@k2b/cloud 0.29.1 → 0.31.0

package/src/ai/store.ts

@@ -4,6 +4,7 @@ import { type SQL, sql } from "bun";
 import { type CapabilityActionReview, CapabilityActionReviewSchema } from "../contracts/capabilities";
 import { logger } from "../services/logging";
 import { toPgTextArray } from "../services/postgres";
+import { AI_WEBSITE_APPROVAL_TOOL } from "./approvals";
 import { aiTurnErrorText } from "./chat/turn-error";
 import { AI_MEMORY_LEARNING_DEFAULT_ENABLED } from "./prefs";
 import type { AiTurnBlock } from "./protocol";
@@ -36,6 +37,7 @@ import type {
   AiTurnStatus,
   AiTurnSteer,
   AiTurnSweepResult,
+  AiWebsiteReceipt,
 } from "./types";
 
 /** A queued turn this old without a claim is considered lost and re-enqueued by the sweep. */
@@ -191,6 +193,7 @@ type TurnRow = {
 };
 
 type PendingActionRow = {
+  approval_id: string | null;
   turn_id: string;
   conversation_id: string;
   call_id: string;
@@ -202,6 +205,8 @@ type PendingActionRow = {
   review: unknown | null;
   approval_scope: string;
   allow_always: boolean;
+  allow_chat: boolean | null;
+  remember_tool_name: string | null;
   frontend_mode: AiFrontendToolMode | null;
   resolved_event: unknown | null;
 };
@@ -678,9 +683,12 @@ const pendingActionToPublicEvent = (row: PendingActionRow): AiPendingTurnAction
         message: row.message ?? undefined,
         review: parseCapabilityActionReview(row.review),
         allowAlways: row.allow_always,
+        allowChat: row.allow_always || row.allow_chat === true,
+        ...(row.remember_tool_name === AI_WEBSITE_APPROVAL_TOOL ? { website: row.approval_scope } : {}),
       };
 
 const rowToPendingActionRecord = (row: PendingActionRow): AiPendingTurnActionRecord => ({
+  approvalId: row.approval_id ?? undefined,
   turnId: row.turn_id,
   conversationId: row.conversation_id,
   callId: row.call_id,
@@ -692,6 +700,8 @@ const rowToPendingActionRecord = (row: PendingActionRow): AiPendingTurnActionRec
   review: parseCapabilityActionReview(row.review),
   approvalScope: row.approval_scope,
   allowAlways: row.allow_always,
+  allowChat: row.allow_always || row.allow_chat === true,
+  ...(row.remember_tool_name ? { rememberToolName: row.remember_tool_name } : {}),
   frontendMode: row.frontend_mode ?? undefined,
   resolvedEvent: row.resolved_event ? parseJsonValue<InboundEvent>(row.resolved_event) : null,
 });
@@ -784,6 +794,18 @@ const messageSearchText = (message: Message): string => {
   return text.slice(0, SEARCH_TEXT_MAX_CHARS);
 };
 
