@k2b/cloud 0.30.0 → 0.32.0

package/src/ai/local-tool-contracts.ts

@@ -0,0 +1,244 @@
+import { z } from "zod";
+import { AI_SKILL_DESCRIPTION_MAX_CHARS, AI_SKILL_INSTRUCTIONS_MAX_CHARS, AI_SKILL_NAME_PATTERN } from "./skill-format";
+
+/**
+ * Contracts of the client tools a local client such as `cld` runs on the user's computer, and of the context it
+ * sends with a turn. Cloud declares and validates them; the client executes them and enforces its own path rules.
+ */
+export const AI_LOCAL_TOOL_NAMES = [
+  "local_list",
+  "local_read",
+  "local_upload",
+  "local_download",
+  "local_write",
+  "local_move",
+  "load_local_skill",
+] as const;
+export type AiLocalToolName = (typeof AI_LOCAL_TOOL_NAMES)[number];
+
+/** Longest absolute path a client reports, Linux PATH_MAX. */
+export const AI_LOCAL_PATH_MAX_CHARS = 4096;
+/** Entries per local_list page by default and at most, like code_files. */
+export const AI_LOCAL_LIST_DEFAULT_LIMIT = 100;
+export const AI_LOCAL_LIST_MAX_LIMIT = 1000;
+/** Bytes per local_read call by default and at most, like read_file. */
+export const AI_LOCAL_READ_DEFAULT_BYTES = 16 * 1024;
+export const AI_LOCAL_READ_MAX_BYTES = 64 * 1024;
+/** Text one local_write call writes, like write_file. */
+export const AI_LOCAL_WRITE_MAX_BYTES = 100 * 1024;
+/** Paths per upload or move batch, like the code-mode input paths and the 64-item request limits. */
+export const AI_LOCAL_BATCH_MAX_ITEMS = 64;
+/** AGENTS.md text one turn carries, the Codex default. */
+export const AI_LOCAL_INSTRUCTIONS_MAX_BYTES = 32 * 1024;
+/** Local Skills one turn lists, like the 64-item request limits. */
+export const AI_LOCAL_SKILLS_MAX_ITEMS = 64;
+/** Local Skills one message selects explicitly. */
+export const AI_LOCAL_SELECTED_SKILLS_MAX_ITEMS = 4;
+/** Files a loaded local Skill lists, like Cloud Skill references. */
+export const AI_LOCAL_SKILL_FILES_MAX_ITEMS = 50;
+
+const LocalPath = z.string().min(1).max(AI_LOCAL_PATH_MAX_CHARS);
+const ChatPath = z.string().trim().min(1).max(500);
+const SkillName = z.string().regex(AI_SKILL_NAME_PATTERN).max(64);
+/** One line of client-reported text: control characters and line breaks never reach the prompt. */
+const FactLine = (max: number) =>
+  z
+    .string()
+    .max(max)
+    .transform((value) => value.replace(/[\p{Cc}\p{Zl}\p{Zp}]+/gu, " ").trim())
+    .pipe(z.string().min(1));
+
+/** A request the client did not run: the person said no, a rule refused it, or it failed. */
+const LocalToolProblem = z.object({
+  status: z.enum(["denied", "failed"]),
+  error: z.string().max(2000),
+});
+
+export const CloudAiLocalListInputSchema = z.object({
+  path: LocalPath.default(".").describe("Folder to list, relative to the workspace."),
+  pattern: z
+    .string()
+    .trim()
+    .min(1)
+    .max(500)
+    .optional()
+    .describe("Glob such as **/*.pdf or 2026-09/*.{pdf,jpg}; matching ignores case. ** lists subfolders."),
+  recursive: z.boolean().default(false),
+  limit: z.number().int().min(1).max(AI_LOCAL_LIST_MAX_LIMIT).default(AI_LOCAL_LIST_DEFAULT_LIMIT),
+  after: LocalPath.optional().describe("nextAfter of the previous page."),
+});
+export const CloudAiLocalListOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("completed"),
+    path: LocalPath,
+    entries: z
+      .array(
+        z.object({
+          path: LocalPath,
+          type: z.enum(["file", "directory", "other"]),
+          size: z.number().int().min(0),
+          modifiedAt: z.string().max(40),
+        }),
+      )
+      .max(AI_LOCAL_LIST_MAX_LIMIT),
+    nextAfter: LocalPath.nullable(),
+    unreadable: z.array(LocalPath).max(AI_LOCAL_LIST_MAX_LIMIT).optional(),
+  }),
+  LocalToolProblem,
+]);
+
+export const CloudAiLocalReadInputSchema = z.object({
+  path: LocalPath,
+  offset: z.number().int().min(1).default(1).describe("First line to read."),
+  maxBytes: z.number().int().min(1).max(AI_LOCAL_READ_MAX_BYTES).default(AI_LOCAL_READ_DEFAULT_BYTES),
+});
+// Two completed shapes share their status, so this is a plain union rather than one keyed by status.
+export const CloudAiLocalReadOutputSchema = z.union([
+  z.object({
+    status: z.literal("completed"),
+    kind: z.literal("text"),
+    path: LocalPath,
+    /** Lines prefixed with their number and a tab; short lines can make the numbers outweigh the text. */
+    content: z.string().max(AI_LOCAL_READ_MAX_BYTES * 10),
+    firstLine: z.number().int().min(1),
+    lastLine: z.number().int().min(0),
+    totalBytes: z.number().int().min(0),
+    nextOffset: z.number().int().min(1).nullable(),
+  }),
+  z.object({
+    status: z.literal("completed"),
+    kind: z.literal("uploaded"),
+    path: LocalPath,
+    chatPath: ChatPath,
+    mediaType: z.string().max(120),
+    size: z.number().int().min(0),
+  }),
+  LocalToolProblem,
+]);
+
+export const CloudAiLocalUploadInputSchema = z.object({
+  paths: z.array(LocalPath).min(1).max(AI_LOCAL_BATCH_MAX_ITEMS),
+  directory: ChatPath.optional().describe("Chat folder for all files; by default each file keeps its folder from the workspace."),
+});
+export const CloudAiLocalUploadOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("completed"),
+    files: z
+      .array(z.object({ path: LocalPath, chatPath: ChatPath, mediaType: z.string().max(120), size: z.number().int().min(0) }))
+      .max(AI_LOCAL_BATCH_MAX_ITEMS),
+    failed: z.array(z.object({ path: LocalPath, error: z.string().max(2000) })).max(AI_LOCAL_BATCH_MAX_ITEMS),
+  }),
+  LocalToolProblem,
+]);
+
+export const CloudAiLocalDownloadInputSchema = z.object({
+  path: ChatPath.describe("Chat file to save."),
+  to: LocalPath.describe("Target file, relative to the workspace."),
+  replace: z.boolean().default(false),
+});
+export const CloudAiLocalDownloadOutputSchema = z.discriminatedUnion("status", [
+  z.object({ status: z.literal("completed"), path: LocalPath, size: z.number().int().min(0), replaced: z.boolean() }),
+  LocalToolProblem,
+]);
+
+export const CloudAiLocalWriteInputSchema = z.object({
+  path: LocalPath,
+  content: z.string().refine((value) => new TextEncoder().encode(value).byteLength <= AI_LOCAL_WRITE_MAX_BYTES, "Content exceeds 100 KiB."),
+  mode: z.enum(["create", "append", "replace"]).default("create"),
+});
+export const CloudAiLocalWriteOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("completed"),
+    path: LocalPath,
+    mode: z.enum(["create", "append", "replace"]),
+    size: z.number().int().min(0),
+  }),
+  LocalToolProblem,
+]);
+
+const LocalMove = z.object({ from: LocalPath, to: LocalPath });
+export const CloudAiLocalMoveInputSchema = z.object({
+  moves: z.array(LocalMove).min(1).max(AI_LOCAL_BATCH_MAX_ITEMS),
+});
+/** A move batch reports what already moved even when it stops, so the model can name or undo it. */
+export const CloudAiLocalMoveOutputSchema = z.object({
+  status: z.enum(["completed", "denied", "failed"]),
+  moved: z.array(LocalMove).max(AI_LOCAL_BATCH_MAX_ITEMS),
+  conflicts: z.array(z.object({ to: LocalPath, reason: z.string().max(500) })).max(AI_LOCAL_BATCH_MAX_ITEMS),
+  error: z.string().max(2000).optional(),
+});
+
+export const CloudAiLoadLocalSkillInputSchema = z.object({ name: SkillName });
+export const CloudAiLoadLocalSkillOutputSchema = z.discriminatedUnion("status", [
+  z.object({
+    status: z.literal("completed"),
+    name: SkillName,
+    directory: LocalPath,
+    instructions: z.string().max(AI_SKILL_INSTRUCTIONS_MAX_CHARS),
+    files: z.array(LocalPath).max(AI_LOCAL_SKILL_FILES_MAX_ITEMS),
+  }),
+  LocalToolProblem,
+]);
+
+/** Facts about the local client a turn comes from; Cloud renders them into the "# Local client" prompt section. */
+export const AiLocalClientSchema = z.object({
+  kind: z.enum(["cli", "acp"]),
+  /** The editor's ACP clientInfo.name. */
+  name: FactLine(120).optional(),
+  cwd: FactLine(AI_LOCAL_PATH_MAX_CHARS),
+  os: FactLine(120),
+  shell: FactLine(120),
+  localTools: z.enum(["ask", "off"]),
+});
+
+/** AGENTS.md files and local Skills the client found in its workspace for one turn. */
+export const AiLocalContextSchema = z.object({
+  instructions: z
+    .array(z.object({ path: LocalPath, content: z.string() }))
+    .max(64)
+    .refine(
+      (files) =>
+        files.reduce((bytes, file) => bytes + new TextEncoder().encode(file.content).byteLength, 0) <= AI_LOCAL_INSTRUCTIONS_MAX_BYTES,
+      "AGENTS.md content exceeds 32 KiB.",
+    )
+    .default([]),
+  skills: z
+    .array(
+      z.object({
+        name: SkillName,
+        description: z.string().trim().min(1).max(AI_SKILL_DESCRIPTION_MAX_CHARS),
+        scope: z.enum(["project", "global"]),
+        manualOnly: z.boolean().optional(),
+      }),
+    )
+    .max(AI_LOCAL_SKILLS_MAX_ITEMS)
+    .refine((skills) => new Set(skills.map((skill) => skill.name)).size === skills.length, "Local Skill names must be unique.")
+    .default([]),
+  selectedSkills: z
+    .array(
+      z.object({
+        name: SkillName,
+        directory: LocalPath,
+        instructions: z.string().trim().min(1).max(AI_SKILL_INSTRUCTIONS_MAX_CHARS),
+      }),
+    )
+    .max(AI_LOCAL_SELECTED_SKILLS_MAX_ITEMS)
+    .default([]),
+});
+
+export type CloudAiLocalListInput = z.infer<typeof CloudAiLocalListInputSchema>;
+export type CloudAiLocalListOutput = z.infer<typeof CloudAiLocalListOutputSchema>;
+export type CloudAiLocalReadInput = z.infer<typeof CloudAiLocalReadInputSchema>;
+export type CloudAiLocalReadOutput = z.infer<typeof CloudAiLocalReadOutputSchema>;
+export type CloudAiLocalUploadInput = z.infer<typeof CloudAiLocalUploadInputSchema>;
+export type CloudAiLocalUploadOutput = z.infer<typeof CloudAiLocalUploadOutputSchema>;
+export type CloudAiLocalDownloadInput = z.infer<typeof CloudAiLocalDownloadInputSchema>;
+export type CloudAiLocalDownloadOutput = z.infer<typeof CloudAiLocalDownloadOutputSchema>;
+export type CloudAiLocalWriteInput = z.infer<typeof CloudAiLocalWriteInputSchema>;
+export type CloudAiLocalWriteOutput = z.infer<typeof CloudAiLocalWriteOutputSchema>;
+export type CloudAiLocalMoveInput = z.infer<typeof CloudAiLocalMoveInputSchema>;
+export type CloudAiLocalMoveOutput = z.infer<typeof CloudAiLocalMoveOutputSchema>;
+export type CloudAiLoadLocalSkillInput = z.infer<typeof CloudAiLoadLocalSkillInputSchema>;
+export type CloudAiLoadLocalSkillOutput = z.infer<typeof CloudAiLoadLocalSkillOutputSchema>;
+export type AiLocalClient = z.infer<typeof AiLocalClientSchema>;
+export type AiLocalContext = z.infer<typeof AiLocalContextSchema>;

