@agent-native/core 0.160.1 → 0.161.0

package/corpus/templates/mail/.agents/skills/email-drafts/SKILL.md

@@ -69,6 +69,30 @@ Before creating or rewriting a draft, read the user's drafting settings with `pn
 - Follow `writingStyle` when present.
 - Keep generated copy natural and specific. Avoid generic AI email tropes, headings, and over-formal filler unless the user asks for that style.
 
+## Updating Durable Drafting Settings
+
+Treat requests to permanently change, add to, or remove a writing-style rule as
+settings changes, not drafting requests. Route them to `update-mail-settings`.
+Do not call `manage-draft`, open the compose UI, or create a draft unless the user separately asks
+to create or edit an email draft.
+
+For a durable settings request:
+
+1. Read the current settings with `get-mail-settings`.
+2. Merge the requested rule into the existing `writingStyle`, preserving
+   unrelated instructions. For a removal, remove only the requested rule.
+3. If the requested change is ambiguous, conflicts with existing guidance, or
+   would materially rewrite the style, show the proposed merged wording and
+   ask the user to confirm before changing it.
+4. Call `update-mail-settings` with the complete merged `writingStyle` value.
+5. Re-read the settings with `get-mail-settings` and confirm the persisted result. Do not
+   report success based only on the update call response.
+
+If the user asks both to change the durable style and to draft an email, update
+the settings first, then create the separately requested draft using the
+confirmed settings. A style-setting request alone must leave compose state
+unchanged.
+
 ## How It Works
 
 1. **Write** `writeAppState("compose-{id}", draft)` — the shared application state row changes

package/corpus/templates/mail/actions/get-mail-settings.ts