+/**
+ * An ended turn uses no further approval: cancel its open questions and the turn's own approvals that no call used.
+ * A Studio request linked from the turn stays as decided, because the code run uses it when the call runs there.
+ */
+const cancelTurnApprovals = async (db: typeof sql, turnId: string): Promise<void> => {
+  await db`
+    UPDATE approvals.requests SET status = 'cancelled'
+    WHERE id IN (SELECT approval_id FROM ai.pending_actions WHERE turn_id = ${turnId} AND approval_id IS NOT NULL)
+      AND (status = 'pending' OR (status = 'approved' AND requester_kind = 'assistant_turn'))
+  `;
+};
+
 /**
  * Record how a turn ended on its messages when its loop could not record it: a stop while an approval waits, a run
  * time limit, or a turn the sweep finalizes. History reads the ending from the last assistant message, so such a turn
@@ -878,6 +900,35 @@ const recordTurnEnd = async (
   }
 };
 
+/**
+ * Records requests a website approval let through on the assistant message that holds the tool call, as each one
+ * goes out, so the chat keeps every receipt whether the call succeeds, fails, or its turn stops. Website approvals
+ * apply only to interactive chats, whose messages live in `ai.messages`. A receipt with a known index replaces itself.
+ */
+export const recordAiWebsiteReceipts = async (input: {
+  conversationId: string;
+  turnId: string;
+  callId: string;
+  receipts: AiWebsiteReceipt[];
+}): Promise<void> => {
+  if (!input.receipts.length) return;
+  const receipts = Object.fromEntries(input.receipts.map(({ index, method, url }) => [String(index), { method, url }]));
+  await sql`
+    UPDATE ai.messages
+    SET meta = COALESCE(meta, '{}'::jsonb) || jsonb_build_object(
+      'websiteReceipts',
+      COALESCE(meta->'websiteReceipts', '{}'::jsonb) || jsonb_build_object(
+        ${input.callId}::text,
+        COALESCE(meta->'websiteReceipts'->${input.callId}::text, '{}'::jsonb) || (${JSON.stringify(receipts)}::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))
+  `;
+};
+
 /** Insert a message inside an open conversation-lock transaction and bump the conversation. */
 const insertMessageLocked = async (
   input: {
@@ -3017,6 +3068,7 @@ export const aiConversations: AiConversationService = {
         WHERE turn_id = ${input.turnId}
           AND status = 'pending'
       `;
+      await cancelTurnApprovals(tx, input.turnId);
       if (input.status !== "completed") {
         await recordTurnEnd(tx, {
           conversationId: input.conversationId,
@@ -3173,6 +3225,7 @@ export const aiConversations: AiConversationService = {
         WHERE turn_id = ${finalized.turnId}
           AND status = 'pending'
       `;
+      await cancelTurnApprovals(sql, finalized.turnId);
       await sql`
         UPDATE ai.turn_steers
         SET status = 'discarded', consumed_at = COALESCE(consumed_at, now())
@@ -3261,6 +3314,7 @@ export const aiConversations: AiConversationService = {
   savePendingTurnAction: async (input) => {
     await sql`
       INSERT INTO ai.pending_actions (
+        approval_id,
         turn_id,
         conversation_id,
         call_id,
@@ -3271,12 +3325,15 @@ export const aiConversations: AiConversationService = {
         review,
         approval_scope,
         allow_always,
+        allow_chat,
+        remember_tool_name,
         frontend_mode,
         status,
         resolved_event,
         resolved_at
       )
       VALUES (
+        ${input.approvalId ?? null}::uuid,
         ${input.turnId},
         ${input.conversationId},
         ${input.callId},
@@ -3287,6 +3344,8 @@ export const aiConversations: AiConversationService = {
         ${input.review ? JSON.stringify(input.review) : null}::text::jsonb,
         ${input.approvalScope},
         ${input.allowAlways},
+        ${input.allowChat ?? input.allowAlways},
+        ${input.rememberToolName ?? null},
         ${input.frontendMode ?? null},
         ${input.resolvedEvent ? "resolved" : "pending"},
         ${input.resolvedEvent ? JSON.stringify(input.resolvedEvent) : null}::text::jsonb,
@@ -3294,6 +3353,7 @@ export const aiConversations: AiConversationService = {
       )
       ON CONFLICT (turn_id, call_id)
       DO UPDATE SET
+        approval_id = EXCLUDED.approval_id,
         kind = EXCLUDED.kind,
         tool_name = EXCLUDED.tool_name,
         args = EXCLUDED.args,
@@ -3301,6 +3361,8 @@ export const aiConversations: AiConversationService = {
         review = EXCLUDED.review,
         approval_scope = EXCLUDED.approval_scope,
         allow_always = EXCLUDED.allow_always,
+        allow_chat = EXCLUDED.allow_chat,
+        remember_tool_name = EXCLUDED.remember_tool_name,
         frontend_mode = EXCLUDED.frontend_mode
     `;
   },
@@ -3370,12 +3432,15 @@ export const aiConversations: AiConversationService = {
 
   clearPendingTurnActions: async (input) => {
     await sql`
-      UPDATE ai.pending_actions
+      WITH aborted AS (UPDATE ai.pending_actions
       SET status = 'aborted',
           resolved_at = COALESCE(resolved_at, now())
       WHERE conversation_id = ${input.conversationId}
         AND turn_id = ${input.turnId}
         AND status = 'pending'
+        RETURNING approval_id)
+      UPDATE approvals.requests SET status='cancelled'
+      WHERE id IN (SELECT approval_id FROM aborted WHERE approval_id IS NOT NULL) AND status='pending'
     `;
   },
 

package/src/ai/tool-audit.ts

@@ -1,4 +1,5 @@
 import { sql } from "bun";
+import type { ApprovalDecisionChannel } from "../services/approvals";
 
 /**
  * AI-specific tool-call state only: approval, turn linkage, and the request id
@@ -8,7 +9,14 @@ import { sql } from "bun";
  */
 export type AiToolCallLocation = "server" | "client" | "client_view" | "client_interaction";
 
-export type AiToolApprovalState = "not_required" | "waiting" | "approved_once" | "approved_always" | "approved_by_preference" | "rejected";
+export type AiToolApprovalState =
+  | "not_required"
+  | "waiting"
+  | "approved_once"
+  | "approved_for_chat"
+  | "approved_always"
+  | "approved_by_preference"
+  | "rejected";
 
 export const aiToolAudit = {
   /** Resolve the current server-recorded invocation, never a model-supplied chat id. */
@@ -140,12 +148,14 @@ export const aiToolAudit = {
     turnId: string;
     callId: string;
     approvalState: Exclude<AiToolApprovalState, "not_required" | "waiting">;
+    decidedVia?: ApprovalDecisionChannel;
   }): Promise<void> => {
     const approved = input.approvalState !== "rejected";
     await sql`
       UPDATE ai.tool_calls
       SET
         approval_state = ${input.approvalState},
+        approval_decided_via = ${input.decidedVia ?? null},
         status = CASE WHEN ${approved} THEN status ELSE 'rejected' END,
         approved_at = CASE WHEN ${approved} THEN now() ELSE approved_at END,
         rejected_at = CASE WHEN ${approved} THEN rejected_at ELSE now() END

package/src/ai/tool-sentences.ts

@@ -0,0 +1,38 @@
+import type { CapabilityPresentationCatalog } from "../contracts/capabilities";
+
+/**
+ * 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" },
+  },
+  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" },
+        },
+      },
+    },
+  },
+} as const satisfies CapabilityPresentationCatalog;

package/src/ai/tools.ts

@@ -4,6 +4,7 @@ import type { z } from "zod";
 import type { RequestActor } from "../server";
 import { aiToolNeedsApproval } from "./approvals";
 import type {
+  AiApprovalTarget,
   AiDataBoundary,
   AiFrontendToolMode,
   AiProjectFileToolSource,
@@ -13,6 +14,7 @@ import type {
   AiToolApprovalPolicy,
   AiToolDefinition,
   AiToolRuntime,
+  AiWebsiteReceipt,
 } from "./types";
 
 export const defineAiTool = <TInput extends z.ZodType, TOutput extends z.ZodType>(config: {
@@ -60,6 +62,12 @@ export const defineAiTool = <TInput extends z.ZodType, TOutput extends z.ZodType
           timeZone?: string;
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
+          /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
+          requestApprovalFor?: (message: string, target: AiApprovalTarget) => Promise<boolean>;
+          /** Relays a decision for an effect another platform component consumes and executes. */
+          requestRelayedApproval?: (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => Promise<boolean>;
+          /** Shows requests a website approval let through as they go out, so the chat keeps them whatever the outcome. */
+          reportWebsiteReceipts?: (receipts: AiWebsiteReceipt[]) => Promise<void>;
         },
       ) => Promise<z.infer<TOutput>>,
     ): AiToolRuntime<TInput, TOutput> {
@@ -106,15 +114,93 @@ export type AiToolPreparationContext = {
   locale?: string;
   timeZone?: string;
   reportToolProgress?: (callId: string, message: string) => Promise<void>;
+  /** Uses the approved snapshot immediately before the tool executes its effect. */
+  consumeApproval?: (approvalCallId: string, input: unknown) => Promise<AiApprovalUse>;
+  /** Links a relayed decision to the record the effect owner will consume. */
+  linkApproval?: (approvalCallId: string, approvalId: string) => void;
+  /** Hears what a nested approval asks for before the approval is requested. */
+  describeApproval?: (approvalCallId: string, target: AiApprovalTarget) => void;
+  reportWebsiteReceipts?: (callId: string, receipts: AiWebsiteReceipt[]) => Promise<void>;
 };
 
+/**
+ * What using an approval found: `approved` lets the effect run, `changed` means the approved snapshot no longer
+ * matches and asks again, and `used` means an earlier run of the call already used it, so the call must not run again.
+ */
+export type AiApprovalUse = "approved" | "changed" | "used";
+
+const approvalCallIdPattern = /^(.*)-approval-(\d+)$/;
+
+/**
+ * Whether `askedCallIds` holds a question of the same tool call that Nessi asked after `approvalCallId`, the call's
+ * own approval or one of its numbered questions. A turn that continues after such a question runs the tool from its
+ * start again, so the approvals before it are used again by the same call.
+ */
+export const aiApprovalAskedLater = (approvalCallId: string, askedCallIds: Iterable<string>): boolean => {
+  const own = approvalCallIdPattern.exec(approvalCallId);
+  const callId = own ? own[1] : approvalCallId,
+    index = own ? Number(own[2]) : -1;
+  for (const asked of askedCallIds) {
+    const later = approvalCallIdPattern.exec(asked);
+    if (later && later[1] === callId && Number(later[2]) > index) return true;
+  }
+  return false;
+};
+
+const approvalUsedError = () =>
+  new Error("This approval was already used, so Cloud does not run the call again. Check its outcome before you call again.");
+
 export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRuntimeTool[] }): PreparedAiTools => {
   const canonicalNames = new Map<string, string>();
   const approvalPolicies = new Map<string, AiToolApprovalPolicy>();
   const frontendModes = new Map<string, AiFrontendToolMode>();
 
+  const approvalContext = async (toolInput: unknown, ctx: ToolContext, needsApproval: boolean) => {
+    const callId = ctx.callId;
+    const use = (approvalCallId: string): Promise<AiApprovalUse> =>
+      input.consumeApproval ? input.consumeApproval(approvalCallId, toolInput) : Promise.resolve("approved");
+    if (needsApproval && input.consumeApproval) {
+      const used = callId ? await use(callId) : "changed";
+      if (used === "used") throw approvalUsedError();
+      if (used === "changed") throw new Error("This approval no longer matches the call. Ask again.");
+    }
+    // Nessi numbers the approvals of one execution in request order; count them to name each one's call ID.
+    let approvals = 0;
+    const requestApproval = async (message: string, target?: AiApprovalTarget): Promise<boolean> => {
+      while (true) {
+        const approvalCallId = `${callId}-approval-${approvals++}`;
+        if (target) input.describeApproval?.(approvalCallId, target);
+        if (!(await ctx.requestApproval(message))) return false;
+        const used = await use(approvalCallId);
+        if (used === "approved") return true;
+        if (used === "used") throw approvalUsedError();
+        // A changed snapshot requires a new human decision under the next Nessi action ID.
+      }
+    };
+    return {
+      ...ctx,
+      requestApproval,
+      requestApprovalFor: (message: string, target: AiApprovalTarget) => requestApproval(message, target),
+      requestRelayedApproval: async (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => {
+        const approvalCallId = `${callId}-approval-${approvals++}`;
+        if (options.approvalId) input.linkApproval?.(approvalCallId, options.approvalId);
+        if (options.target) input.describeApproval?.(approvalCallId, options.target);
+        if (!(await ctx.requestApproval(message))) return false;
+        // The effect's own record is used where it runs. Without one, as for a website request from code, the relay
+        // that hands over the decision uses the chat's record; a decision it cannot use is not handed over as approval.
+        return options.approvalId !== undefined || (await use(approvalCallId)) === "approved";
+      },
+    };
+  };
+
   const tools = (input.tools ?? []).map((tool): Tool => {
-    if (!isCloudAiTool(tool)) return tool;
+    if (!isCloudAiTool(tool)) {
+      if (tool.kind !== "server") return tool;
+      return {
+        ...tool,
+        execute: async (toolInput, ctx) => tool.execute(toolInput, await approvalContext(toolInput, ctx, tool.def.needsApproval === true)),
+      };
+    }
 
     canonicalNames.set(tool.def.name, tool.def.canonicalName ?? tool.def.name);
     approvalPolicies.set(tool.def.name, tool.def.approval);
@@ -130,12 +216,12 @@ export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRun
     });
 
     if (tool.location === "server") {
-      return nessiTool.server((toolInput, ctx) => {
+      return nessiTool.server(async (toolInput, ctx) => {
         if (!input.actor) throw new Error(`AI server tool "${tool.def.name}" requires a request actor.`);
         const report = input.reportToolProgress;
         const callId = ctx.callId;
         return tool.run(toolInput, {
-          ...ctx,
+          ...(await approvalContext(toolInput, ctx, aiToolNeedsApproval(tool.def.approval))),
           actor: input.actor,
           conversationId: input.conversationId,
           turnId: input.turnId,
@@ -147,6 +233,8 @@ export const prepareAiTools = (input: AiToolPreparationContext & { tools?: AiRun
           locale: input.locale,
           timeZone: input.timeZone,
           reportProgress: callId && report ? (message) => report(callId, message) : undefined,
+          reportWebsiteReceipts:
+            callId && input.reportWebsiteReceipts ? (receipts) => input.reportWebsiteReceipts!(callId, receipts) : undefined,
         });
       });
     }

package/src/ai/types.ts

@@ -12,7 +12,8 @@ import type {
 } from "@k2b/nessi";
 import type { Usage } from "@k2b/nessi/ai";
 import type { z } from "zod";
-import type { CapabilityActionReview, CloudResourceRef } from "../contracts/capabilities";
+import type { CapabilitySentenceField } from "../_internal/capability-sentences";
+import type { CapabilityActionReview, CapabilityActionSentences, CloudResourceRef } from "../contracts/capabilities";
 import type { RequestActor } from "../server";
 import type { AiTurnBlock } from "./protocol";
 
@@ -302,6 +303,8 @@ export type AiStoredMessage = {
     toolPresentations?: Record<string, AiToolPresentation>;
     /** How the person decided an approval; `expired` when the turn ended while it still waited. */
     toolOutcomes?: Record<string, "rejected" | "approved" | "expired">;
+    /** Requests a website approval let through, by tool call and then by `AiWebsiteReceipt.index`. */
+    websiteReceipts?: Record<string, Record<string, { method: string; url: string }>>;
     /** Why the turn failed, on the last message of its loop. The chat words it in the reader's language. */
     turnError?: AiTurnError;
   } | null;
@@ -419,6 +422,10 @@ export type AiPendingTurnAction =
       message?: string;
       review?: CapabilityActionReview;
       allowAlways: boolean;
+      /** Whether the approval can be remembered for this chat. */
+      allowChat: boolean;
+      /** The website origin a chat approval would allow, for an HTTP request a code run makes. */
+      website?: string;
     }
   | {
       type: "frontend_tool";
@@ -440,6 +447,7 @@ export type AiTurnAbortRequest =
     };
 
 export type AiPendingTurnActionRecord = {
+  approvalId?: string;
   turnId: string;
   conversationId: string;
   callId: string;
@@ -451,6 +459,10 @@ export type AiPendingTurnActionRecord = {
   review?: CapabilityActionReview;
   approvalScope: string;
   allowAlways: boolean;
+  /** Whether the approval can be remembered for this chat; defaults to `allowAlways`. */
+  allowChat?: boolean;
+  /** Remembered-approval name when it differs from `name`: the website or Action a code run asks for. */
+  rememberToolName?: string;
   frontendMode?: AiFrontendToolMode;
   resolvedEvent: InboundEvent | null;
 };
@@ -606,6 +618,11 @@ export type AiChatTurnRunConfig = {
   selectedSkillIds?: string[];
   /** Server-owned marker: model grants apply only to interactive Assistant chat. */
   assistantChat?: true;
+  /**
+   * Server-owned marker: a person started this turn in a signed-in browser session, not through `cld`, an API key,
+   * a delegated account, or a schedule. Only such a turn uses website approvals.
+   */
+  signedInSession?: true;
   kind?: "chat";
   input: Input;
   /** Stable public ID exposed as runtime context, not instructions. */
@@ -1015,6 +1032,23 @@ export type AiAccessResult<TAccess = unknown> = {
 
 export type AiToolApprovalPolicy = "never" | "once" | "always" | { kind: "user-configurable"; default: "once" | "always"; scope?: string };
 
+/**
+ * What a server tool asks a person to approve when the approval can be remembered: a website or an Action, not the
+ * tool itself. A target can always be remembered for its chat.
+ */
+export type AiApprovalTarget = {
+  toolName: string;
+  approvalScope: string;
+  /** Whether the person may also remember it everywhere. */
+  always: boolean;
+};
+
+/**
+ * A request a remembered website approval let through without asking. The chat shows it with its full URL and a revoke
+ * action; `index` orders the receipts of one tool call, and a receipt reported again with the same index replaces it.
+ */
+export type AiWebsiteReceipt = { index: number; method: string; url: string };
+
 export type AiFrontendToolMode = "client" | "client_view" | "client_interaction";
 
 export type AiCapabilityToolPresentation = {
@@ -1025,6 +1059,12 @@ export type AiCapabilityToolPresentation = {
   appAccent?: string;
   title: string;
   capabilityKind: "query" | "action";
+  /** Actions: the app's sentences in the locale of the turn, worded for each call by the chat. */
+  sentences?: CapabilityActionSentences;
+  /** Actions: field formats for the sentences and labelled fields for the generic sentence, in schema order. */
+  fields?: CapabilitySentenceField[];
+  /** Actions: Cloud offered the model `approvalReason` for this call, so the chat may show it as the model's reason. */
+  approvalReason?: true;
 };
 
 export type AiToolPresentation = AiCapabilityToolPresentation;
@@ -1064,6 +1104,12 @@ export type AiToolRuntime<TInput extends z.ZodType = z.ZodType, TOutput extends
           timeZone?: string;
           /** Localized short status; never include payloads or secrets. */
           reportProgress?: (message: string) => Promise<void>;
+          /** Asks like `requestApproval`, and lets the person remember the approval of `target`. */
+          requestApprovalFor?: (message: string, target: AiApprovalTarget) => Promise<boolean>;
+          /** Relays a decision for an effect another platform component consumes and executes. */
+          requestRelayedApproval?: (message: string, options: { approvalId?: string; target?: AiApprovalTarget }) => Promise<boolean>;
+          /** Shows requests a website approval let through as they go out, so the chat keeps them whatever the outcome. */
+          reportWebsiteReceipts?: (receipts: AiWebsiteReceipt[]) => Promise<void>;
         },
       ): Promise<z.infer<TOutput>>;
     }

package/src/ai/web-provenance.ts

@@ -0,0 +1,103 @@
+import { domainToUnicode } from "node:url";
+import { sql } from "bun";
+import { toPgTextArray } from "../services/postgres";
+
+/** The longest address web_extract and fetch_file accept; a longer one can never be read, so it is never recorded. */
+const WEB_ADDRESS_MAX_CHARS = 2_000;
+
+const URL_TOKEN = /https?:\/\/[^\s<>"'`\\^{}|[\]]+/gi;
+/**
+ * An address typed without its scheme, such as `example.org/news`. It must start the word: a host inside another
+ * address, an email address, or a longer host name is not a typed address of its own.
+ */
+const BARE_TOKEN =
+  /(?<![\w@.\-/:%+~#=?&])(?:[a-z0-9](?:[a-z0-9-]*[a-z0-9])?\.)+[a-z][a-z0-9-]*[a-z0-9](?::\d{1,5})?(?:\/[^\s<>"'`\\^{}|[\]]*)?/gi;
+
+/** Drops punctuation that ends the sentence around an address, and a closing bracket the address did not open. */
+const trimToken = (token: string): string => {
+  let end = token.length;
+  while (end > 0) {
+    const last = token[end - 1]!;
+    if (".,;:!?*'\"".includes(last)) end--;
+    else if (last === ")" && token.slice(0, end).split("(").length <= token.slice(0, end).split(")").length - 1) end--;
+    else break;
+  }
+  return token.slice(0, end);
+};
+
+/** The forms of one address that count as the same read: as written, without its fragment, and over HTTPS. */
+const addressForms = (raw: string, add: (address: string) => void) => {
+  let url: URL;
+  try {
+    url = new URL(raw);
+  } catch {
+    return;
+  }
+  if (url.protocol !== "https:" && url.protocol !== "http:") return;
+  const forms = [url.href];
+  if (url.hash) forms.push(url.href.slice(0, -url.hash.length));
+  // Upgrading to HTTPS carries no data the address did not already carry.
+  if (url.protocol === "http:") forms.push(...forms.map((form) => `https:${form.slice("http:".length)}`));
+  for (const form of forms) if (form.length <= WEB_ADDRESS_MAX_CHARS) add(form);
+};
+
+/**
+ * Every whole address in a text, normalized like a URL the tools read. Only complete tokens count, never a part of a
+ * longer address; with `typed`, an address written without its scheme counts too, as a person often types it.
+ */
+export const webAddressesIn = (text: string, options: { typed?: boolean } = {}): Set<string> => {
+  const addresses = new Set<string>();
+  const add = (address: string) => addresses.add(address);
+  const rest = text.replace(URL_TOKEN, (token) => {
+    addressForms(trimToken(token), add);
+    return " ";
+  });
+  if (options.typed)
+    for (const [token] of rest.matchAll(BARE_TOKEN)) {
+      const bare = trimToken(token);
+      addressForms(`https://${bare}`, add);
+      addressForms(`http://${bare}`, add);
+    }
+  return addresses;
+};
+
+/** Records addresses a web search returned or a page read in this chat links to; later reads of them do not ask. */
+export const recordWebAddresses = async (conversationId: string, addresses: Iterable<string>): Promise<void> => {
+  const list = [...addresses];
+  if (!list.length) return;
+  await sql`
+    INSERT INTO ai.web_addresses (conversation_id, address)
+    SELECT ${conversationId}::uuid, address FROM unnest(${toPgTextArray(list)}::text[]) address
+    ON CONFLICT DO NOTHING
+  `;
+};
+
+/**
+ * Whether the chat itself supplied this address: the person wrote it, a web search returned it, or a page read
+ * earlier links to it. A message another chat sent counts as neither. Anything else, such as an address the model
+ * assembled from other data, has no provenance. `url` is the normalized address the tool reads.
+ */
+export const hasWebAddressProvenance = async (conversationId: string, url: string): Promise<boolean> => {
+  const [recorded] = await sql<{ found: boolean }[]>`
+    SELECT EXISTS (SELECT 1 FROM ai.web_addresses WHERE conversation_id = ${conversationId}::uuid AND address = ${url}) AS found
+  `;
+  if (recorded?.found) return true;
+  // Only the person's own messages that name the host are read, never tool results.
+  const { hostname } = new URL(url);
+  const hosts = [...new Set([hostname, domainToUnicode(hostname) || hostname])];
+  const rows = await sql<{ text: string }[]>`
+    SELECT text FROM (
+      SELECT message, meta FROM ai.messages WHERE conversation_id = ${conversationId}::uuid AND kind = 'message' AND role = 'user'
+      UNION ALL
+      SELECT message, meta FROM ai.task_messages WHERE conversation_id = ${conversationId}::uuid AND kind = 'message' AND role = 'user'
+    ) entry
+    CROSS JOIN LATERAL (
+      SELECT string_agg(CASE WHEN jsonb_typeof(part) = 'string' THEN part #>> '{}' ELSE part->>'text' END, chr(10)) AS text
+      FROM jsonb_array_elements(CASE WHEN jsonb_typeof(entry.message->'content') = 'array' THEN entry.message->'content' ELSE '[]'::jsonb END) part
+      WHERE jsonb_typeof(part) = 'string' OR part->>'type' = 'text'
+    ) content
+    WHERE NOT COALESCE(entry.meta ? 'agentMessage', false)
+      AND EXISTS (SELECT 1 FROM unnest(${toPgTextArray(hosts)}::text[]) host WHERE strpos(lower(content.text), host) > 0)
+  `;
+  return rows.some((row) => webAddressesIn(row.text, { typed: true }).has(url));
+};