@k2b/cloud 0.30.0 → 0.31.0

package/src/ai/executor.ts

@@ -3,6 +3,7 @@ import { compact, nessi } from "@k2b/nessi";
 import { listCapabilities } from "../_internal/registry";
 import type { CapabilityActionReview } from "../contracts/capabilities";
 import type { AccessSubject, RequestActor } from "../server";
+import { approvalAssurance, approvalScopeFromToolName, approvals } from "../services/approvals";
 import { createHelpReader } from "../services/help";
 import { logger } from "../services/logging";
 import { getMandate } from "../services/mandates";
@@ -10,6 +11,7 @@ import type { MandatePolicyV1 } from "../services/mandates/policy";
 import { coreSettings } from "../services/settings/api";
 import { normalizeLocale } from "../shared/locale";
 import {
+  AI_WEBSITE_APPROVAL_TOOL,
   type AiToolApprovalContext,
   aiToolAllowsAlways,
   aiToolApprovalScope,
@@ -55,13 +57,13 @@ import { isAiVisionModelConfigured, type resolveAiModel } from "./settings";
 import { selectAiSkillCatalog } from "./skill-catalog";
 import { createCloudAiLoadSkillTool, createCloudAiSearchSkillsTool, loadSelectedAiSkills } from "./skill-tool";
 import { aiSkills } from "./skills";
-import { aiConversations } from "./store";
+import { aiConversations, recordAiWebsiteReceipts } from "./store";
 import { AI_LIVE_SNAPSHOT_INTERVAL_MS, publishAiWireEvent } from "./stream";
 import { composeAiSystemPrompt } from "./system-prompt";
 import { aiToolAudit } from "./tool-audit";
 import { acceptCanonicalToolNames } from "./tool-call-names";
 import { resolveAiToolResultMaxChars } from "./tool-result-budget";
-import { aiToolPromptHints, type PreparedAiTools, prepareAiTools } from "./tools";
+import { type AiApprovalUse, aiApprovalAskedLater, aiToolPromptHints, type PreparedAiTools, prepareAiTools } from "./tools";
 import { AiTranscriptionError } from "./transcription";
 import {
   AiTurnFailure,
@@ -75,6 +77,7 @@ import { type AiTurnGuidance, loadAiTurnGuidance } from "./turn-guidance";
 import { type AiTurnPolicyToolCall, applyAiTurnPolicy } from "./turn-policy";
 import { createTurnTimingRecorder, withDurableTurnTiming } from "./turn-timing";
 import type {
+  AiApprovalTarget,
   AiChatTurnRunConfig,
   AiFrontendToolMode,
   AiPendingTurnActionRecord,
@@ -85,6 +88,7 @@ import type {
   AiTurnFinalizedEvent,
   AiTurnRunConfig,
   AiTurnSteer,
+  AiWebsiteReceipt,
 } from "./types";
 import { isAiImageMediaType } from "./types";
 import { validateAiTurnRequest } from "./validate";
@@ -296,7 +300,15 @@ const rebuildBlocksFromMessages = (
         callId: action.callId,
         status: action.kind === "client_tool" ? "awaiting_client" : "awaiting_approval",
         approval:
-          action.kind === "client_tool" ? undefined : { message: action.message, review: action.review, allowAlways: action.allowAlways },
+          action.kind === "client_tool"
+            ? undefined
+            : {
+                message: action.message,
+                review: action.review,
+                allowAlways: action.allowAlways,
+                allowChat: action.allowChat ?? action.allowAlways,
+                ...(action.rememberToolName === AI_WEBSITE_APPROVAL_TOOL ? { website: action.approvalScope } : {}),
+              },
         frontendMode: action.frontendMode,
       };
     }
@@ -381,9 +393,25 @@ const approvalReviewForCallId = (
  */
 const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowRememberedApprovals = true) => {
   const toolBlocks = new Map<string, Extract<AiTurnBlock, { kind: "tool" }>>();
+  /** Website receipts by the call that shows them and their index; every later state of that call keeps them. */
+  const receiptsByCall = new Map<string, Map<number, { method: string; url: string }>>();
   for (const block of seedBlocks) {
-    if (block.kind === "tool") toolBlocks.set(block.callId, block);
+    if (block.kind !== "tool") continue;
+    toolBlocks.set(block.callId, block);
+    // A pending nested approval shows on its parent call's block; receipts belong to that block.
+    const shownCallId = block.id === toolBlockId(block.callId) ? block.callId : (customApprovalParentCallId(block.callId) ?? block.callId);
+    if (block.receipts?.length) receiptsByCall.set(shownCallId, new Map(block.receipts.map((receipt, index) => [index, receipt])));
   }
+  const receiptsOf = (callId: string) => {
+    const receipts = receiptsByCall.get(callId);
+    return receipts ? [...receipts].sort(([a], [b]) => a - b).map(([, receipt]) => receipt) : undefined;
+  };
+  const addReceipts = (callId: string, receipts: AiWebsiteReceipt[]) => {
+    const known = receiptsByCall.get(callId) ?? new Map<number, { method: string; url: string }>();
+    for (const { index, method, url } of receipts) known.set(index, { method, url });
+    receiptsByCall.set(callId, known);
+    return receiptsOf(callId) ?? [];
+  };
   /** Real frontend mode per tool name — set once the turn's tools are prepared.
    *  Getting this wrong is not cosmetic: the client auto-resolves plain "client"
    *  blocks, so a mislabeled client_interaction tool (survey) would be answered
@@ -408,6 +436,10 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
   const setApprovalPolicies = (items: PreparedAiTools["approvalPolicies"]) => {
     approvalPolicies = items;
   };
+  let approvalTargets: ReadonlyMap<string, AiApprovalTarget> = new Map();
+  const setApprovalTargets = (items: ReadonlyMap<string, AiApprovalTarget>) => {
+    approvalTargets = items;
+  };
   let rejectedCallIds = new Set<string>();
   const setRejectedCallIds = (items: Set<string>) => {
     rejectedCallIds = items;
@@ -435,10 +467,11 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
       status: patch.status ?? existing?.status ?? "running",
       result: "result" in patch ? patch.result : existing?.result,
       isError: "isError" in patch ? patch.isError : existing?.isError,
-      approval: approval && !allowRememberedApprovals ? { ...approval, allowAlways: false } : approval,
+      approval: approval && !allowRememberedApprovals ? { ...approval, allowAlways: false, allowChat: false } : approval,
       frontendMode: patch.frontendMode ?? existing?.frontendMode,
       presentation: patch.presentation ?? existing?.presentation ?? presentations.get(rawName) ?? presentations.get(name),
       ...(approvedCallIds.has(callId) || approvedCallIds.has(displayCallId) || existing?.approved ? { approved: true } : {}),
+      ...(receiptsOf(displayCallId) ? { receipts: receiptsOf(displayCallId) } : {}),
     };
     toolBlocks.set(callId, block);
     return { type: "block_set", block };
@@ -484,6 +517,10 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
       case "tool_action_request":
         const displayCallId = event.kind === "custom_approval" ? (customApprovalParentCallId(event.callId) ?? event.callId) : event.callId;
         const review = approvalReviewForCallId(approvalReviews, event.callId);
+        const target = event.kind === "custom_approval" ? approvalTargets.get(event.callId) : undefined;
+        const allowAlways = target
+          ? target.always
+          : review?.approvalScope !== undefined || aiToolAllowsAlways(approvalPolicies.get(event.name));
         return [
           setTool(
             event.callId,
@@ -497,7 +534,9 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
                   : {
                       message: event.message,
                       review,
-                      allowAlways: review?.approvalScope !== undefined || aiToolAllowsAlways(approvalPolicies.get(event.name)),
+                      allowAlways,
+                      allowChat: target !== undefined || allowAlways,
+                      ...(target?.toolName === AI_WEBSITE_APPROVAL_TOOL ? { website: target.approvalScope } : {}),
                     },
               frontendMode: event.kind === "client_tool" ? (frontendModes.get(event.name) ?? "client") : undefined,
             },
@@ -542,8 +581,10 @@ const createEventMapper = (attempt: number, seedBlocks: AiTurnBlock[], allowReme
     setCanonicalNames,
     setApprovalPolicies,
     setApprovalReviews,
+    setApprovalTargets,
     setRejectedCallIds,
     setApprovedCallIds,
+    addReceipts,
   };
 };
 
@@ -900,9 +941,13 @@ export class AiTurnExecutor {
       });
     }
 
+    const approvalTargets = new Map<string, AiApprovalTarget>();
+    const linkedApprovals = new Map<string, string>();
+    const freshApprovalRequired = new Set<string>();
     const dynamicToolRuntimeContext = {
       turnId,
       reportToolProgress: (callId: string, message: string) => pipeline.reportToolProgress(callId, message),
+      reportWebsiteReceipts: (callId: string, receipts: AiWebsiteReceipt[]) => pipeline.reportWebsiteReceipts(callId, receipts),
       attachedFilePaths: new Set(config.files?.attached.map((file) => file.path) ?? []),
       allowedDataBoundaries: material.modelPolicy?.allowedDataBoundaries,
       projectFiles,
@@ -910,6 +955,35 @@ export class AiTurnExecutor {
       selectedModel: resolved,
       locale: promptLocale,
       timeZone,
+      linkApproval: (approvalCallId: string, approvalId: string) => {
+        linkedApprovals.set(approvalCallId, approvalId);
+      },
+      consumeApproval: async (approvalCallId: string, input: unknown): Promise<AiApprovalUse> => {
+        const pending = await aiConversations.getPendingTurnAction({ conversationId, turnId, callId: approvalCallId });
+        if (!pending?.approvalId) return "approved";
+        const result = await approvals.consume(pending.approvalId, {
+          input,
+          review: approvalReviewForCallId(capabilityActionReviews, approvalCallId) ?? null,
+          requester: { kind: "assistant_turn", ref: `${turnId}/${approvalCallId}` },
+        });
+        if (result.ok) return "approved";
+        if (result.code === "ALREADY_CONSUMED") {
+          // A later question of the same call proves this run resumes after it, not after a crash during the effect.
+          const [open, resolved] = await Promise.all([
+            aiConversations.listPendingActionRecords({ conversationId, turnId }),
+            aiConversations.listResolvedPendingActions({ conversationId, turnId }),
+          ]);
+          return aiApprovalAskedLater(
+            approvalCallId,
+            [...open, ...resolved].map((action) => action.callId),
+          )
+            ? "approved"
+            : "used";
+        }
+        freshApprovalRequired.add(customApprovalParentCallId(approvalCallId) ?? approvalCallId);
+        return "changed";
+      },
+      describeApproval: (approvalCallId: string, target: AiApprovalTarget) => approvalTargets.set(approvalCallId, target),
     };
     const prepared = prepareAiTools({
       tools: activeTools,
@@ -920,6 +994,7 @@ export class AiTurnExecutor {
     let backgroundError: string | null = null;
     const rememberableCapabilityApprovals = new Map<string, string>();
     const capabilityActionReviews = new Map<string, CapabilityActionReview>();
+    pipeline.setApprovalTargets(approvalTargets);
     pipeline.setFrontendModes(prepared.frontendModes);
     pipeline.setCanonicalNames(prepared.canonicalNames);
     pipeline.setApprovalPolicies(prepared.approvalPolicies);
@@ -1332,6 +1407,9 @@ export class AiTurnExecutor {
       allowRememberedApprovals: aiTurnAllowsRememberedApprovals(config),
       rememberableCapabilityApprovals,
       capabilityActionReviews,
+      approvalTargets,
+      linkedApprovals,
+      freshApprovalRequired,
       appliedSteers,
       noteToolRound: turnPolicy.noteToolRound,
       noteToolCall: turnPolicy.noteToolCall,
@@ -1401,6 +1479,9 @@ export class AiTurnExecutor {
     allowRememberedApprovals: boolean;
     rememberableCapabilityApprovals: ReadonlyMap<string, string>;
     capabilityActionReviews: ReadonlyMap<string, CapabilityActionReview>;
+    approvalTargets: ReadonlyMap<string, AiApprovalTarget>;
+    linkedApprovals: ReadonlyMap<string, string>;
+    freshApprovalRequired?: ReadonlySet<string>;
     appliedSteers: AiTurnSteer[];
     noteToolRound: () => void;
     noteToolCall: (call: AiTurnPolicyToolCall) => void;
@@ -1423,6 +1504,7 @@ export class AiTurnExecutor {
       allowRememberedApprovals,
       rememberableCapabilityApprovals,
       capabilityActionReviews,
+      approvalTargets,
       appliedSteers,
       noteToolRound,
       noteToolCall,
@@ -1446,6 +1528,9 @@ export class AiTurnExecutor {
             allowRememberedApprovals,
             rememberableCapabilityApprovals,
             capabilityActionReviews,
+            approvalTargets,
+            linkedApprovals: input.linkedApprovals,
+            freshApprovalRequired: input.freshApprovalRequired,
             onBackgroundBlocked: input.onBackgroundBlocked,
           });
           if (suspended) {
@@ -1549,6 +1634,9 @@ export class AiTurnExecutor {
     allowRememberedApprovals: boolean;
     rememberableCapabilityApprovals: ReadonlyMap<string, string>;
     capabilityActionReviews: ReadonlyMap<string, CapabilityActionReview>;
+    approvalTargets: ReadonlyMap<string, AiApprovalTarget>;
+    linkedApprovals: ReadonlyMap<string, string>;
+    freshApprovalRequired?: ReadonlySet<string>;
     onBackgroundBlocked?: (message: string) => void;
   }): Promise<boolean> {
     const {
@@ -1562,6 +1650,7 @@ export class AiTurnExecutor {
       allowRememberedApprovals,
       rememberableCapabilityApprovals,
       capabilityActionReviews,
+      approvalTargets,
     } = input;
     const approvalPolicy = prepared.approvalPolicies.get(event.name);
     const toolName = prepared.canonicalNames.get(event.name) ?? event.name;
@@ -1571,8 +1660,13 @@ export class AiTurnExecutor {
       event.kind === "custom_approval"
         ? rememberableCapabilityApprovals.get(customApprovalParentCallId(event.callId) ?? event.callId)
         : undefined;
-    const approvalScope = capabilityApprovalScope ?? aiToolApprovalScope(toolName, approvalPolicy);
-    const allowAlways = allowRememberedApprovals && (capabilityApprovalScope !== undefined || aiToolAllowsAlways(approvalPolicy));
+    // A tool that names what it asks for (a code run's HTTP request or Action, a web page to read) already looked up
+    // its own remembered approvals under its own rules; the approval is remembered for that target, not the tool.
+    const target = event.kind === "custom_approval" ? approvalTargets.get(event.callId) : undefined;
+    const approvalScope = target?.approvalScope ?? capabilityApprovalScope ?? aiToolApprovalScope(toolName, approvalPolicy);
+    const allowAlways =
+      allowRememberedApprovals && (target ? target.always : capabilityApprovalScope !== undefined || aiToolAllowsAlways(approvalPolicy));
+    const allowChat = allowRememberedApprovals && (target !== undefined || allowAlways);
 
     // Display-only client_view tools (cards, charts) need neither a browser nor input: Cloud answers them itself, in
     // background runs too, whose transcript shows them later. The block goes from running straight to completed:
@@ -1609,8 +1703,15 @@ export class AiTurnExecutor {
     }
 
     // Remembered approvals resolve inline too.
-    if (event.kind !== "client_tool" && allowAlways && approvalContext) {
-      const remembered = await hasRememberedAiToolApproval(approvalContext, { toolName, approvalScope }).catch(() => false);
+    if (
+      event.kind !== "client_tool" &&
+      !target &&
+      allowAlways &&
+      approvalContext &&
+      // A stale decided snapshot needs another human decision, even if the first response also remembered it.
+      !input.freshApprovalRequired?.has(customApprovalParentCallId(event.callId) ?? event.callId)
+    ) {
+      const remembered = await hasRememberedAiToolApproval(approvalContext, { toolName, approvalScope, conversationId }).catch(() => false);
       if (remembered) {
         await aiToolAudit
           .noteApprovalResolved({ turnId, callId: event.callId, approvalState: "approved_by_preference" })
@@ -1620,7 +1721,40 @@ export class AiTurnExecutor {
       }
     }
 
+    const review = event.kind === "custom_approval" ? approvalReviewForCallId(capabilityActionReviews, event.callId) : undefined;
+    let approvalId: string | undefined;
+    let presented = event;
+    if (event.kind !== "client_tool") {
+      const conversation = await aiConversations.getConversation({ conversationId });
+      const owner = conversation?.createdByUserId;
+      if (!owner) throw new Error("Approval requires a conversation owner");
+      const linked = input.linkedApprovals.get(event.callId);
+      if (linked) {
+        const record = await approvals.get(linked);
+        if (!record || record.status !== "pending" || record.requesterKind !== "studio_app" || record.approverUserId !== owner)
+          throw new Error("Approval does not belong to an open Studio request of the conversation owner");
+        approvalId = linked;
+        // The card shows the question the effect's own record holds, never the text the relay sent.
+        presented = { ...event, message: record.sentence };
+      } else {
+        const record = await approvals.request({
+          ...approvalScopeFromToolName(toolName),
+          approvalScope,
+          requester: { kind: "assistant_turn", ref: `${turnId}/${event.callId}`, appId: "assistant", title: conversation.title },
+          subjectId: owner,
+          approverUserId: owner,
+          assurance: approvalAssurance(target !== undefined || capabilityApprovalScope !== undefined || aiToolAllowsAlways(approvalPolicy)),
+          sentence: event.message ?? toolName,
+          review,
+          input: event.args,
+          expiresInMs: AI_ACTION_BUDGET_MS,
+        });
+        if (!record.ok) throw new Error("This approval was already decided or has expired.");
+        approvalId = record.id;
+      }
+    }
     await aiConversations.savePendingTurnAction({
+      approvalId,
       turnId,
       conversationId,
       callId: event.callId,
@@ -1628,10 +1762,12 @@ export class AiTurnExecutor {
       status: "pending",
       name: toolName,
       args: event.args,
-      message: event.message,
-      review: event.kind === "custom_approval" ? approvalReviewForCallId(capabilityActionReviews, event.callId) : undefined,
+      message: presented.message,
+      review,
       approvalScope,
       allowAlways,
+      allowChat,
+      ...(target ? { rememberToolName: target.toolName } : {}),
       frontendMode,
       resolvedEvent: null,
     });
@@ -1653,7 +1789,7 @@ export class AiTurnExecutor {
         .catch(() => undefined);
     }
 
-    await pipeline.apply(event);
+    await pipeline.apply(presented);
     const suspended = await aiConversations.suspendTurn({
       conversationId,
       turnId,
@@ -1871,7 +2007,9 @@ class StreamPipeline {
     this.blocks = this.allowRememberedApprovals
       ? blocks
       : blocks.map((block) =>
-          block.kind === "tool" && block.approval ? { ...block, approval: { ...block.approval, allowAlways: false } } : block,
+          block.kind === "tool" && block.approval
+            ? { ...block, approval: { ...block.approval, allowAlways: false, allowChat: false } }
+            : block,
         );
   }
 
@@ -1895,6 +2033,10 @@ class StreamPipeline {
     this.mapper.setApprovalPolicies(policies);
   }
 
+  setApprovalTargets(targets: ReadonlyMap<string, AiApprovalTarget>): void {
+    this.mapper.setApprovalTargets(targets);
+  }
+
   setRejectedCallIds(callIds: Set<string>): void {
     this.mapper.setRejectedCallIds(callIds);
   }
@@ -1950,6 +2092,20 @@ class StreamPipeline {
     await this.maybeSnapshot();
   }
 
+  /**
+   * Shows requests a website approval let through on the call's block, and records them on its message before they go
+   * out, so the chat keeps each receipt and its revoke action whether the call succeeds, fails, or the turn stops.
+   */
+  async reportWebsiteReceipts(callId: string, receipts: AiWebsiteReceipt[]): Promise<void> {
+    if (!receipts.length) return;
+    await recordAiWebsiteReceipts({ conversationId: this.conversationId, turnId: this.turnId, callId, receipts });
+    const merged = this.mapper.addReceipts(callId, receipts);
+    const block = this.blocks.find((block) => block.kind === "tool" && block.id === toolBlockId(callId));
+    if (block?.kind !== "tool") return;
+    await this.emitOp({ type: "block_set", block: { ...block, receipts: merged } });
+    await this.maybeSnapshot();
+  }
+
   async reportToolProgress(callId: string, progress: string): Promise<void> {
     const block = this.blocks.find((block) => block.kind === "tool" && block.callId === callId);
     if (!block || block.kind !== "tool" || block.progress === progress) return;

package/src/ai/fetch-file-tool.ts

@@ -3,6 +3,7 @@ import { type RequestOptions as HttpsRequestOptions, request as httpsRequest } f
 import { z } from "zod";
 import { type PublicNetworkAddress, resolvePublicNetworkAddresses } from "../services/network-security";
 import { AI_FILES_MAX_FILE_BYTES_DEFAULT, aiFileStore, guessAiMediaType, normalizeAiFilePath } from "./files-store";
+import { authorizeWebRead } from "./firecrawl-tools";
 import { defineAiTool } from "./tools";
 
 const FETCH_FILE_MAX_REDIRECTS = 5;
@@ -225,9 +226,12 @@ const responseLocation = (headers: IncomingHttpHeaders): string | null => {
   return typeof value === "string" && value.trim() ? value : null;
 };
 
+/** How a download that a website approval let through may proceed: only on that origin, each request shown first. */
+type WebsiteApprovedDownload = { origin: string; onRequest: (url: URL, hop: number) => Promise<void> };
+
 export const downloadPublicFile = async (
   rawUrl: string,
-  options: FetchFileDependencies & { maxBytes?: number; signal?: AbortSignal } = {},
+  options: FetchFileDependencies & { maxBytes?: number; signal?: AbortSignal; approvedWebsite?: WebsiteApprovedDownload } = {},
 ): Promise<{ bytes: Uint8Array; headers: IncomingHttpHeaders; url: URL }> => {
   const resolve = options.resolve ?? resolvePublicNetworkAddresses;
   const perform =
@@ -238,6 +242,14 @@ export const downloadPublicFile = async (
   let url = publicHttpsUrl(rawUrl);
 
   for (let redirects = 0; redirects <= FETCH_FILE_MAX_REDIRECTS; redirects++) {
+    if (options.approvedWebsite) {
+      // A website approval covers its own origin only; an open redirect must not carry the address to another one.
+      if (url.origin !== options.approvedWebsite.origin)
+        throw new Error(
+          `Redirect to another website — The file moved to ${url.toString()}, which this chat has not allowed. Download that address directly so the person can decide.`,
+        );
+      await options.approvedWebsite.onRequest(url, redirects);
+    }
     const addresses = await resolveFileAddresses(resolve, url.hostname);
     const response = await perform(url, addresses, { maxBytes, signal: options.signal });
     if (response.statusCode >= 300 && response.statusCode < 400) {
@@ -280,11 +292,15 @@ const responseMediaType = (headers: IncomingHttpHeaders, path: string): string =
 
 export const runCloudAiFetchFile = async (
   input: z.infer<typeof CloudAiFetchFileInputSchema>,
-  context: { conversationId?: string; signal?: AbortSignal },
+  context: { conversationId?: string; signal?: AbortSignal; approvedWebsite?: WebsiteApprovedDownload },
   dependencies: FetchFileDependencies = {},
 ): Promise<z.infer<typeof CloudAiFetchFileOutputSchema>> => {
   if (!context.conversationId) throw new Error("The fetch_file tool needs a conversation context.");
-  const downloaded = await downloadPublicFile(input.url, { ...dependencies, signal: context.signal });
+  const downloaded = await downloadPublicFile(input.url, {
+    ...dependencies,
+    signal: context.signal,
+    approvedWebsite: context.approvedWebsite,
+  });
   const path = normalizeAiFilePath(`/imports/${safeFilename(input.filename, downloaded.url)}`);
   if (!path) throw new Error("Could not derive a valid conversation file path.");
   const stat = await aiFileStore.createAssistantFile({
@@ -307,7 +323,28 @@ export const createCloudAiFetchFileTool = (dependencies: FetchFileDependencies =
     timeoutMs: 90_000,
     promptHint:
       "fetch an exact public HTTPS source file into the chat when the user provides a file link; inspect it with read_file or view_image and present it when useful.",
-  }).server((input, context) => runCloudAiFetchFile(input, context, dependencies));
+  }).server(async (input, context) => {
+    const url = publicHttpsUrl(input.url);
+    const allowedForChat = await authorizeWebRead("file", url.toString(), context);
+    return runCloudAiFetchFile(
+      input,
+      {
+        ...context,
+        ...(allowedForChat
+          ? {
+              approvedWebsite: {
+                origin: url.origin,
+                // The first request's receipt is already shown; each redirect on the same website adds one.
+                onRequest: async (next: URL, hop: number) => {
+                  if (hop > 0) await context.reportWebsiteReceipts?.([{ index: hop, method: "GET", url: next.toString() }]);
+                },
+              },
+            }
+          : {}),
+      },
+      dependencies,
+    );
+  });
 
 export type CloudAiFetchFileInput = z.infer<typeof CloudAiFetchFileInputSchema>;
 export type CloudAiFetchFileOutput = z.infer<typeof CloudAiFetchFileOutputSchema>;

package/src/ai/firecrawl-tools.ts

@@ -1,8 +1,13 @@
 import { isIP } from "node:net";
-import { truncateMiddle } from "@k2b/nessi";
+import { type ToolContext, truncateMiddle } from "@k2b/nessi";
 import { z } from "zod";
+import type { RequestActor } from "../server";
 import { coreSettings } from "../services";
+import { AI_WEBSITE_APPROVAL_TOOL, aiTurnAllowsWebsiteApprovals, aiWebsiteApprovalScope, findRememberedAiToolApproval } from "./approvals";
+import { aiConversations } from "./store";
 import { defineAiTool } from "./tools";
+import type { AiApprovalTarget, AiWebsiteReceipt } from "./types";
+import { hasWebAddressProvenance, recordWebAddresses, webAddressesIn } from "./web-provenance";
 
 export const AI_FIRECRAWL_API_KEY_SETTING_KEY = "ai.firecrawl_api_key";
 
@@ -274,13 +279,70 @@ export const createCloudAiWebSearchTool = (config: FirecrawlToolConfig = {}) =>
         ...result,
         snippet: truncateSnippet(result.snippet),
       })),
-  }).server(async (input, ctx) => runCloudAiWebSearch(input, { ...config, signal: ctx.signal }));
+  }).server(async (input, ctx) => {
+    const results = await runCloudAiWebSearch(input, { ...config, signal: ctx.signal });
+    if (ctx.conversationId)
+      await recordWebAddresses(
+        ctx.conversationId,
+        results.flatMap((result) => [...webAddressesIn(result.url)]),
+      );
+    return results;
+  });
+
+const webReadApprovalMessage = (kind: "page" | "file", url: string, locale: string | undefined) =>
+  locale?.startsWith("de")
+    ? [
+        `${kind === "page" ? "Webseite lesen" : "Datei laden"}: ${url}`,
+        "Diese Adresse steht nicht in deiner Nachricht, in einem Suchergebnis oder als Link einer gelesenen Seite.",
+        "Die vollständige Adresse geht an die Website.",
+      ].join("\n")
+    : [
+        `${kind === "page" ? "Read web page" : "Download file"}: ${url}`,
+        "This address is not in your message, in a search result, or linked from a page read earlier.",
+        "The full address goes to the website.",
+      ].join("\n");
+
+export type WebReadContext = Pick<ToolContext, "requestApproval"> & {
+  actor: RequestActor;
+  conversationId?: string;
+  turnId?: string;
+  locale?: string;
+  requestApprovalFor?: (message: string, target: AiApprovalTarget) => Promise<boolean>;
+  reportWebsiteReceipts?: (receipts: AiWebsiteReceipt[]) => Promise<void>;
+};
+
+/**
+ * Lets a public web read through when the chat supplied its address. A read sends its full address to the website,
+ * and an address the chat did not supply may carry private data the model put into it, so any other address asks
+ * like an HTTP request from code: with the full URL, and with the website approval of a signed-in chat. Returns
+ * whether such an approval let it through without asking; the chat then shows the receipt before the read goes out.
+ * Throws when the person declines.
+ */
+export const authorizeWebRead = async (kind: "page" | "file", url: string, ctx: WebReadContext): Promise<boolean> => {
+  if (ctx.conversationId && (await hasWebAddressProvenance(ctx.conversationId, url))) return false;
+  const target = { toolName: AI_WEBSITE_APPROVAL_TOOL, approvalScope: aiWebsiteApprovalScope(new URL(url).origin), always: false };
+  const runConfig = ctx.conversationId
+    ? await aiConversations.getTurnRunConfig({ conversationId: ctx.conversationId, turnId: ctx.turnId ?? "" }).catch(() => null)
+    : null;
+  const actorUserId = ctx.actor.kind === "user" ? ctx.actor.user.id : (ctx.actor.delegatedUser?.id ?? "");
+  if (
+    aiTurnAllowsWebsiteApprovals(runConfig) &&
+    (await findRememberedAiToolApproval({ actorUserId }, { ...target, conversationId: ctx.conversationId, chatOnly: true })) !== null
+  ) {
+    await ctx.reportWebsiteReceipts?.([{ index: 0, method: "GET", url }]);
+    return true;
+  }
+  const message = webReadApprovalMessage(kind, url, ctx.locale);
+  const approved = ctx.requestApprovalFor ? await ctx.requestApprovalFor(message, target) : await ctx.requestApproval(message);
+  if (!approved) throw new Error("The person did not allow reading this address. Use an address from their message or a search result.");
+  return false;
+};
 
 export const createCloudAiWebExtractTool = (config: FirecrawlToolConfig = {}) =>
   defineAiTool({
     name: "web_extract",
     description:
-      "Read one web page by URL and return clean Markdown. Inspect the relevant pages needed to support the answer; for research or comparison, prefer primary sources and read more than one useful source when warranted.",
+      "Read one web page by URL and return clean Markdown. Inspect the relevant pages needed to support the answer; for research or comparison, prefer primary sources and read more than one useful source when warranted. Use addresses exactly as the user wrote them, as web_search returned them, or as a page you already read links them; any other address asks the user first.",
     inputSchema: CloudAiWebExtractInputSchema,
     outputSchema: CloudAiWebExtractOutputSchema,
     approval: "never",
@@ -297,7 +359,28 @@ export const createCloudAiWebExtractTool = (config: FirecrawlToolConfig = {}) =>
         truncated: output.truncated || content !== output.content,
       };
     },
-  }).server(async (input, ctx) => runCloudAiWebExtract(input, { ...config, signal: ctx.signal }));
+  }).server(async (input, ctx) => {
+    const url = assertPublicHttpUrl(input.url);
+    const allowedForChat = await authorizeWebRead("page", url, ctx);
+    const output = await runCloudAiWebExtract({ url }, { ...config, signal: ctx.signal });
+    const final = URL.canParse(output.url) ? new URL(output.url) : null;
+    if (allowedForChat && final && final.href !== url) {
+      // Firecrawl follows redirects on its side. The chat shows where the read ended, and a website approval covers
+      // only content from its own origin.
+      await ctx.reportWebsiteReceipts?.([{ index: 1, method: "GET", url: final.href }]);
+      if (final.origin !== new URL(url).origin)
+        throw new Error(
+          `The page redirected to ${final.href}, which this chat has not allowed. Read that address directly so the person can decide.`,
+        );
+    }
+    // The page and every address it links to may be read again without asking.
+    if (ctx.conversationId)
+      await recordWebAddresses(
+        ctx.conversationId,
+        new Set([...webAddressesIn(url), ...webAddressesIn(output.url), ...webAddressesIn(output.content)]),
+      );
+    return output;
+  });
 
 export type CloudAiWebSearchInput = z.infer<typeof CloudAiWebSearchInputSchema>;
 export type CloudAiWebSearchOutput = z.infer<typeof CloudAiWebSearchOutputSchema>;

