@agent-native/core 0.155.0 → 0.157.0

package/corpus/templates/slides/app/context/DeckContext.tsx

@@ -223,7 +223,9 @@ interface DeckContextType {
     deckId: string,
     layout?: SlideLayout,
     afterIndex?: number,
+    options?: { persistence?: "debounced" | "immediate" },
   ) => string;
+  flushDeckSave: (deckId: string) => Promise<void>;
   updateSlide: (
     deckId: string,
     slideId: string,
@@ -499,6 +501,38 @@ function drainPendingDeckOps(deckId: string): Promise<void> {
   return next;
 }
 
+/**
+ * Wait for a deck's in-flight save(s) to fully settle, including any
+ * follow-up drain chained by immediateFlushRequests for ops queued while a
+ * save was already running, and any requeued retry after a failed attempt.
+ * Used when a caller must not proceed (e.g. firing an agent request against
+ * a slide) until an "immediate" persistence op has actually reached the
+ * server. Throws if the save ultimately fails after retries exhaust, since
+ * `drainPendingDeckOps` swallows save errors internally to drive its own
+ * retry loop and its promise always resolves regardless of outcome.
+ */
+async function flushDeckSave(deckId: string): Promise<void> {
+  for (let i = 0; i < 40; i++) {
+    const active = inFlightSaveChains.get(deckId);
+    if (active) {
+      await active;
+      continue;
+    }
+    if (failedSaveDecks.has(deckId)) {
+      throw new Error(
+        `Failed to save deck ${deckId} after ${MAX_DECK_SAVE_RETRIES} attempts`,
+      );
+    }
+    if (pendingOpsQueue.has(deckId) || pendingSaves.has(deckId)) {
+      // A failed op was requeued for retry, or a debounced save is armed;
+      // wait for it to actually run rather than declaring success early.
+      await new Promise((resolve) => setTimeout(resolve, 50));
+      continue;
+    }
+    return;
+  }
+}
+
 function enqueueDeckOp(
   deckId: string,
   op: GranularOp,
@@ -2095,7 +2129,12 @@ export function DeckProvider({ children }: { children: ReactNode }) {
   );
 
   const addSlide = useCallback(
-    (deckId: string, layout: SlideLayout = "content", afterIndex?: number) => {
+    (
+      deckId: string,
+      layout: SlideLayout = "content",
+      afterIndex?: number,
+      addOptions?: { persistence?: "debounced" | "immediate" },
+    ) => {
       markDeckDirty(deckId);
       const newSlide: Slide = {
         id: nanoid(8),
@@ -2128,7 +2167,7 @@ export function DeckProvider({ children }: { children: ReactNode }) {
         afterSlideId,
         fields: addSlideFields(newSlide),
       };
-      enqueueDeckOp(deckId, op);
+      enqueueDeckOp(deckId, op, addOptions);
       if (before) recordUndo(before, op, { label: "Add slide" });
 
       return newSlide.id;
@@ -2329,6 +2368,7 @@ export function DeckProvider({ children }: { children: ReactNode }) {
         refreshOpenDeck: refetchOpenDeckIfChanged,
         getDeck,
         addSlide,
+        flushDeckSave,
         updateSlide,
         deleteSlide,
         duplicateSlide,

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

@@ -290,53 +290,20 @@ button[title="Open agent sidebar"] {
 
 .deck-editor-context-toolbar-host--narrow {
   display: flex;
-  justify-content: flex-end;
+  justify-content: flex-start;
 }
 
 .deck-editor-context-toolbar-host--narrow
   > [data-slide-inline-edit-surface="true"] {
   min-width: 0;
-  width: fit-content;
-  max-width: 100%;
-  flex: 0 1 auto;
-}
-
-@container deck-editor (max-width: 1149px) {
-  .deck-editor-context-toolbar-host--wide {
-    display: none;
-  }
-
-  .deck-editor-context-toolbar-host--narrow {
-    display: flex;
-  }
+  width: 100%;
+  flex: 1 1 auto;
 }
 
-@container deck-editor (min-width: 1150px) {
-  .deck-editor-context-toolbar-host--narrow {
-    display: none;
-  }
-
-  .deck-editor-context-toolbar-host--wide[data-context-toolbar-visible="true"] {
-    display: flex;
-    flex: 1 1 0%;
-    align-items: center;
-    justify-content: flex-end;
-  }
-
-  .deck-editor-context-toolbar-host--wide
-    > [data-slide-inline-edit-surface="true"] {
-    min-width: 0;
-    max-width: 100%;
-  }
-
-  .deck-editor-context-toolbar-host--wide .slide-context-toolbar--top-row {
-    height: 2.75rem;
-    justify-content: flex-end;
-    border: 0;
-    background: transparent;
-    padding-inline: 0;
-  }
-}
+/* The element-controls toolbar (New Slide, text/style controls, zoom)
+ * always renders as its own row below the title/Share/Present bar, at every
+ * viewport size — the "wide" host above stays permanently hidden by the
+ * base rule so the row never merges into the title bar on large screens. */
 
 @container (max-width: 36rem) {
   .deck-grid {

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

@@ -514,11 +514,15 @@ const messages = {
     generatingSlide: "Generating slide",
     uploadFailed: "Upload failed",
     uploadAttachedFileFailed: "Could not upload the attached file.",
+    newSlideSaveFailed: "Couldn't save the new slide. Please try again.",
     addSlides: "Add slides",
     addEmptySlide: "Add empty slide",
     noAi: "no AI",
     duplicateCurrentSlide: "Duplicate current slide",
     promptPlaceholder: "Describe the slides you want...",
+    newSlide: "New slide",
+    closeAddSlides: "Close",
+    describeThisSlide: "Describe this slide",
   },
   presentation: {
     loadFailed: "Could not load this presentation.",

package/corpus/templates/slides/app/pages/DeckEditor.tsx

@@ -182,6 +182,7 @@ export default function DeckEditor() {
     duplicateSlide,
     duplicateDeck,
     addSlide,
+    flushDeckSave,
     reorderSlides,
     markDeckDirty,
     undo,
@@ -218,6 +219,25 @@ export default function DeckEditor() {
     pendingDeckNavigationBlocker.proceed();
   }, [pendingDeckNavigationBlocker]);
   const { generating } = useAgentGenerating();
+  // Dedicated instance (not the `generating` one above, which reflects ANY
+  // agent chat activity) so an unrelated concurrent run can't be mistaken
+  // for this one finishing and clear the flag early. Owning the submit call
+  // here — instead of in EditorSidebar, which unmounts when the rail closes
+  // on narrow viewports — keeps both the run-scoping and the completion
+  // tracking correct across a remount.
+  const { generating: addSlideAgentGenerating, submit: addSlideAgentSubmit } =
+    useAgentGenerating();
+  const sawAddSlideAgentGeneratingRef = useRef(false);
+  useEffect(() => {
+    if (addSlideAgentGenerating) {
+      sawAddSlideAgentGeneratingRef.current = true;
+      return;
+    }
+    if (addSlideGenerating && sawAddSlideAgentGeneratingRef.current) {
+      sawAddSlideAgentGeneratingRef.current = false;
+      setAddSlideGenerating(false);
+    }
+  }, [addSlideGenerating, addSlideAgentGenerating]);
   // Generation intent can arrive after this route mounts because the user
   // answers pre-generation questions from the empty editor.
   const wasNewDeckCreation = useRef(searchParams.get("generating") === "1");
@@ -231,6 +251,14 @@ export default function DeckEditor() {
   const [sidebarOpen, setSidebarOpen] = useState(
     () => typeof window !== "undefined" && window.innerWidth >= 768,
   );
+  // The slide just inserted via the toolbar's New Slide button, so the rail
+  // can anchor the "describe this slide" popover to its thumbnail once it
+  // mounts — even though the button that sets this now lives in the
+  // toolbar, outside the rail.
+  const [describeSlideId, setDescribeSlideId] = useState<string | null>(null);
+  useEffect(() => {
+    setDescribeSlideId(null);
+  }, [id]);
   const [contextToolbarSlot, setContextToolbarSlot] =
     useState<HTMLDivElement | null>(null);
   const [wideContextToolbarSlot, setWideContextToolbarSlot] =
@@ -807,49 +835,92 @@ export default function DeckEditor() {
     return () => document.removeEventListener("keydown", handleKeyDown);
   }, [deck, id, activeSlideId, deleteSlideWithUndo, pinMode, drawMode]);
 
-  // Cmd/Ctrl+C then Cmd/Ctrl+V duplicates a slide thumbnail in the film
-  // strip. Scoped to an actually-focused thumbnail (rather than "no other
-  // handler claimed it", like the Delete-key handler below) so the shortcut
-  // can't fire from an unrelated toolbar button, dialog, or menu.
+  // Command/Ctrl+C then Command/Ctrl+V on the slide rail duplicates the
+  // selected slide directly below itself. Only claims the shortcut when no
+  // slide element is selected — SlideEditor owns Cmd+C/V for object copy/paste
+  // in that case.
   const copiedSlideIdRef = useRef<string | null>(null);
   useEffect(() => {
     const handleKeyDown = (e: KeyboardEvent) => {
-      if (!deck || !id) return;
+      if (!deck || !id || !canEdit) return;
       if (!(e.metaKey || e.ctrlKey) || e.altKey) return;
       const key = e.key.toLowerCase();
       if (key !== "c" && key !== "v") return;
       if (pinMode || drawMode) return;
+
+      // A live browser text selection (e.g. the user triple-clicked rendered,
+      // non-editable slide copy) means Cmd/Ctrl+C is a normal text copy —
+      // let it through instead of hijacking it into a slide duplicate.
+      if (key === "c" && (window.getSelection()?.toString().length ?? 0) > 0) {
+        return;
+      }
+
+      // Radix Popper positions Popover/DropdownMenu/Select/Tooltip content
+      // inside the same [data-radix-popper-content-wrapper]. A tooltip opens
+      // on plain hover, so treating every such wrapper as blocking would
+      // disable this shortcut just by mousing over a toolbar button; only
+      // wrappers that aren't tooltips (marked with data-agent-native-tooltip)
+      // should count as an open menu/popover/dialog owning the keystroke.
+      const isBlockingPopperWrapper = (el: Element) =>
+        el.matches("[data-radix-popper-content-wrapper]") &&
+        !el.querySelector("[data-agent-native-tooltip]");
+      const isInsideSafeZone = (el: Element | null) => {
+        if (!el) return false;
+        if (el instanceof HTMLInputElement) return true;
+        if (el instanceof HTMLTextAreaElement) return true;
+        if (el instanceof HTMLElement) {
+          if (el.isContentEditable) return true;
+          if (el.closest("[contenteditable='true']")) return true;
+          if (el.closest("input, textarea, [role='textbox']")) return true;
+          if (el.closest("[data-pin-popover]")) return true;
+          if (el.closest("[data-add-slide-popover]")) return true;
+          if (el.closest(".agent-panel-root")) return true;
+          if (el.closest("[role='dialog'], [role='alertdialog']")) return true;
+          const popperWrapper = el.closest(
+            "[data-radix-popper-content-wrapper]",
+          );
+          if (popperWrapper && isBlockingPopperWrapper(popperWrapper))
+            return true;
+        }
+        return false;
+      };
+      if (isInsideSafeZone(e.target as Element | null)) return;
+      if (isInsideSafeZone(document.activeElement)) return;
+      if (document.querySelector("[data-pin-popover]")) return;
+      if (document.querySelector("[data-add-slide-popover]")) return;
+      // A dialog/sheet/menu/popover owning focus elsewhere in the DOM (not
+      // just under the event target) still shouldn't let this document-level
+      // shortcut duplicate the slide underneath it.
       if (
         document.querySelector(
-          "[role='dialog'], [role='menu'], [role='listbox']",
+          "[role='dialog'], [role='alertdialog'], [role='menu'], [role='listbox']",
         )
-      ) {
+      )
+        return;
+      if (
+        Array.from(
+          document.querySelectorAll("[data-radix-popper-content-wrapper]"),
+        ).some(isBlockingPopperWrapper)
+      )
+        return;
+      if (document.querySelector("[data-slide-element-selected='true']"))
         return;
-      }
-      if (!canEdit) return;
-      const focusedThumbnail = document.activeElement?.closest(
-        "[data-slide-thumbnail-id]",
-      );
-      if (!focusedThumbnail) return;
-      const focusedSlideId = focusedThumbnail.getAttribute(
-        "data-slide-thumbnail-id",
-      );
-      if (!focusedSlideId) return;
 
       if (key === "c") {
-        copiedSlideIdRef.current = focusedSlideId;
+        if (!activeSlideId) return;
+        copiedSlideIdRef.current = activeSlideId;
         return;
       }
-      const copiedSlideId = copiedSlideIdRef.current;
-      if (!copiedSlideId) return;
-      if (!deck.slides.some((s) => s.id === copiedSlideId)) return;
+
+      const copiedId = copiedSlideIdRef.current;
+      if (!copiedId || !deck.slides.some((s) => s.id === copiedId)) return;
       e.preventDefault();
-      const newSlideId = duplicateSlide(id, copiedSlideId);
-      if (newSlideId) setActiveSlideId(newSlideId);
+      const newId = duplicateSlide(id, copiedId);
+      if (newId) setActiveSlideId(newId);
     };
     document.addEventListener("keydown", handleKeyDown);
     return () => document.removeEventListener("keydown", handleKeyDown);
-  }, [deck, id, duplicateSlide, canEdit, pinMode, drawMode]);
+  }, [deck, id, canEdit, activeSlideId, duplicateSlide, pinMode, drawMode]);
 
   // Resolve the active slide from URL/deck state. Imports replace slide IDs, so
   // keep this valid after deck contents change instead of only on first load.
@@ -1083,9 +1154,30 @@ export default function DeckEditor() {
 
   const handleAddEmptySlide = () => {
     const activeIdx = deck.slides.findIndex((s) => s.id === activeSlideId);
-    setActiveSlideId(
-      addSlide(id, "blank", activeIdx >= 0 ? activeIdx : undefined),
+    // Immediate persistence: this placeholder is immediately followed by an
+    // agent request to `update-slide` it, which can reach the server before
+    // the default 500ms debounce would have flushed the `add-slide` op.
+    const newId = addSlide(
+      id,
+      "blank",
+      activeIdx >= 0 ? activeIdx : undefined,
+      {
+        persistence: "immediate",
+      },
     );
+    setActiveSlideId(newId);
+    return newId;
+  };
+
+  const handleNewSlideClick = () => {
+    const newId = handleAddEmptySlide();
+    if (newId) {
+      // The rail owns the anchor node the describe-slide popover attaches
+      // to, so it must be mounted even if it started closed on a narrow
+      // viewport where the toolbar button is still reachable.
+      setSidebarOpen(true);
+      setDescribeSlideId(newId);
+    }
   };
 
   return (
@@ -1101,7 +1193,6 @@ export default function DeckEditor() {
         canEdit={canEdit}
         canComment={canComment}
         onTitleChange={(title) => updateDeck(id, { title })}
-        slideCount={deck.slides.length}
         currentSlideIndex={currentIndex >= 0 ? currentIndex : 0}
         sidebarOpen={sidebarOpen}
         onToggleSidebar={() => setSidebarOpen(!sidebarOpen)}
@@ -1113,6 +1204,8 @@ export default function DeckEditor() {
         onShowHistory={() => setHistoryOpen((open) => !open)}
         historyButtonRef={historyButtonRef}
         currentSlide={currentSlide}
+        onAddEmptySlide={canEdit ? handleNewSlideClick : undefined}
+        addSlideGenerating={addSlideGenerating}
         onWideContextToolbarSlotChange={setWideContextToolbarSlot}
         activeUsers={slideActiveUsers.filter((u) => u.email !== session?.email)}
         agentPresent={agentPresent}
@@ -1187,13 +1280,6 @@ export default function DeckEditor() {
           }
           return exportDeckToGoogleSlides(deck.title, slides, deck.aspectRatio);
         }}
-        currentSlideId={currentSlide?.id}
-        addSlideGenerating={addSlideGenerating}
-        onAddSlideGeneratingChange={setAddSlideGenerating}
-        onAddEmptySlide={handleAddEmptySlide}
-        onDuplicateCurrentSlide={
-          currentSlide ? () => duplicateSlide(id, currentSlide.id) : undefined
-        }
         onChangeSlideTransition={
           canEdit && currentSlide
             ? (transition) => updateSlide(id, currentSlide.id, { transition })
@@ -1226,6 +1312,13 @@ export default function DeckEditor() {
                   slides={deck.slides}
                   activeSlideId={currentSlide?.id || ""}
                   deckId={id}
+                  deckTitle={deck.title}
+                  describeSlideId={describeSlideId}
+                  onCloseDescribe={() => setDescribeSlideId(null)}
+                  onAwaitAddSlidePersisted={() => flushDeckSave(id)}
+                  onRemoveFailedSlide={(slideId) => deleteSlide(id, slideId)}
+                  addSlideAgentSubmit={addSlideAgentSubmit}
+                  onAddSlideGeneratingChange={setAddSlideGenerating}
                   onSelectSlide={(slideId) => {
                     setGeneratingSlideSelected(false);
                     setActiveSlideId(slideId);
@@ -1304,19 +1397,11 @@ export default function DeckEditor() {
             contextToolbarLeading={
               canEdit ? (
                 <EditorActionCluster
-                  deckId={id}
-                  deckTitle={deck.title}
-                  currentSlideId={currentSlide.id}
-                  slideCount={deck.slides.length}
-                  currentSlideIndex={currentIndex >= 0 ? currentIndex : 0}
-                  addSlideGenerating={addSlideGenerating}
-                  onAddSlideGeneratingChange={setAddSlideGenerating}
-                  onAddEmptySlide={handleAddEmptySlide}
-                  onDuplicateCurrentSlide={() =>
-                    duplicateSlide(id, currentSlide.id)
-                  }
                   textBoxMode={textBoxMode}
                   onToggleTextBoxMode={toggleTextBoxMode}
+                  onAddEmptySlide={handleNewSlideClick}
+                  addSlideGenerating={addSlideGenerating}
+                  currentSlideId={currentSlide.id}
                   slideTransition={currentSlide.transition}
                   onChangeSlideTransition={(transition) =>
                     updateSlide(id, currentSlide.id, { transition })

package/dist/agent/index.d.ts

@@ -1,4 +1,4 @@
-export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "./production-agent.js";
+export { createProductionAgentHandler, type ActionEntry, type ScriptEntry, type ProductionAgentOptions, type AgentActionSurface, type AgentActionSurfaceDetails, type AgentLoopFinalResponseGuard, type AgentLoopFinalResponseGuardContext, type AgentLoopFinalResponseGuardResult, type AgentLoopToolCallSummary, type AgentLoopToolResultSummary, } from "./production-agent.js";
 export { type ActionTool, type ScriptTool, type AgentMessage, type AgentChatRequest, type AgentChatEvent, type AgentChatAttachment, type AgentChatReference, type MentionProvider, type MentionProviderItem, } from "./types.js";
 export { TripWire, type Processor, type ProcessorState, type ProcessorAbort, type ProcessOutputStreamArgs, type ProcessOutputStepArgs, type ProcessOutputResultArgs, } from "./processors.js";
 export { DEFAULT_MODEL } from "./default-model.js";

package/dist/agent/production-agent.d.ts

@@ -255,6 +255,29 @@ export interface ActionEntry {
 /** @deprecated Use `ActionEntry` instead */
 export type ScriptEntry = ActionEntry;
 export type AgentExecutionMode = "act" | "plan";
+export interface AgentActionSurface {
+    allowedActionNames: readonly string[];
+}
+export interface AgentActionSurfaceDetails {
+    event: any;
+    ownerEmail: string | null;
+    orgId: string | null;
+    threadId?: string;
+    mode: AgentExecutionMode;
+    internalContinuation: boolean;
+    availableActionNames: readonly string[];
+}
+/** Read a persisted allowlist while preserving legacy absence and failing
+ * closed when the field is present but malformed. */
+export declare function readPersistedAllowedActionNames(value: unknown): string[] | undefined;
+export interface PersistedActionSurface {
+    orgId: string | null;
+    allowedActionNames: string[];
+}
+/** Read a nested persisted action surface. An absent envelope is legacy;
+ * a present but invalid envelope is an explicit org-less, empty surface. */
+export declare function readPersistedActionSurface(value: unknown, propertyName: string): PersistedActionSurface | undefined;
+export declare function filterActionsByAllowedNames(actions: Record<string, ActionEntry>, allowedActionNames: readonly string[]): Record<string, ActionEntry>;
 export declare const PLAN_MODE_SYSTEM_PROMPT = "## Plan Mode Active\n\nYou are in Plan mode. This turn is for research, clarification, and a proposed approach only.\n\nHard rules:\n- Use only read-only tools. Do not edit files, write resources, run mutating bash commands, mutate SQL rows, navigate the UI, send notifications, create jobs, create tools, send messages or tasks to external agents, or change external systems.\n- If a needed detail is unclear, ask a concise clarifying question before proposing a plan.\n- When ready, present a concrete plan with the files/tools you expect to touch, the intended changes, validation steps, and notable risks.\n- Do not treat approval as implicit while Plan mode is still active. Tell the user to switch to Act mode with the mode selector or /act before implementation.";
 export declare function isPlanModeToolCallAllowed(name: string, input: unknown, entry: ActionEntry): boolean;
 export declare function createPlanModeActionRegistry(actions: Record<string, ActionEntry>): Record<string, ActionEntry>;
@@ -314,6 +337,13 @@ export interface ProductionAgentOptions {
         displayMessage?: string;
         attachments?: AgentChatAttachment[];
     }>;
+    /**
+     * Resolve the exact action registry exposed to one interactive agent-chat
+     * request. Returned names are a hard allowlist: omitted actions are absent
+     * from both the provider schemas and the searchable registry. When set, all
+     * allowed actions are loaded directly on the first model request.
+     */
+    resolveActionSurface?: (details: AgentActionSurfaceDetails) => AgentActionSurface | Promise<AgentActionSurface>;
     /** Optional per-app agent run chunk budget in milliseconds. Defaults to
      *  AGENT_RUN_SOFT_TIMEOUT_MS when set, otherwise no framework-imposed
      *  timeout. When reached, the client receives an internal auto-continuation

package/dist/agent/production-agent.js

@@ -16,7 +16,7 @@ import { completeRun as completeProgressRun, startRun as startProgressRun, updat
 import { isRuntimeVisibleScope, parseSkillFrontmatter, } from "../server/agent-chat/skill-frontmatter.js";
 import { canUseDeployCredentialFallbackForRequest, getProviderCredentialAuthFailure, readDeployCredentialEnv, } from "../server/credential-provider.js";
 import { readBody } from "../server/h3-helpers.js";
-import { getRequestRunContext, ensureRequestRunContext, getRequestContext, getRequestOrgId, getRequestUserEmail, runWithRequestContext, } from "../server/request-context.js";
+import { assertRequestActionSurfaceIsolation, getRequestRunContext, ensureRequestRunContext, getRequestContext, getRequestOrgId, getRequestUserEmail, runWithRequestContext, } from "../server/request-context.js";
 import { fireInternalDispatch } from "../server/self-dispatch.js";
 import { isReasoningEffort, normalizeReasoningEffortForRequest, stepDownReasoningEffort, } from "../shared/reasoning-effort.js";
 import { actionPreparationContinuationNote } from "./action-continuation-guidance.js";
@@ -391,6 +391,55 @@ export async function resolveOwnerEngineApiKey(input) {
 export async function getOwnerAnthropicApiKey(ownerEmail) {
     return getOwnerApiKey("anthropic", ownerEmail);
 }
+function hasOwn(value, propertyName) {
+    return (typeof value === "object" &&
+        value !== null &&
+        Object.prototype.hasOwnProperty.call(value, propertyName));
+}
+/** Read a persisted allowlist while preserving legacy absence and failing
+ * closed when the field is present but malformed. */
+export function readPersistedAllowedActionNames(value) {
+    if (!hasOwn(value, "allowedActionNames"))
+        return undefined;
+    const names = value.allowedActionNames;
+    if (!Array.isArray(names) ||
+        !names.every((name) => typeof name === "string")) {
+        return [];
+    }
+    return [...new Set(names)];
+}
+/** Read a nested persisted action surface. An absent envelope is legacy;
+ * a present but invalid envelope is an explicit org-less, empty surface. */
+export function readPersistedActionSurface(value, propertyName) {
+    if (!hasOwn(value, propertyName))
+        return undefined;
+    const surface = value[propertyName];
+    const allowedActionNames = readPersistedAllowedActionNames(surface) ?? [];
+    if (!hasOwn(surface, "orgId")) {
+        return { orgId: null, allowedActionNames: [] };
+    }
+    const orgId = surface.orgId;
+    if (orgId !== null &&
+        (typeof orgId !== "string" || orgId.trim().length === 0)) {
+        return { orgId: null, allowedActionNames: [] };
+    }
+    return { orgId, allowedActionNames };
+}
+export function filterActionsByAllowedNames(actions, allowedActionNames) {
+    const allowedNames = [...new Set(allowedActionNames)];
+    const unknownNames = allowedNames.filter((name) => !Object.prototype.hasOwnProperty.call(actions, name));
+    if (unknownNames.length > 0) {
+        throw new Error(`resolveActionSurface returned unknown action name(s): ${unknownNames.join(", ")}`);
+    }
+    const filtered = Object.fromEntries(allowedNames.map((name) => [name, actions[name]]));
+    // `attachToolSearch` closes over the registry it was originally attached to.
+    // Rebind it to this request's filtered registry so explicitly allowing
+    // `tool-search` cannot disclose actions that the resolver omitted.
+    if (filtered[TOOL_SEARCH_ACTION_NAME]) {
+        filtered[TOOL_SEARCH_ACTION_NAME] = createToolSearchEntry(() => filtered);
+    }
+    return filtered;
+}
 export const PLAN_MODE_SYSTEM_PROMPT = `## Plan Mode Active
 
 You are in Plan mode. This turn is for research, clarification, and a proposed approach only.
@@ -6031,6 +6080,9 @@ export function resolveAgentRequestReasoningEffort({ model, requestEffort, confi
     return normalizeReasoningEffortForRequest(model, isReasoningEffort(requestEffort) ? requestEffort : configuredEffort);
 }
 export function createProductionAgentHandler(options) {
+    if (options.resolveActionSurface) {
+        assertRequestActionSurfaceIsolation();
+    }
     // Undefined = let each engine pick its own defaultModel at request time.
     const configuredModel = options.model;
     // Resolve actions — prefer `actions`, fall back to deprecated `scripts`
@@ -6040,7 +6092,7 @@ export function createProductionAgentHandler(options) {
     // the settings UI) show up to the LLM without a process restart. MCP tools
     // are also scope-filtered per request — a user-scope server added by Alice
     // must not appear in Bob's tool list in a shared-process deployment.
-    const getEngineTools = (actions = resolvedActions) => {
+    const getRequestActions = (actions = resolvedActions) => {
         const filtered = {};
         for (const [name, entry] of Object.entries(actions)) {
             if (name.startsWith("mcp__") && !isMcpToolAllowedForRequest(name)) {
@@ -6048,8 +6100,9 @@ export function createProductionAgentHandler(options) {
             }
             filtered[name] = entry;
         }
-        return actionsToEngineTools(filtered);
+        return filtered;
     };
+    const getEngineTools = (actions) => actionsToEngineTools(getRequestActions(actions));
     return defineEventHandler(async (event) => {
         // Diagnostic-only setup-timing instrumentation. Captures wall-clock offsets
         // from handler entry through the work done BEFORE startRun so a slow pre-run
@@ -6089,12 +6142,20 @@ export function createProductionAgentHandler(options) {
         // (the route HMAC-verifies the dispatch before invoking us). When set, we
         // run the loop inline with the background soft-timeout, reusing the
         // pre-claimed runId/turnId — we must NOT re-claim the slot or re-dispatch.
-        const backgroundRunMarker = body[AGENT_CHAT_BACKGROUND_RUN_FIELD] &&
+        const backgroundRunMarker = preInjectedBody &&
+            body[AGENT_CHAT_BACKGROUND_RUN_FIELD] &&
             typeof body[AGENT_CHAT_BACKGROUND_RUN_FIELD] === "object" &&
             typeof body[AGENT_CHAT_BACKGROUND_RUN_FIELD].runId === "string"
             ? body[AGENT_CHAT_BACKGROUND_RUN_FIELD]
             : null;
         const isBackgroundWorker = backgroundRunMarker !== null;
+        // Both fields are internal durable-dispatch artifacts, never client input.
+        // A body marker alone is not proof of worker identity: only the verified
+        // `_process-run` route can install `preInjectedBody` on the event context.
+        if (!isBackgroundWorker) {
+            delete body[AGENT_CHAT_BACKGROUND_RUN_FIELD];
+            delete body.__resolvedActionSurface;
+        }
         // DIAGNOSTIC-ONLY: progressive per-stage hang localizer for the bg worker.
         // The worker's runId is available EARLY on the marker (the general `runId`
         // var resolves much later), so capture it now and emit the LAST setup stage
@@ -6197,6 +6258,35 @@ export function createProductionAgentHandler(options) {
                 requestAttachments = preparedRequest.attachments;
             }
         }
+        const availableRequestActions = getRequestActions();
+        let surfacedRequestActions = availableRequestActions;
+        if (options.resolveActionSurface) {
+            const persistedSurface = isBackgroundWorker
+                ? readPersistedActionSurface(body, "__resolvedActionSurface")
+                : undefined;
+            const surface = persistedSurface !== undefined
+                ? persistedSurface
+                : await options.resolveActionSurface({
+                    event,
+                    ownerEmail,
+                    orgId: getRequestOrgId() ?? null,
+                    threadId,
+                    mode: requestMode,
+                    internalContinuation: Boolean(internalContinuation),
+                    availableActionNames: Object.keys(availableRequestActions),
+                });
+            surfacedRequestActions = filterActionsByAllowedNames(availableRequestActions, surface.allowedActionNames);
+            const allowedNames = Object.keys(surfacedRequestActions);
+            const runCtx = ensureRequestRunContext();
+            if (runCtx)
+                runCtx.allowedActionNames = allowedNames;
+            if (!isBackgroundWorker) {
+                body.__resolvedActionSurface = {
+                    orgId: getRequestOrgId() ?? null,
+                    allowedActionNames: allowedNames,
+                };
+            }
+        }
         // DIAGNOSTIC-ONLY: owner/request context prep (resolveAgentOwnerEmail +
         // prepareRequest) finished. A worker stuck before this points at the
         // owner/request-context awaits.
@@ -6428,7 +6518,7 @@ export function createProductionAgentHandler(options) {
         const screenContextThunk = () => (async () => {
             const screenStart = Date.now();
             try {
-                const viewScreenAction = resolvedActions["view-screen"];
+                const viewScreenAction = surfacedRequestActions["view-screen"];
                 if (viewScreenAction) {
                     const result = await viewScreenAction.run({}, {
                         userEmail: getRequestUserEmail(),
@@ -6667,10 +6757,12 @@ export function createProductionAgentHandler(options) {
         }
         const screenContext = timeBlock + screenBlock + urlBlock + selectionBlock;
         const requestActions = requestMode === "plan"
-            ? createPlanModeActionRegistry(resolvedActions)
-            : resolvedActions;
+            ? createPlanModeActionRegistry(surfacedRequestActions)
+            : surfacedRequestActions;
         const availableRequestTools = getEngineTools(requestActions);
-        const initialRequestTools = filterInitialEngineTools(availableRequestTools, options.initialToolNames);
+        const initialRequestTools = options.resolveActionSurface
+            ? availableRequestTools
+            : filterInitialEngineTools(availableRequestTools, options.initialToolNames);
         const requestTools = requestMode === "plan"
             ? preloadPlanModeEngineTools({
                 request: requestMessage,

package/dist/agent/types.d.ts

@@ -186,6 +186,15 @@ export interface AgentChatRequest {
          */
         payloadRef?: boolean;
     };
+    /**
+     * Server-resolved action authorization carried across authenticated durable
+     * background dispatches. Normal client requests must not trust this field;
+     * the foreground handler deletes and replaces it before persistence.
+     */
+    __resolvedActionSurface?: {
+        orgId: string | null;
+        allowedActionNames: string[];
+    };
     /**
      * Stable identity for the logical assistant turn this request belongs to.
      * The client sends the SAME turnId for the initial POST and every