@@ -17,7 +17,7 @@ function normalize(settings: Partial<UserSettings> | undefined, email: string) {
 
 export default defineAction({
   description:
-    "Read the user's mail drafting settings, including configured signature and writing style.",
+    "Read the user's current mail drafting settings, including configured signature and writing style. Use this before updating a durable preference so unrelated settings can be preserved.",
   schema: z.object({}),
   http: { method: "GET" },
   readOnly: true,

package/corpus/templates/mail/actions/update-mail-settings.ts

@@ -11,16 +11,20 @@ const settingsSchema = z.object({
   signature: z
     .string()
     .optional()
-    .describe("Markdown/plain-text signature to add to new drafts"),
+    .describe(
+      "Persistent Markdown/plain-text signature for new drafts. Preserve the existing signature unless the user asks to replace it.",
+    ),
   writingStyle: z
     .string()
     .optional()
-    .describe("Short notes describing how generated drafts should sound"),
+    .describe(
+      "Persistent writing rules for generated drafts. Read the current setting first, merge the requested change, and preserve unrelated rules.",
+    ),
 });
 
 export default defineAction({
   description:
-    "Update the user's mail drafting settings, including signature and writing style.",
+    "Update the user's persistent mail drafting settings, including signature and writing style. Use this for durable preferences, not email draft content. Read the current settings first and preserve fields the user did not ask to change.",
   schema: settingsSchema,
   run: async (args) => {
     const ownerEmail = getRequestUserEmail();

package/corpus/templates/mail/app/i18n/en-US.ts

@@ -501,7 +501,9 @@ const messages = {
     signature: "Signature",
     importFromGmail: "Import from Gmail",
     signatureHelp:
-      "Added to new drafts before quoted reply history. Markdown links and images are supported.",
+      "Added to new drafts before quoted reply history. Paste an image here or use Add image; Markdown links and images are supported.",
+    addSignatureImage: "Add image",
+    signatureImageUploadFailed: "Failed to upload signature image",
     writingStyle: "Writing style",
     writingStylePlaceholder: "Short, specific, warm. Avoid formal filler.",
     saveDraftingSettings: "Save drafting settings",

package/corpus/templates/mail/app/pages/SettingsPage.tsx

@@ -37,6 +37,7 @@ import {
   IconClock,
   IconPlayerPlay,
   IconSignature,
+  IconPhoto,
   IconFilter,
   IconInfoCircle,
   IconMessage2,
@@ -89,6 +90,7 @@ import {
 } from "@/hooks/use-automations";
 import { useSettings, useUpdateSettings } from "@/hooks/use-emails";
 import { useNavigationState } from "@/hooks/use-navigation-state";
+import { openFilePicker, uploadFile } from "@/lib/upload";
 import { cn } from "@/lib/utils";
 
 import changelog from "../../CHANGELOG.md?raw";
@@ -1137,6 +1139,7 @@ function DraftingSection() {
   const queryClient = useQueryClient();
   const [signature, setSignature] = useState("");
   const [writingStyle, setWritingStyle] = useState("");
+  const signatureSelectionRef = useRef({ start: 0, end: 0 });
   const importSignature = useActionMutation("import-gmail-signature", {
     onSuccess: (result) => {
       setSignature(result.signature);
@@ -1168,6 +1171,49 @@ function DraftingSection() {
   const isDirty =
     signature !== savedSignature || writingStyle !== savedWritingStyle;
 
+  const insertSignatureImage = async (
+    file: File,
+    start: number,
+    end: number,
+  ) => {
+    try {
+      const result = await uploadFile(file);
+      const markdown = `![${file.name.replace(/\.[^.]+$/, "")}](${result.url})`;
+      setSignature(
+        (current) =>
+          `${current.slice(0, start)}${markdown}${current.slice(end)}`,
+      );
+    } catch {
+      toast.error(t("settings.signatureImageUploadFailed"));
+    }
+  };
+
+  const handleSignaturePaste = (
+    event: React.ClipboardEvent<HTMLTextAreaElement>,
+  ) => {
+    const image = Array.from(event.clipboardData.items)
+      .find((item) => item.kind === "file" && item.type.startsWith("image/"))
+      ?.getAsFile();
+    if (!image) return;
+    event.preventDefault();
+    const target = event.currentTarget;
+    void insertSignatureImage(
+      image,
+      target.selectionStart,
+      target.selectionEnd,
+    );
+  };
+
+  const handleSignatureImage = async () => {
+    const file = await openFilePicker("image/*");
+    if (!file) return;
+    await insertSignatureImage(
+      file,
+      signatureSelectionRef.current.start,
+      signatureSelectionRef.current.end,
+    );
+  };
+
   const handleSave = () => {
     updateSettings.mutate(
       {
@@ -1223,10 +1269,27 @@ function DraftingSection() {
                   )}
                   {t("settings.importFromGmail")}
                 </Button>
+                <Button
+                  type="button"
+                  variant="ghost"
+                  size="sm"
+                  className="h-6 px-2 text-[11px]"
+                  onClick={() => void handleSignatureImage()}
+                >
+                  <IconPhoto className="h-3 w-3" />
+                  {t("settings.addSignatureImage")}
+                </Button>
               </div>
               <Textarea
                 value={signature}
                 onChange={(event) => setSignature(event.target.value)}
+                onPaste={handleSignaturePaste}
+                onSelect={(event) => {
+                  signatureSelectionRef.current = {
+                    start: event.currentTarget.selectionStart,
+                    end: event.currentTarget.selectionEnd,
+                  };
+                }}
                 placeholder={"Best,\nSteve"}
                 rows={5}
                 className="resize-none px-3 py-2 text-[13px] placeholder:text-muted-foreground/40"

package/corpus/templates/mail/changelog/2026-08-17-gmail-signatures-now-preserve-images-and-support-paste-or-up.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-17
+---
+
+Gmail signatures now preserve images and support paste or upload in Mail

package/corpus/templates/mail/changelog/2026-08-17-mail-now-updates-durable-drafting-preferences-without-openin.md

@@ -0,0 +1,6 @@
+---
+type: fixed
+date: 2026-08-17
+---
+
+Mail now updates durable drafting preferences without opening a draft

package/corpus/templates/mail/server/plugins/agent-chat.ts

@@ -23,6 +23,7 @@ const INITIAL_TOOL_NAMES = [
   "refresh-list",
   "navigate",
   "get-mail-settings",
+  "update-mail-settings",
   "find-contact",
   "provider-api-catalog",
   "provider-api-docs",
@@ -172,6 +173,24 @@ Before drafting or rewriting email copy, run \`get-mail-settings\`.
 - Follow \`writingStyle\` when present.
 - Draft bodies use Markdown only. Avoid generic AI email tropes, headings, and over-formal filler unless the user explicitly asks for a formal template.
 
+## Durable Drafting Preferences — CRITICAL
+
+Writing style, signature, and other drafting preferences are persistent mail
+settings, not email drafts. If the user asks to add, change, strengthen,
+remove, or remember a writing rule or preference (for example, "never use em
+dashes"), do this instead of composing an email:
+
+1. Run \`get-mail-settings\`.
+2. Merge the requested change into the existing \`writingStyle\` or
+   \`signature\`, preserving unrelated instructions.
+3. Run \`update-mail-settings\` with the complete merged value.
+4. Confirm the returned setting was updated.
+
+Do not call \`manage-draft\`, \`queue-email-draft\`, or \`send-email\` for a
+preference-only request. Only create or edit an email when the user separately
+asks for an email. If a request asks for both a preference change and an email,
+update the preference first, then read it again and apply it to the email.
+
 When the user asks to draft/email a specific person (e.g., "email my wife", "draft an email to Alice"):
 - This is a NEW email \u2014 use manage-draft with --action=create and mode "compose", NOT "reply"
 - Look up the recipient's email from AGENTS.md contacts or ask the user

package/corpus/templates/mail/shared/gmail-signature.ts

@@ -45,7 +45,16 @@ export function htmlSignatureToMarkdown(html: string): string {
     .replace(/<style[\s\S]*?<\/style>/gi, "");
 
   next = next.replace(/<br\s*\/?>/gi, "\n");
-  next = next.replace(/<img\b[^>]*>/gi, "");
+  const imageTokens: string[] = [];
+  next = next.replace(/<img\b[^>]*>/gi, (tag) => {
+    const src = safeUrl(attr(tag, "src"));
+    if (!src) return "";
+    const alt = cleanMarkdown(attr(tag, "alt") || attr(tag, "title") || "");
+    const image = `![${alt.replace(/]/g, "\\]")}](${normalizeMarkdownUrl(src)})`;
+    const token = `\uE100${imageTokens.length}\uE101`;
+    imageTokens.push(image);
+    return token;
+  });
   next = next.replace(
     /<a\b[^>]*href\s*=\s*(?:"[^"]*"|'[^']*'|[^\s>]+)[^>]*>([\s\S]*?)<\/a>/gi,
     (match, label) => {
@@ -69,5 +78,8 @@ export function htmlSignatureToMarkdown(html: string): string {
     )
     .replace(/<[^>]+>/g, "");
 
-  return cleanMarkdown(next);
+  return cleanMarkdown(next).replace(
+    /\uE100(\d+)\uE101/g,
+    (match, index: string) => imageTokens[Number(index)] ?? match,
+  );
 }

package/corpus/templates/mail/shared/signature.ts

@@ -14,16 +14,7 @@ function splitQuotedContent(body: string): [string, string] {
 }
 
 export function normalizeSignature(signature?: string | null): string {
-  return stripSignatureImages(signature ?? "").trim();
-}
-
-export function stripSignatureImages(signature: string): string {
-  return signature
-    .replace(
-      /\[!\[[\s\S]*?\]\((?:https?:\/\/|data:image\/)[^)]*\)\]\([^)]*\)/gi,
-      "",
-    )
-    .replace(/!\[[\s\S]*?\]\((?:https?:\/\/|data:image\/)[^)]*\)/gi, "")
+  return (signature ?? "")
     .split("\n")
     .map((line) => line.replace(/[ \t]+$/g, ""))
     .join("\n")

package/corpus/templates/slides/actions/generate-slides-ai.ts

@@ -62,6 +62,8 @@ Rules:
 - Last slide should be a summary or call-to-action
 - Content should be concise and presentation-ready (not paragraphs)
 - Use bullet points for lists, keep each point brief
+- Keep title, section, statement, and call-to-action slides centered with generous, even margins
+- Do not use emoji as decorative icons or bullets; use plain text bullets or HTML/CSS shapes instead
 - Do not invent factual numbers, metrics, URLs, source attributions, dates, success rates, benchmarks, customer names, or case-study results. Only include concrete factual claims if they are present in the topic/context. If a useful metric is unknown, use qualitative wording, [metric TBD], or clearly label it as a draft assumption.
 - ${imageInstruction}
 

package/corpus/templates/slides/actions/patch-deck.ts

@@ -357,7 +357,7 @@ export function applyOperation(deck: any, op: Operation): void {
       if (slides.length === 0 && !op.allowEmpty) {
         slides.push({
           id: `slide-${Date.now()}-fallback`,
-          content: `<div class="fmd-slide" style="padding: 80px 110px; display: flex; flex-direction: column; justify-content: center;"><div style="font-size: 28px; font-weight: 600; color: rgba(255,255,255,0.4);">Double-click to edit</div></div>`,
+          content: `<div class="fmd-slide" style="box-sizing: border-box; width: 100%; height: 100%; padding: 80px 110px; display: flex; flex-direction: column; justify-content: center; align-items: center; text-align: center;"><div style="font-size: 28px; font-weight: 600; color: hsl(var(--muted-foreground) / 0.4);">Double-click to edit</div></div>`,
           notes: "",
           layout: "blank",
         });

package/corpus/templates/slides/app/components/ThemeToggle.tsx

@@ -26,6 +26,7 @@ export function ThemeToggle({ className }: { className?: string }) {
         <Button
           variant="ghost"
           size="icon"
+          aria-label={t("root.toggleTheme")}
           onClick={() => setTheme(isDark ? "light" : "dark")}
           className={cn("h-7 w-7 text-muted-foreground", className)}
         >

package/corpus/templates/slides/app/components/editor/SlideThumbnailContextMenu.tsx

@@ -0,0 +1,59 @@
+import { useT } from "@agent-native/core/client/i18n";
+import type { ReactElement, ReactNode } from "react";
+
+import {
+  ContextMenu,
+  ContextMenuContent,
+  ContextMenuItem,
+  ContextMenuSeparator,
+  ContextMenuTrigger,
+} from "@/components/ui/context-menu";
+
+interface SlideThumbnailContextMenuProps {
+  children: ReactElement;
+  canDelete?: boolean;
+  onSelect: () => void;
+  onDuplicate: () => void;
+  onDelete: () => void;
+  /** Optional extra items for the owning editor to add later. */
+  childrenAfterActions?: ReactNode;
+}
+
+/**
+ * Keep slide actions discoverable without removing the compact hover buttons.
+ * The trigger stays the thumbnail itself, so a right-click works anywhere on
+ * the preview and the menu remains usable with a keyboard once the thumbnail
+ * has focus.
+ */
+export function SlideThumbnailContextMenu({
+  children,
+  canDelete = true,
+  onSelect,
+  onDuplicate,
+  onDelete,
+  childrenAfterActions,
+}: SlideThumbnailContextMenuProps) {
+  const t = useT();
+
+  return (
+    <ContextMenu>
+      <ContextMenuTrigger asChild onContextMenu={onSelect}>
+        {children}
+      </ContextMenuTrigger>
+      <ContextMenuContent>
+        <ContextMenuItem onSelect={onDuplicate}>
+          {t("editorSidebar.duplicateSlide")}
+        </ContextMenuItem>
+        <ContextMenuSeparator />
+        {childrenAfterActions}
+        <ContextMenuItem
+          disabled={!canDelete}
+          onSelect={onDelete}
+          className="text-destructive focus:text-destructive"
+        >
+          {t("editorSidebar.deleteSlide")}
+        </ContextMenuItem>
+      </ContextMenuContent>
+    </ContextMenu>
+  );
+}

package/corpus/templates/slides/app/global.css

@@ -431,6 +431,7 @@ button[title="Open agent sidebar"] {
 
 /* Full-bleed wrapper for blank-layout slides */
 .fmd-slide {
+  position: relative;
   width: 100%;
   height: 100%;
   display: flex;

package/corpus/templates/slides/app/lib/normalize-slide-padding.ts

@@ -6,16 +6,45 @@
  * value here makes a successful-looking agent edit a no-op in the renderer.
  */
 export function normalizeSlidePadding(html: string): string {
-  if (!html.includes('class="fmd-slide"')) return html;
+  for (const match of html.matchAll(/<div\b[^>]*>/gi)) {
+    const openingTag = match[0];
+    const classMatch = /\bclass\s*=\s*(["'])(.*?)\1/i.exec(openingTag);
 
-  return html.replace(
-    /(<div\b[^>]*\bclass="fmd-slide"[^>]*\bstyle=")([^"]*)(")/,
-    (_match, before, style, after) => {
-      const hasPadding = /(?:^|;)\s*padding\s*:/i.test(style);
-      const nextStyle = hasPadding
-        ? style
-        : `padding: 80px 110px;${style.startsWith(" ") ? "" : " "}${style}`;
-      return `${before}${nextStyle}${after}`;
-    },
-  );
+    if (!classMatch || !/\bfmd-slide\b/i.test(classMatch[2])) continue;
+
+    const styleMatch = /\bstyle\s*=\s*(["'])(.*?)\1/i.exec(openingTag);
+    if (styleMatch) {
+      const style = styleMatch[2];
+      if (/(?:^|;)\s*padding\s*:/i.test(style)) return html;
+
+      const nextStyle = `padding: 80px 110px;${
+        style.startsWith(" ") ? "" : " "
+      }${style}`;
+      const nextStyleAttribute = styleMatch[0].replace(style, nextStyle);
+      const nextOpeningTag = openingTag.replace(
+        styleMatch[0],
+        nextStyleAttribute,
+      );
+
+      return (
+        html.slice(0, match.index) +
+        nextOpeningTag +
+        html.slice(match.index + openingTag.length)
+      );
+    }
+
+    const classEnd = classMatch.index + classMatch[0].length;
+    const nextOpeningTag =
+      openingTag.slice(0, classEnd) +
+      ' style="padding: 80px 110px;"' +
+      openingTag.slice(classEnd);
+
+    return (
+      html.slice(0, match.index) +
+      nextOpeningTag +
+      html.slice(match.index + openingTag.length)
+    );
+  }
+
+  return html;
 }

package/corpus/templates/slides/changelog/2026-08-17-stable-layout-and-slide-editing.md

@@ -0,0 +1,6 @@
+---
+type: improved
+date: 2026-08-17
+---
+
+Slides now keep generated layouts stable, surface both-axis overflow, and make slide and text-box editing easier to discover.

package/corpus/templates/slides/shared/deck-title.ts

@@ -107,14 +107,22 @@ export function deriveDeckTitleFromSlideContent(
     }
   }
 
-  const styledTextPattern =
-    /<([a-z][\w:-]*)\b[^>]*\bstyle\s*=\s*(["'])([\s\S]*?)\2[^>]*>([\s\S]*?)<\/\1>/gi;
-  for (const match of content.matchAll(styledTextPattern)) {
+  const styledOpeningPattern =
+    /<([a-z][\w:-]*)\b[^>]*\bstyle\s*=\s*(["'])([\s\S]*?)\2[^>]*>/gi;
+  for (const match of content.matchAll(styledOpeningPattern)) {
     const fontSize = Number.parseFloat(
       match[3]?.match(/(?:^|;)\s*font-size\s*:\s*([\d.]+)px/i)?.[1] ?? "0",
     );
     if (fontSize < 28) continue;
-    const text = usableCandidate(match[4] ?? "");
+
+    const bodyStart = (match.index ?? 0) + match[0].length;
+    const closingTag = new RegExp(`</${match[1]}\\s*>`, "i").exec(
+      content.slice(bodyStart),
+    );
+    const body = closingTag
+      ? content.slice(bodyStart, bodyStart + closingTag.index)
+      : "";
+    const text = usableCandidate(body);
     if (text) candidates.push({ score: fontSize, text });
   }
 

package/dist/agent/production-agent.js

@@ -42,7 +42,7 @@ import { ProcessorChain, TripWire, toolCallsFromContent, } from "./processors.js
 import { startRun, subscribeToRun, getActiveRunForThread, getActiveRunForThreadAsync, getRun, abortRun, abortRunDurably, abortTurnDurably, tryClaimRunSlot, isHostedRuntime, resolveRunSoftTimeoutMs, resolveRunToolTimeoutCeilingMs, endsAfterCompletedToolWithoutAssistantFinal, } from "./run-manager.js";
 import { writeLedgerEntry, readLedgerEntry, clearLedgerForThread, insertRun, insertRunEvent, isTurnAborted, markRunAborted, updateRunHeartbeat, updateRunStatusIfRunning, setRunError, setRunTerminalReason, claimBackgroundRun, readBackgroundRunClaim, recordRunDiagnostic, countRunsForTurn, RUN_DIAG_STAGE, UNCLAIMED_BACKGROUND_RUN_GRACE_MS, } from "./run-store.js";
 import { buildCurrentTimeUserContext } from "./runtime-context.js";
-import { consumeAgentToolApproval, createAgentToolApproval, } from "./tool-approval-store.js";
+import { consumeAgentToolApproval, createAgentToolApproval, resolveAgentToolApprovalTurnId, } from "./tool-approval-store.js";
 import { findCompletedJournalEntry, } from "./tool-call-journal.js";
 import { redactSensitiveFields, sanitizeToolErrorText, sanitizeToolErrorValue, } from "./tool-error-redaction.js";
 import { describeToolResultImages, extractAgentImagesFromActionResult, } from "./tool-result-images.js";
@@ -6976,12 +6976,25 @@ export function createProductionAgentHandler(options) {
         const isChainedBackgroundContinuation = isBackgroundWorker && backgroundContinuationCount > 0;
         const runId = backgroundRunMarker?.runId ?? generateRunId();
         const effectiveThreadId = threadId ?? runId;
+        const resolvedApprovalTurnId = !isBackgroundWorker &&
+            ownerEmail &&
+            threadId &&
+            requestedApprovedToolCalls?.length
+            ? await resolveAgentToolApprovalTurnId({
+                ownerEmail,
+                orgId: getRequestOrgId() ?? null,
+                threadId,
+                requestedTurnId: requestTurnId,
+                approvalKeys: requestedApprovedToolCalls,
+            })
+            : null;
         const effectiveTurnId = typeof backgroundRunMarker?.turnId === "string" &&
             backgroundRunMarker.turnId.trim()
             ? backgroundRunMarker.turnId.trim()
-            : typeof requestTurnId === "string" && requestTurnId.trim()
-                ? requestTurnId.trim()
-                : runId;
+            : (resolvedApprovalTurnId ??
+                (typeof requestTurnId === "string" && requestTurnId.trim()
+                    ? requestTurnId.trim()
+                    : runId));
         const approvalStoreBinding = (binding) => {
             if (!ownerEmail) {
                 throw new Error("Cannot create or consume an approval without an authenticated owner");

package/dist/agent/tool-approval-migrations.d.ts

@@ -34,6 +34,7 @@ export declare const AGENT_TOOL_APPROVAL_TABLE_SQL: {
 };
 export declare const AGENT_TOOL_APPROVAL_INDEX_SQL = "CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_binding\n  ON agent_tool_approvals(owner_email, org_id, thread_id, tool_name, call_id, status)";
 export declare const AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL = "CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_logical\n  ON agent_tool_approvals(owner_email, org_id, thread_id, turn_id, tool_name, approval_key_hash, status)";
+export declare const AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL = "CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_recovery\n  ON agent_tool_approvals(owner_email, org_id, thread_id, approval_key_hash, status, turn_id)";
 /**
  * Durable approval grants are created and consumed on request paths, but their
  * schema belongs to the release migration boundary in production.

package/dist/agent/tool-approval-migrations.js

@@ -35,6 +35,8 @@ export const AGENT_TOOL_APPROVAL_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_age
   ON agent_tool_approvals(owner_email, org_id, thread_id, tool_name, call_id, status)`;
 export const AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_logical
   ON agent_tool_approvals(owner_email, org_id, thread_id, turn_id, tool_name, approval_key_hash, status)`;
+export const AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL = `CREATE INDEX IF NOT EXISTS idx_agent_tool_approvals_recovery
+  ON agent_tool_approvals(owner_email, org_id, thread_id, approval_key_hash, status, turn_id)`;
 /**
  * Durable approval grants are created and consumed on request paths, but their
  * schema belongs to the release migration boundary in production.
@@ -58,4 +60,12 @@ ${AGENT_TOOL_APPROVAL_INDEX_SQL}`,
             sqlite: AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL,
         },
     },
+    {
+        version: 3,
+        name: "agent-tool-approvals-recovery-index",
+        sql: {
+            postgres: AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL,
+            sqlite: AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL,
+        },
+    },
 ];

package/dist/agent/tool-approval-store.d.ts

@@ -9,6 +9,18 @@ export interface AgentToolApprovalBinding {
     expiresAt?: number;
 }
 export declare function hashAgentToolApprovalKey(approvalKey: string): string;
+/**
+ * Recover the durable scope for an approval continuation when a transport
+ * drops the original turn id. A single pending logical turn is safe to
+ * recover; multiple turns are deliberately ambiguous and stay unmatched.
+ */
+export declare function resolveAgentToolApprovalTurnId(binding: {
+    ownerEmail: string;
+    orgId?: string | null;
+    threadId?: string | null;
+    requestedTurnId?: string | null;
+    approvalKeys: readonly string[];
+}): Promise<string | null>;
 export declare function createAgentToolApproval(binding: AgentToolApprovalBinding): Promise<void>;
 /**
  * Atomically consume the server-created approval for one logical tool call.

package/dist/agent/tool-approval-store.js

@@ -1,7 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
 import { getDbExec, isPostgres, retryOnDdlRace } from "../db/client.js";
 import { ensureIndexExists, ensureTableExists } from "../db/ddl-guard.js";
-import { AGENT_TOOL_APPROVAL_INDEX_SQL, AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL, AGENT_TOOL_APPROVAL_TABLE_SQL, } from "./tool-approval-migrations.js";
+import { AGENT_TOOL_APPROVAL_INDEX_SQL, AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL, AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL, AGENT_TOOL_APPROVAL_TABLE_SQL, } from "./tool-approval-migrations.js";
 const APPROVAL_TTL_MS = 15 * 60_000;
 const APPROVAL_CLEANUP_AGE_MS = 24 * 60 * 60_000;
 let initPromise;
@@ -13,12 +13,14 @@ async function ensureAgentToolApprovalTable() {
                 await ensureTableExists("agent_tool_approvals", createSql);
                 await ensureIndexExists("idx_agent_tool_approvals_binding", AGENT_TOOL_APPROVAL_INDEX_SQL);
                 await ensureIndexExists("idx_agent_tool_approvals_logical", AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL);
+                await ensureIndexExists("idx_agent_tool_approvals_recovery", AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL);
                 return;
             }
             const client = getDbExec();
             await retryOnDdlRace(() => client.execute(createSql));
             await retryOnDdlRace(() => client.execute(AGENT_TOOL_APPROVAL_INDEX_SQL));
             await retryOnDdlRace(() => client.execute(AGENT_TOOL_APPROVAL_LOGICAL_INDEX_SQL));
+            await retryOnDdlRace(() => client.execute(AGENT_TOOL_APPROVAL_RECOVERY_INDEX_SQL));
         })().catch((error) => {
             initPromise = undefined;
             throw error;
@@ -29,6 +31,49 @@ async function ensureAgentToolApprovalTable() {
 export function hashAgentToolApprovalKey(approvalKey) {
     return createHash("sha256").update(approvalKey).digest("hex");
 }
+/**
+ * Recover the durable scope for an approval continuation when a transport
+ * drops the original turn id. A single pending logical turn is safe to
+ * recover; multiple turns are deliberately ambiguous and stay unmatched.
+ */
+export async function resolveAgentToolApprovalTurnId(binding) {
+    const approvalKeys = [...new Set(binding.approvalKeys)].slice(0, 200);
+    if (!binding.threadId || approvalKeys.length === 0)
+        return null;
+    await ensureAgentToolApprovalTable();
+    const now = Date.now();
+    const hashes = approvalKeys.map(hashAgentToolApprovalKey);
+    const placeholders = hashes.map(() => "?").join(", ");
+    const result = await getDbExec().execute({
+        sql: `SELECT turn_id FROM agent_tool_approvals
+      WHERE owner_email = ?
+        AND ((org_id IS NULL AND CAST(? AS TEXT) IS NULL) OR org_id = ?)
+        AND ((thread_id IS NULL AND CAST(? AS TEXT) IS NULL) OR thread_id = ?)
+        AND approval_key_hash IN (${placeholders})
+        AND status = 'pending'
+        AND expires_at > ?
+        AND turn_id IS NOT NULL`,
+        args: [
+            binding.ownerEmail,
+            binding.orgId ?? null,
+            binding.orgId ?? null,
+            binding.threadId,
+            binding.threadId,
+            ...hashes,
+            now,
+        ],
+    });
+    const turnIds = new Set((result.rows ?? [])
+        .map((row) => {
+        const value = row.turn_id;
+        return typeof value === "string" && value.trim() ? value.trim() : null;
+    })
+        .filter((turnId) => turnId !== null));
+    const requestedTurnId = binding.requestedTurnId?.trim();
+    if (requestedTurnId && turnIds.has(requestedTurnId))
+        return requestedTurnId;
+    return turnIds.size === 1 ? [...turnIds][0] : null;
+}
 export async function createAgentToolApproval(binding) {
     await ensureAgentToolApprovalTable();
     const now = Date.now();

package/dist/agent/types.d.ts

@@ -232,7 +232,9 @@ export interface AgentChatRequest {
      * `approval_required`; the client re-issues the turn (typically an empty
      * continuation) with the approved call's key here so the gate lets it run.
      * Keys not present here keep the action paused. The model never sees or sets
-     * this — it is supplied by the human's approve affordance.
+     * this — it is supplied by the human's approve affordance. Clients should
+     * preserve the original turnId; the server can recover one uniquely pending
+     * durable grant when a transport drops it, but refuses ambiguous matches.
      */
     approvedToolCalls?: string[];
 }