package/src/ai/index.ts

@@ -1,14 +1,20 @@
 export { type AiAppSkillIssue, aiAppSkills, appSkillsRegistryState, reconcileAppSkills } from "./app-skill-store";
 export { type AiApprovalPreferenceRoutes, type AiApprovalPreferenceView, createAiApprovalPreferenceRoutes } from "./approval-routes";
 export {
+  AI_WEBSITE_APPROVAL_TOOL,
   type AiToolApprovalContext,
   type AiToolApprovalPreference,
+  type AiToolApprovalRemember,
   aiToolAllowsAlways,
   aiToolApprovalScope,
   aiToolNeedsApproval,
+  aiTurnAllowsWebsiteApprovals,
+  aiWebsiteApprovalScope,
+  findRememberedAiToolApproval,
   forgetAiToolApproval,
   hasRememberedAiToolApproval,
   listAiToolApprovalPreferences,
+  parseAiWebsiteApprovalScope,
   rememberAiToolApproval,
   revokeAiToolApprovalPreference,
 } from "./approvals";
@@ -309,6 +315,7 @@ export {
 } from "./transcription";
 export type {
   AiAccessResult,
+  AiApprovalTarget,
   AiCapabilityToolPresentation,
   AiClientToolId,
   AiConversation,
@@ -360,6 +367,7 @@ export type {
   AiTurnStatus,
   AiTurnToolSource,
   AiUserContentPart,
+  AiWebsiteReceipt,
 } from "./types";
 export { AI_MESSAGE_FEEDBACK_REASONS, isAiImageMediaType } from "./types";
 export { isAiSettingsError } from "./validate";