package/src/ai/malformed-tool-call-repair.ts

@@ -0,0 +1,144 @@
+import type { NessiIssue, Provider, SessionStore, ToolCallBlock, ToolStreamIssue } from "@k2b/nessi";
+import { AiTurnFailure } from "./turn-failure";
+import type { AiStoredMessage } from "./types";
+
+/** At most two automatic repairs per chat turn; user steering does not reset this budget. */
+export const AI_MALFORMED_TOOL_CALL_REPAIR_ATTEMPTS = 2;
+
+const excerpt = (text: string, maxChars: number): string => (text.length <= maxChars ? text : `${text.slice(0, maxChars - 1)}…`);
+
+/** Never include argsText: code and other tool arguments can be very large. */
+export const malformedToolCallMessage = (issue: ToolStreamIssue): string =>
+  `The tool call${issue.name ? ` to ${excerpt(issue.name, 120)}` : ""} could not be used: ${excerpt(issue.message, 512)} (${issue.reason}).`;
+
+const REPAIR_REQUEST = "Re-send the call with its exact tool name and complete, valid, properly escaped JSON arguments.";
+
+const buildStoredMalformedToolCallRepairText = (name: string): string => `The tool call to ${name} could not be used. ${REPAIR_REQUEST}`;
+
+export const buildMalformedToolCallRepairText = (issue: ToolStreamIssue): string => `${malformedToolCallMessage(issue)} ${REPAIR_REQUEST}`;
+
+// The prefix lets resumed turns count repairs independently of ordinary tool calls. The id is 34 characters of [a-z0-9_],
+// within OpenAI's 40- and Anthropic's 64-character limits; stricter providers (Mistral's nine alphanumeric characters)
+// map ids at the transport boundary (see provider.ts).
+export const newMalformedToolCallId = (): string => `malformed_${crypto.randomUUID().replaceAll("-", "").slice(0, 24)}`;
+
+export const isMalformedToolCallId = (id: string): boolean => /^malformed_[0-9a-f]{24}$/.test(id);
+
+export const malformedToolCallName = (issue: ToolStreamIssue): string =>
+  issue.name && /^[A-Za-z0-9_-]{1,64}$/.test(issue.name) ? issue.name : "unknown_tool";
+
+// Partial responses (error/interrupted) count too: their stored error result requests the repair on resume, so each
+// saved response with a malformed call spends one repair, as in the live run.
+export const countMalformedToolCallRepairs = (messages: readonly Pick<AiStoredMessage, "message">[]): number =>
+  messages.filter(
+    ({ message }) =>
+      message.role === "assistant" && message.content.some((block) => block.type === "tool_call" && isMalformedToolCallId(block.id)),
+  ).length;
+
+// Since 0.17.1, nessi also repairs malformed calls with its own user message and counter. Cloud's session store
+// drops user messages nessi appends, and applying Cloud's repair through steering resets nessi's counter.
+// Only Cloud's repair reaches the model and user. Executor unit tests pin Cloud's exhaustion; live integration tests
+// pin the repair results sent to the model, absence of nessi's message in storage and requests, and Cloud's logged failure.
+export const createMalformedToolCallRepair = (previousAttempts: number) => {
+  let attempts = previousAttempts;
+  let lastIssue: ToolStreamIssue | undefined;
+  // Malformed calls of the provider response in flight; pending marks a stored response that still awaits its repair.
+  let issues: (ToolStreamIssue & { callId: string })[] = [];
+  // A stored response beyond the budget means the run stopped before it could fail the turn.
+  let pending = previousAttempts > AI_MALFORMED_TOOL_CALL_REPAIR_ATTEMPTS;
+  return {
+    startProviderTurn: () => {
+      issues = [];
+    },
+    noteIssue: (issue: NessiIssue): NessiIssue => {
+      if (issue.kind !== "malformed_tool_call") return issue;
+      const rewritten = { ...issue, callId: newMalformedToolCallId() };
+      issues.push(rewritten);
+      lastIssue = rewritten;
+      return rewritten;
+    },
+    /** Hands the response's malformed calls to the store once and marks the repair as due. */
+    takeResponseIssues: () => {
+      const taken = issues;
+      issues = [];
+      if (taken.length > 0) pending = true;
+      return taken;
+    },
+    takeSteering: (): string | undefined => {
+      if (!pending) return undefined;
+      pending = false;
+      if (attempts >= AI_MALFORMED_TOOL_CALL_REPAIR_ATTEMPTS || !lastIssue) {
+        throw new AiTurnFailure(
+          "failed",
+          lastIssue
+            ? malformedToolCallMessage(lastIssue)
+            : "A stored response held a tool call that could not be used after the turn's repairs were spent.",
+        );
+      }
+      attempts++;
+      return buildMalformedToolCallRepairText(lastIssue);
+    },
+  };
+};
+
+export const withMalformedToolCallRepair = (provider: Provider, repair: ReturnType<typeof createMalformedToolCallRepair>): Provider => ({
+  ...provider,
+  stream: async function* (request) {
+    repair.startProviderTurn();
+    for await (const event of provider.stream(request)) {
+      yield event.type === "issue" ? { ...event, issue: repair.noteIssue(event.issue) } : event;
+    }
+  },
+});
+
+export const withMalformedToolCallResults = (
+  store: SessionStore,
+  repair: ReturnType<typeof createMalformedToolCallRepair>,
+): SessionStore => ({
+  ...store,
+  load: async () => {
+    const entries = await store.load();
+    const assistantIndex = entries.findLastIndex(({ message, kind }) => message.role === "assistant" && kind === "message");
+    const assistant = entries[assistantIndex]?.message;
+    const following = entries.slice(assistantIndex + 1);
+    if (assistant?.role !== "assistant" || following.some(({ message }) => message.role === "user")) return entries;
+    const resolved = new Set(following.flatMap(({ message }) => (message.role === "tool_result" ? [message.callId] : [])));
+    const missing = assistant.content.filter(
+      (block): block is ToolCallBlock => block.type === "tool_call" && isMalformedToolCallId(block.id) && !resolved.has(block.id),
+    );
+    if (missing.length === 0) return entries;
+    for (const call of missing) {
+      await store.append({
+        role: "tool_result",
+        callId: call.id,
+        name: call.name,
+        isError: true,
+        result: buildStoredMalformedToolCallRepairText(call.name),
+      });
+    }
+    return store.load();
+  },
+  append: async (message, opts) => {
+    const issues = message.role === "assistant" && opts?.kind !== "summary" ? repair.takeResponseIssues() : [];
+    if (message.role !== "assistant" || issues.length === 0) {
+      await store.append(message, opts);
+      return;
+    }
+    const calls: ToolCallBlock[] = issues.map((issue) => ({
+      type: "tool_call",
+      id: issue.callId,
+      name: malformedToolCallName(issue),
+      args: {},
+    }));
+    await store.append({ ...message, content: [...message.content, ...calls] }, opts);
+    for (const issue of issues) {
+      await store.append({
+        role: "tool_result",
+        callId: issue.callId,
+        name: malformedToolCallName(issue),
+        result: buildMalformedToolCallRepairText(issue),
+        isError: true,
+      });
+    }
+  },
+});

