@k2b/cloud 0.40.0 → 0.42.0

package/src/ai/store.ts

@@ -1,7 +1,9 @@
 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 CapabilityActionReviewData, CapabilityActionReviewDataSchema } from "../contracts/capabilities";
+import { capabilityRequestHash } from "../capabilities/claims";
+import { restoreReviewSnapshot, serializeReviewSnapshot } from "../capabilities/review-storage";
+import { type CapabilityActionReviewPresentation, CapabilityActionReviewPresentationSchema } 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";
@@ -14,6 +16,13 @@ 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 {
+  compactCapabilityReview,
+  compactReviewMapSql,
+  compactReviewMetaSql,
+  compactStoredReview,
+  storedReviewWithContent,
+} from "./review-content";
 import { AiRunTimeout } from "./run-timeout";
 import { withAiShortId, withAiShortIdForDb } from "./short-id";
 import { parseAiTodoPlan } from "./todo-contracts";
@@ -530,9 +539,9 @@ const parseJsonValue = <T>(value: unknown): T => {
   return value as T;
 };
 
-const parseCapabilityActionReview = (value: unknown): CapabilityActionReviewData | undefined => {
+const parseCapabilityActionReview = (value: unknown): CapabilityActionReviewPresentation | undefined => {
   if (value === null || value === undefined) return undefined;
-  const parsed = CapabilityActionReviewDataSchema.safeParse(parseJsonValue(value));
+  const parsed = CapabilityActionReviewPresentationSchema.safeParse(restoreReviewSnapshot(parseJsonValue(value)));
   return parsed.success ? parsed.data : undefined;
 };
 
@@ -664,6 +673,14 @@ const intValue = (value: number | string | null | undefined): number => Math.max
 
 const rowToMessage = (row: MessageRow): AiStoredMessage => {
   const message = parseJsonValue<Message>(row.message);
+  const meta = row.meta ? parseJsonValue<AiStoredMessage["meta"]>(row.meta) : null;
+  if (meta?.toolReviews)
+    meta.toolReviews = Object.fromEntries(
+      Object.entries(meta.toolReviews).map(([callId, review]) => [
+        callId,
+        compactStoredReview(review, { conversationId: row.conversation_id, turnId: row.loop_id ?? "", callId }),
+      ]),
+    );
   return {
     id: row.id,
     shortId: row.short_id,
@@ -679,7 +696,7 @@ const rowToMessage = (row: MessageRow): AiStoredMessage => {
     loopAggregate: row.loop_aggregate ? parseJsonValue<LoopAggregate>(row.loop_aggregate) : null,
     loopDoneReason: row.loop_done_reason,
     compactedAt: row.compacted_at ? iso(row.compacted_at) : null,
-    meta: row.meta ? parseJsonValue<AiStoredMessage["meta"]>(row.meta) : null,
+    meta,
     feedback:
       Number(row.feedback_rating) === 1 || Number(row.feedback_rating) === -1
         ? {
@@ -733,7 +750,16 @@ const pendingActionToPublicEvent = (row: PendingActionRow): AiPendingTurnAction
         name: row.tool_name,
         args: row.args,
         message: row.message ?? undefined,
-        review: parseCapabilityActionReview(row.review),
+        review: (() => {
+          const review = parseCapabilityActionReview(row.review);
+          return review
+            ? compactCapabilityReview(review, {
+                conversationId: row.conversation_id,
+                turnId: row.turn_id,
+                callId: row.kind === "custom_approval" ? row.call_id.replace(/-approval-[0-9]+$/, "") : row.call_id,
+              })
+            : undefined;
+        })(),
         allowAlways: row.allow_always,
         allowChat: row.allow_always || row.allow_chat === true,
         ...(row.remember_tool_name === AI_WEBSITE_APPROVAL_TOOL ? { website: row.approval_scope } : {}),
@@ -749,7 +775,16 @@ const rowToPendingActionRecord = (row: PendingActionRow): AiPendingTurnActionRec
   name: row.tool_name,
   args: row.args,
   message: row.message ?? undefined,
-  review: parseCapabilityActionReview(row.review),
+  review: (() => {
+    const review = parseCapabilityActionReview(row.review);
+    return review
+      ? compactCapabilityReview(review, {
+          conversationId: row.conversation_id,
+          turnId: row.turn_id,
+          callId: row.kind === "custom_approval" ? row.call_id.replace(/-approval-[0-9]+$/, "") : row.call_id,
+        })
+      : undefined;
+  })(),
   approvalScope: row.approval_scope,
   allowAlways: row.allow_always,
   allowChat: row.allow_always || row.allow_chat === true,
@@ -994,7 +1029,7 @@ const recordAiToolMeta = async (
       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)
+          jsonb_build_object(${input.callId}::text, ${key === "toolReviews" ? serializeReviewSnapshot(value) : JSON.stringify(value)}::text::jsonb)
       )
       WHERE conversation_id = ${input.conversationId}::uuid AND loop_id = ${input.turnId}::text
         AND role = 'assistant'
@@ -1005,8 +1040,16 @@ const recordAiToolMeta = async (
   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 recordAiToolReview = async (input: {
+  conversationId: string;
+  turnId: string;
+  callId: string;
+  review: AiStoredActionReview;
+}): Promise<AiStoredActionReview> => {
+  const stored = storedReviewWithContent(input.review, input);
+  await recordAiToolMeta(input, "toolReviews", stored);
+  return compactStoredReview(stored, input);
+};
 
 export const recordAiToolCheck = (input: { conversationId: string; turnId: string; callId: string; check: AiActionCheck }, db = sql) =>
   recordAiToolMeta(input, "toolChecks", input.check, db);
@@ -1319,11 +1362,45 @@ export const saveAiDraftInTransaction = async (
   };
 };
 
+export class AiConversationCreationError extends Error {
+  constructor(readonly reason: "conflict" | "unavailable") {
+    super(
+      reason === "conflict"
+        ? "This creation request was already used with different input."
+        : "The conversation from this request is no longer available.",
+    );
+  }
+}
+
 export const aiConversations: AiConversationService = {
+  getDraftSubmission: async ({ conversationId, ownerUserId, revision }) => {
+    const [row] = await sql<{ message_id: string; turn_id: string | null }[]>`
+      SELECT message.short_id AS message_id, turn.short_id AS turn_id
+      FROM ai.messages message
+      JOIN ai.conversations conversation ON conversation.id = message.conversation_id
+      LEFT JOIN ai.turns turn ON turn.id::text = message.loop_id AND turn.conversation_id = conversation.id
+      WHERE conversation.id = ${conversationId}::uuid AND conversation.created_by_user_id = ${ownerUserId}::uuid
+        AND conversation.archived_at IS NULL AND message.role = 'user'
+        AND message.meta->>'submittedDraftRevision' = ${String(revision)}
+      LIMIT 1
+    `;
+    return row ? { messageId: row.message_id, turnId: row.turn_id } : null;
+  },
   createConversation: async (input) => {
-    const rows = await withAiShortId(
-      "idx_ai_conversations_short_id",
-      (shortId) => sql<ConversationRow[]>`
+    const normalized = {
+      title: input.title?.trim() || "New chat",
+      description: input.description?.trim() ?? "",
+      projectId: input.projectId ?? null,
+      draft: input.draft ?? [],
+      preloadTools: input.preloadTools ?? [],
+      allowedTools: input.allowedTools ?? null,
+      launchedByAppId: input.launchedByAppId?.trim() || null,
+    };
+    const insert = async (db: SQL) => {
+      const rows = await withAiShortIdForDb(
+        db,
+        "idx_ai_conversations_short_id",
+        (attempt, shortId) => attempt<ConversationRow[]>`
       INSERT INTO ai.conversations (
         short_id,
         title,
@@ -1339,8 +1416,8 @@ export const aiConversations: AiConversationService = {
       )
       SELECT
         ${shortId},
-        ${input.title?.trim() || "New chat"},
-        ${input.description?.trim() ?? ""},
+        ${normalized.title},
+        ${normalized.description},
         ${input.projectId ?? null}::uuid,
         ${JSON.stringify(input.draft ?? [])}::text::jsonb,
         ${input.draft?.length ? 1 : 0},
@@ -1352,10 +1429,38 @@ export const aiConversations: AiConversationService = {
       WHERE ${input.projectId ?? null}::uuid IS NULL
          OR EXISTS (SELECT 1 FROM ai.projects project WHERE project.id = ${input.projectId ?? null}::uuid)
       RETURNING *
-    `,
-    );
-    if (!rows[0]) throw new Error("Project does not exist.");
-    return rowToConversation(rows[0]);
+      `,
+      );
+      if (!rows[0]) throw new Error("Project does not exist.");
+      return rowToConversation(rows[0]);
+    };
+    if (!input.requestId) return insert(sql);
+    const hash = capabilityRequestHash(normalized);
+    return sql.begin(async (tx) => {
+      const reserved = await tx<{ request_id: string }[]>`
+        INSERT INTO ai.conversation_creations (owner_user_id, request_id, input_hash)
+        VALUES (${input.ownerUserId}::uuid, ${input.requestId}::uuid, ${hash})
+        ON CONFLICT (owner_user_id, request_id) DO NOTHING RETURNING request_id
+      `;
+      const [claim] = await tx<{ input_hash: string; conversation_id: string | null }[]>`
+        SELECT input_hash, conversation_id FROM ai.conversation_creations
+        WHERE owner_user_id = ${input.ownerUserId}::uuid AND request_id = ${input.requestId}::uuid
+        FOR UPDATE
+      `;
+      if (!claim || claim.input_hash !== hash) throw new AiConversationCreationError("conflict");
+      if (!reserved.length) {
+        const [existing] = await tx<ConversationRow[]>`
+          SELECT * FROM ai.conversations WHERE id = ${claim.conversation_id}::uuid
+            AND created_by_user_id = ${input.ownerUserId}::uuid AND archived_at IS NULL
+        `;
+        if (!existing) throw new AiConversationCreationError("unavailable");
+        return rowToConversation(existing);
+      }
+      const conversation = await insert(tx);
+      await tx`UPDATE ai.conversation_creations SET conversation_id = ${conversation.id}::uuid
+        WHERE owner_user_id = ${input.ownerUserId}::uuid AND request_id = ${input.requestId}::uuid`;
+      return conversation;
+    });
   },
 
   forkConversation: async (input) => {
@@ -2442,7 +2547,10 @@ export const aiConversations: AiConversationService = {
     // summaries are hidden. The active summary sorts after archived rows
     // sharing its checkpoint seq, marking where the model context begins.
     const rows = await sql<MessageRow[]>`
-      SELECT *
+      SELECT id, short_id, conversation_id, seq, kind, message, loop_id, model_profile_id, provider_model,
+        usage, stop_reason, loop_aggregate, loop_done_reason, compacted_at, created_at,
+        feedback_rating, feedback_reasons, feedback_comment, feedback_updated_at,
+        ${compactReviewMetaSql(todoMetaJson())} AS meta
       FROM ai.messages
       WHERE conversation_id = ${input.conversationId}
         AND NOT (kind = 'summary' AND compacted_at IS NOT NULL)
@@ -2467,7 +2575,10 @@ export const aiConversations: AiConversationService = {
         ORDER BY seq DESC
         LIMIT ${limit}
       )
-      SELECT *
+      SELECT id, short_id, conversation_id, seq, kind, message, loop_id, model_profile_id, provider_model,
+        usage, stop_reason, loop_aggregate, loop_done_reason, compacted_at, created_at,
+        feedback_rating, feedback_reasons, feedback_comment, feedback_updated_at,
+        ${compactReviewMetaSql(todoMetaJson())} AS meta
       FROM ai.messages
       WHERE conversation_id = ${input.conversationId}
         AND seq IN (SELECT seq FROM page_seqs)
@@ -2496,7 +2607,10 @@ export const aiConversations: AiConversationService = {
     const pattern = `%${query.toLowerCase()}%`;
     const rows = await sql<(MessageRow & { page_rank: number | string })[]>`
       WITH matching AS (
-        SELECT *, DENSE_RANK() OVER (ORDER BY seq DESC) AS page_rank
+        SELECT id, short_id, conversation_id, seq, kind, message, loop_id, model_profile_id, provider_model,
+        usage, stop_reason, loop_aggregate, loop_done_reason, compacted_at, created_at,
+        feedback_rating, feedback_reasons, feedback_comment, feedback_updated_at,
+        ${compactReviewMetaSql(todoMetaJson())} AS meta, DENSE_RANK() OVER (ORDER BY seq DESC) AS page_rank
         FROM ai.messages
         WHERE conversation_id = ${input.conversationId}::uuid
           AND role <> 'tool_result'
@@ -2620,7 +2734,10 @@ export const aiConversations: AiConversationService = {
 
   listContextMessages: async (input) => {
     const rows = await sql<MessageRow[]>`
-      SELECT *
+      SELECT id, short_id, conversation_id, seq, kind, message, loop_id, model_profile_id, provider_model,
+        usage, stop_reason, loop_aggregate, loop_done_reason, compacted_at, created_at,
+        feedback_rating, feedback_reasons, feedback_comment, feedback_updated_at,
+        ${compactReviewMetaSql(todoMetaJson())} AS meta
       FROM ai.messages
       WHERE conversation_id = ${input.conversationId}
         AND compacted_at IS NULL
@@ -2631,7 +2748,10 @@ export const aiConversations: AiConversationService = {
 
   listTurnMessages: async (input) => {
     const rows = await sql<MessageRow[]>`
-      SELECT *
+      SELECT id, short_id, conversation_id, seq, kind, message, loop_id, model_profile_id, provider_model,
+        usage, stop_reason, loop_aggregate, loop_done_reason, compacted_at, created_at,
+        feedback_rating, feedback_reasons, feedback_comment, feedback_updated_at,
+        ${compactReviewMetaSql(todoMetaJson())} AS meta
       FROM (SELECT * FROM ai.messages UNION ALL SELECT * FROM ai.task_messages) messages
       WHERE conversation_id = ${input.conversationId}
         AND loop_id = ${input.loopId}
@@ -3042,7 +3162,7 @@ export const aiConversations: AiConversationService = {
     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
+        SELECT ${compactReviewMapSql(sql`meta->'toolReviews'`)} AS tool_reviews, meta->'toolChecks' AS tool_checks
         FROM (
           SELECT meta, seq, conversation_id, loop_id, role FROM ai.messages
           UNION ALL
@@ -3062,7 +3182,8 @@ export const aiConversations: AiConversationService = {
       turn: rowToTurn(rows[0]),
       liveBlocks: rowToLiveBlocks(rows[0]).map((block) => {
         if (block.kind !== "tool") return block;
-        const review = reviews.get(block.callId);
+        const snapshot = reviews.get(block.callId);
+        const review = snapshot ? compactStoredReview(snapshot, { ...input, turnId: rows[0]!.id, callId: block.callId }) : undefined;
         const check = checks.get(block.callId);
         return { ...block, ...(review ? { review } : {}), ...(check ? { check } : {}) };
       }),
@@ -3546,7 +3667,7 @@ export const aiConversations: AiConversationService = {
         ${input.name},
         ${JSON.stringify(input.args ?? null)}::text::jsonb,
         ${input.message ?? null},
-        ${input.review ? JSON.stringify(input.review) : null}::text::jsonb,
+        ${input.review ? serializeReviewSnapshot("sentence" in input.review ? storedReviewWithContent(input.review, input) : input.review) : null}::text::jsonb,
         ${input.approvalScope},
         ${input.allowAlways},
         ${input.allowChat ?? input.allowAlways},
@@ -3574,7 +3695,8 @@ export const aiConversations: AiConversationService = {
 
   listPendingTurnActions: async (input) => {
     const rows = await sql<PendingActionRow[]>`
-      SELECT *
+      SELECT approval_id, turn_id, conversation_id, call_id, kind, status, tool_name, args, message,
+        review - 'content' AS review, approval_scope, allow_always, allow_chat, remember_tool_name, frontend_mode, resolved_event
       FROM ai.pending_actions
       WHERE conversation_id = ${input.conversationId}
         AND turn_id = ${input.turnId}
@@ -3586,7 +3708,8 @@ export const aiConversations: AiConversationService = {
 
   getPendingTurnAction: async (input) => {
     const rows = await sql<PendingActionRow[]>`
-      SELECT *
+      SELECT approval_id, turn_id, conversation_id, call_id, kind, status, tool_name, args, message,
+        review - 'content' AS review, approval_scope, allow_always, allow_chat, remember_tool_name, frontend_mode, resolved_event
       FROM ai.pending_actions
       WHERE conversation_id = ${input.conversationId}
         AND turn_id = ${input.turnId}
@@ -3607,9 +3730,34 @@ 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 ${compactReviewMapSql(sql`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 ?? {}).map(
+          ([callId, review]) => [callId, compactStoredReview(review, { ...input, callId })] as const,
+        ),
+      ),
+    );
+  },
+
   listPendingActionRecords: async (input) => {
     const rows = await sql<PendingActionRow[]>`
-      SELECT *
+      SELECT approval_id, turn_id, conversation_id, call_id, kind, status, tool_name, args, message,
+        review - 'content' AS review, approval_scope, allow_always, allow_chat, remember_tool_name, frontend_mode, resolved_event
       FROM ai.pending_actions
       WHERE conversation_id = ${input.conversationId}
         AND turn_id = ${input.turnId}
@@ -3621,7 +3769,8 @@ export const aiConversations: AiConversationService = {
 
   listResolvedPendingActions: async (input) => {
     const rows = await sql<PendingActionRow[]>`
-      SELECT *
+      SELECT approval_id, turn_id, conversation_id, call_id, kind, status, tool_name, args, message,
+        review - 'content' AS review, approval_scope, allow_always, allow_chat, remember_tool_name, frontend_mode, resolved_event
       FROM ai.pending_actions
       WHERE conversation_id = ${input.conversationId}
         AND turn_id = ${input.turnId}
@@ -3785,7 +3934,11 @@ export const aiConversations: AiConversationService = {
       const rows = input.turnId
         ? (
             await sql<MessageRow[]>`
-            SELECT * FROM ai.messages
+            SELECT id, short_id, conversation_id, seq, kind, message, loop_id, model_profile_id, provider_model,
+              usage, stop_reason, loop_aggregate, loop_done_reason, compacted_at, created_at,
+              feedback_rating, feedback_reasons, feedback_comment, feedback_updated_at,
+              ${compactReviewMetaSql(todoMetaJson())} AS meta
+            FROM ai.messages
             WHERE conversation_id = ${input.conversationId}::uuid AND compacted_at IS NULL
               AND ${visibleToTurn(input.turnId)}
             ORDER BY seq ASC

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