package/src/ai/markdown-pdf-tool.ts

@@ -7,6 +7,7 @@ import {
   type RenderMarkdownToPdfOptions,
   renderMarkdownToPdf,
 } from "../services/pdf";
+import { aiMissingChatFileError } from "./file-error";
 import { aiProjectFilePathFromMount } from "./file-mount";
 import { type AiFileContent, aiFileStore, normalizeAiFilePath } from "./files-store";
 import { withAiPdfConversionSlot } from "./pdf-conversions";
@@ -65,7 +66,7 @@ export const createCloudAiMarkdownToPdfTool = (dependencies: MarkdownPdfToolDepe
     if (!ctx.conversationId) throw new Error("The markdown_to_pdf tool needs a conversation context.");
     const sourcePath = conversationPath(input.path);
     const source = await read({ conversationId: ctx.conversationId, path: sourcePath });
-    if (!source) throw new Error(`No such file: ${sourcePath}`);
+    if (!source) throw aiMissingChatFileError(sourcePath, ctx.localToolsEnabled);
     if (source.origin !== "assistant") {
       throw new Error(`Create an assistant-owned Markdown file with write_file before converting ${sourcePath}.`);
     }

package/src/ai/migrate.ts

@@ -1,4 +1,6 @@
 import { sql } from "bun";
+import { CapabilityActionReviewSchema } from "../contracts/capabilities";
+import { APPROVAL_MAX_WAIT_MS, approvalAssurance, approvalScopeFromToolName, approvals, migrateApprovals } from "../services/approvals";
 import { migrateAiMessageQueue } from "./message-queue";
 import { migrateAiModelAccess } from "./model-access-migrate";
 import { migrateAiQuotas } from "./quotas-migrate";
@@ -21,6 +23,8 @@ export const migrateCloudAi = async (): Promise<void> => {
   if (!outbox?.ready) {
     throw new Error("AI live updates write to events.outbox, which does not exist. Run Core's events migration before the AI migration.");
   }
+  // Approval requests reference auth.users, so they follow the check that Core's own migrations ran.
+  await migrateApprovals();
   await sql`CREATE SCHEMA IF NOT EXISTS ai`.simple();
   console.log("  ✓ ai schema");
 
@@ -640,7 +644,12 @@ export const migrateCloudAi = async (): Promise<void> => {
     PRIMARY KEY (turn_id, request_id)
   )`.simple();
 
+  await sql`ALTER TABLE ai.pending_actions ADD COLUMN IF NOT EXISTS approval_id UUID`.simple();
   await sql`ALTER TABLE ai.pending_actions ADD COLUMN IF NOT EXISTS review JSONB`.simple();
+  // A code run asks for its nested HTTP requests and Actions; their remembered approval names a website or Action, not the run.
+  await sql`ALTER TABLE ai.pending_actions ADD COLUMN IF NOT EXISTS remember_tool_name TEXT`.simple();
+  await sql`ALTER TABLE ai.pending_actions ADD COLUMN IF NOT EXISTS allow_chat BOOLEAN NOT NULL DEFAULT FALSE`.simple();
+  await sql`ALTER TABLE ai.pending_actions ADD COLUMN IF NOT EXISTS consumed_inline BOOLEAN NOT NULL DEFAULT FALSE`.simple();
 
   await sql`
     CREATE UNIQUE INDEX IF NOT EXISTS idx_ai_pending_actions_turn_call
@@ -653,6 +662,12 @@ export const migrateCloudAi = async (): Promise<void> => {
     WHERE status = 'pending'
   `.simple();
 
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_ai_pending_actions_approval
+    ON ai.pending_actions(approval_id)
+    WHERE approval_id IS NOT NULL
+  `.simple();
+
   await sql`
     DO $$
     BEGIN
@@ -700,13 +715,39 @@ export const migrateCloudAi = async (): Promise<void> => {
     FROM ai.tool_approval_preferences
     WHERE tool_name ~ '^[a-z][a-z0-9-]*__(query|action)__'
       AND NOT (length(tool_name) = 64 AND tool_name ~ '__[0-9a-f]{12}$')
-    ON CONFLICT (actor_user_id, tool_name, approval_scope) DO NOTHING
+    ON CONFLICT DO NOTHING
   `.simple();
   await sql`
     DELETE FROM ai.tool_approval_preferences
     WHERE tool_name ~ '^[a-z][a-z0-9-]*__(query|action)__'
   `.simple();
 
+  // An approval limited to one chat ends with that chat. NULL means it applies everywhere.
+  await sql`
+    ALTER TABLE ai.tool_approval_preferences
+    ADD COLUMN IF NOT EXISTS conversation_id UUID REFERENCES ai.conversations(id) ON DELETE CASCADE
+  `.simple();
+  await sql`
+    CREATE UNIQUE INDEX IF NOT EXISTS ai_tool_approval_preferences_reach
+    ON ai.tool_approval_preferences(actor_user_id, tool_name, approval_scope, conversation_id) NULLS NOT DISTINCT
+  `.simple();
+  await sql`ALTER TABLE ai.tool_approval_preferences DROP CONSTRAINT IF EXISTS ai_tool_approval_preferences_unique`.simple();
+  await sql`
+    CREATE INDEX IF NOT EXISTS idx_ai_tool_approval_preferences_conversation
+    ON ai.tool_approval_preferences(conversation_id)
+    WHERE conversation_id IS NOT NULL
+  `.simple();
+  // Addresses a chat's web searches returned and the pages it read link to, normalized; web_extract and fetch_file
+  // read them without asking. Recorded when the tool runs, so a read never scans stored results.
+  await sql`
+    CREATE TABLE IF NOT EXISTS ai.web_addresses (
+      conversation_id UUID NOT NULL REFERENCES ai.conversations(id) ON DELETE CASCADE,
+      address TEXT NOT NULL,
+      created_at TIMESTAMPTZ NOT NULL DEFAULT now(),
+      PRIMARY KEY (conversation_id, address)
+    )
+  `.simple();
+
   await sql`
     CREATE TABLE IF NOT EXISTS ai.tool_calls (
       id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
@@ -724,9 +765,23 @@ export const migrateCloudAi = async (): Promise<void> => {
       rejected_at TIMESTAMPTZ,
       completed_at TIMESTAMPTZ,
       CONSTRAINT ai_tool_calls_status_check CHECK (status IN ('pending', 'running', 'waiting_for_approval', 'waiting_for_frontend', 'completed', 'failed', 'rejected')),
-      CONSTRAINT ai_tool_calls_approval_state_check CHECK (approval_state IN ('not_required', 'waiting', 'approved_once', 'approved_always', 'approved_by_preference', 'rejected'))
+      CONSTRAINT ai_tool_calls_approval_state_check CHECK (approval_state IN ('not_required', 'waiting', 'approved_once', 'approved_for_chat', 'approved_always', 'approved_by_preference', 'rejected'))
     )
   `.simple();
+  await sql`
+    DO $$
+    BEGIN
+      IF NOT EXISTS (
+        SELECT 1 FROM pg_constraint
+        WHERE conname = 'ai_tool_calls_approval_state_check'
+          AND pg_get_constraintdef(oid) LIKE '%approved_for_chat%'
+      ) THEN
+        ALTER TABLE ai.tool_calls DROP CONSTRAINT IF EXISTS ai_tool_calls_approval_state_check;
+        ALTER TABLE ai.tool_calls ADD CONSTRAINT ai_tool_calls_approval_state_check
+          CHECK (approval_state IN ('not_required', 'waiting', 'approved_once', 'approved_for_chat', 'approved_always', 'approved_by_preference', 'rejected'));
+      END IF;
+    END $$
+  `.simple();
 
   await sql`
     CREATE UNIQUE INDEX IF NOT EXISTS idx_ai_tool_calls_turn_call
@@ -738,6 +793,7 @@ export const migrateCloudAi = async (): Promise<void> => {
     ON ai.tool_calls(conversation_id, created_at DESC)
   `.simple();
 
+  await sql`ALTER TABLE ai.tool_calls ADD COLUMN IF NOT EXISTS approval_decided_via TEXT`.simple();
   await sql`ALTER TABLE ai.tool_calls ADD COLUMN IF NOT EXISTS idempotency_key TEXT`.simple();
 
   // Capability shape, outcome, and latency belong to capabilities.executions,
@@ -2525,5 +2581,67 @@ export const migrateCloudAi = async (): Promise<void> => {
       `  ! ${legacyPaths.files} conversation and ${legacyPaths.project_files} project file paths keep a non-NFC Unicode form because a normalized twin exists`,
     );
   }
+  await backfillApprovalRequests();
   console.log("  ✓ ai conversation tables");
 };
+
+const backfillApprovalRequests = async (): Promise<void> => {
+  const decoded = (value: unknown): unknown => (typeof value === "string" ? JSON.parse(value) : value);
+  while (true) {
+    const count = await sql.begin(async (db) => {
+      // Completed turns and ownerless chats cannot still ask a person; leave their legacy rows alone.
+      const rows = await db<
+        {
+          id: string;
+          turn_id: string;
+          call_id: string;
+          tool_name: string;
+          approval_scope: string;
+          message: string | null;
+          review: unknown;
+          args: unknown;
+          allow_always: boolean;
+          allow_chat: boolean;
+          owner: string;
+          title: string;
+          expiry: Date;
+        }[]
+      >`SELECT a.*, c.created_by_user_id AS owner, c.title,
+        COALESCE(t.deadline, a.created_at + interval '24 hours') AS expiry
+        FROM ai.pending_actions a JOIN ai.turns t ON t.id=a.turn_id JOIN ai.conversations c ON c.id=a.conversation_id
+        WHERE a.status='pending' AND a.kind IN ('approval','custom_approval') AND a.approval_id IS NULL
+          AND c.created_by_user_id IS NOT NULL AND t.status='waiting_for_action'
+          -- A running Assistant may already have asked again for this action; keep the request it saw.
+          AND NOT EXISTS (SELECT 1 FROM approvals.requests r
+            WHERE r.requester_kind='assistant_turn' AND r.requester_ref=a.turn_id::text || '/' || a.call_id)
+        ORDER BY a.created_at, a.id LIMIT 200 FOR UPDATE OF a SKIP LOCKED`;
+      for (const row of rows) {
+        const review = CapabilityActionReviewSchema.safeParse(row.review == null ? null : decoded(row.review));
+        // request computes both canonical digests; preserve the original wait deadline, including expiry.
+        const record = await approvals.request(
+          {
+            ...approvalScopeFromToolName(row.tool_name),
+            approvalScope: row.approval_scope,
+            requester: { kind: "assistant_turn", ref: `${row.turn_id}/${row.call_id}`, appId: "assistant", title: row.title },
+            subjectId: row.owner,
+            approverUserId: row.owner,
+            // Every turn that can ask allows remembering, so these flags hold what the call offers.
+            assurance: approvalAssurance(row.allow_always || row.allow_chat),
+            sentence: row.message ?? row.tool_name,
+            review: review.success ? review.data : null,
+            input: decoded(row.args),
+            expiresInMs: Math.min(APPROVAL_MAX_WAIT_MS, row.expiry.getTime() - Date.now()),
+          },
+          db,
+        );
+        if (!record.ok) continue;
+        await db`UPDATE approvals.requests SET expires_at=${row.expiry},
+          status=CASE WHEN ${row.expiry} <= now() THEN 'expired' ELSE status END
+          WHERE id=${record.id}::uuid AND status='pending'`;
+        await db`UPDATE ai.pending_actions SET approval_id=${record.id}::uuid WHERE id=${row.id}::uuid`;
+      }
+      return rows.length;
+    });
+    if (!count) return;
+  }
+};

package/src/ai/openai-api-messages.ts

@@ -0,0 +1,53 @@
+import { i18n } from "@k2b/stdlib";
+
+const catalog = i18n.define({
+  baseLocale: "en",
+  messages: {
+    en: {
+      openai_api_disabled: "The OpenAI-compatible API is turned off. Contact an administrator.",
+      invalid_api_key: "Use an active API key with the access “AI models only”. Create one in your Cloud profile.",
+      model_not_found: "This model is unavailable or you do not have access to it.",
+      invalid_request: "The request does not match the supported chat completion format.",
+      unsupported_content:
+        "Only text messages with system, developer, user or assistant roles are supported. Tool calls are not supported.",
+      unsupported_parameter: "This parameter is not supported. This API gives access to the models only.",
+      context_length_exceeded: "Your messages exceed this model's context window. Shorten them and try again.",
+      request_too_large: "The request body exceeds the limit derived from your available models' context windows.",
+      ai_disabled: "AI is turned off. Contact an administrator.",
+      model_access_denied: "You do not have access to this model. Contact an administrator.",
+      missing_provider_credential: "This model's provider is not configured. Contact an administrator.",
+      insufficient_quota:
+        "Your Assistant usage limit is reached, or your usage could not be measured. Wait for the reset or contact an administrator.",
+      too_many_concurrent_requests: "You have too many simultaneous requests. Wait for a request to finish and try again.",
+      rate_limit_exceeded: "Too many requests. Wait and try again.",
+      upstream_error: "The model provider could not complete your request. Try again later.",
+      internal_error: "Cloud could not process your request. Try again later.",
+      not_found: "This OpenAI-compatible API route does not exist.",
+    },
+    de: {
+      openai_api_disabled: "Die OpenAI-kompatible API ist ausgeschaltet. Wende dich an einen Administrator.",
+      invalid_api_key: "Verwende einen aktiven API-Schlüssel mit dem Zugriff „Nur KI-Modelle“. Du erstellst ihn in deinem Cloud-Profil.",
+      model_not_found: "Dieses Modell ist nicht verfügbar oder nicht für dich freigegeben.",
+      invalid_request: "Deine Anfrage entspricht nicht dem unterstützten Format für Chat-Vervollständigungen.",
+      unsupported_content:
+        "Nur Textnachrichten mit den Rollen system, developer, user oder assistant werden unterstützt. Werkzeugaufrufe werden nicht unterstützt.",
+      unsupported_parameter: "Dieser Parameter wird nicht unterstützt. Diese API gibt nur Zugriff auf die Modelle.",
+      context_length_exceeded: "Deine Nachrichten überschreiten das Kontextfenster dieses Modells. Kürze sie und versuche es erneut.",
+      request_too_large: "Deine Anfrage überschreitet die aus den Kontextfenstern deiner verfügbaren Modelle abgeleitete Größenbegrenzung.",
+      ai_disabled: "KI ist ausgeschaltet. Wende dich an einen Administrator.",
+      model_access_denied: "Dieses Modell ist nicht für dich freigegeben. Wende dich an einen Administrator.",
+      missing_provider_credential: "Der Anbieter dieses Modells ist nicht eingerichtet. Wende dich an einen Administrator.",
+      insufficient_quota:
+        "Dein Nutzungslimit im Assistenten ist erreicht, oder deine Nutzung konnte nicht gemessen werden. Warte auf das Zurücksetzen oder wende dich an einen Administrator.",
+      too_many_concurrent_requests: "Du hast zu viele gleichzeitige Anfragen. Warte, bis eine Anfrage beendet ist, und versuche es erneut.",
+      rate_limit_exceeded: "Zu viele Anfragen. Warte kurz und versuche es erneut.",
+      upstream_error: "Der Modellanbieter konnte deine Anfrage nicht abschließen. Versuche es später erneut.",
+      internal_error: "Cloud konnte deine Anfrage nicht verarbeiten. Versuche es später erneut.",
+      not_found: "Diese Route der OpenAI-kompatiblen API existiert nicht.",
+    },
+  },
+});
+
+export type OpenAiErrorCode = keyof ReturnType<typeof catalog.resolve>["t"];
+export const openAiApiMessages = (locale: string) => catalog.resolve([locale]).t;
+export const checkOpenAiApiMessages = () => catalog.check();