docs(showcase): gen-ui-interrupt + interrupt-headless cross-framework parity

Closes the interrupt architectural-divergence gap for ms-agent-python
and ms-agent-dotnet. Pairs with PDX-68 — same gating mechanism as the
a2ui parity commit.

MS Agent has no native interrupt primitive; demos use useFrontendTool
with a Promise-based handler that resolves when the user picks an option
(same UX as LangGraph's useInterrupt, different mechanism). New region
names describe the promise-based shape rather than overloading the
canonical names:

  ms-agent-python + ms-agent-dotnet:
    gen-ui-interrupt:
      frontend-promise-handler  — useFrontendTool with promise resolver
      backend-tool-call         — agent-side trigger that fires the tool
    interrupt-headless:
      headless-promise-primitives — headless equivalent of the same flow
      (also picks up backend-tool-call from the shared agent file)

MDX restructure (3 docs pages):
- /human-in-the-loop/useInterrupt.mdx
- /human-in-the-loop/headless.mdx
- /programmatic-control.mdx

Each now has parallel <WhenFrameworkHas interrupt_pattern=...> blocks:
  native        → existing langgraph regions (backend-interrupt-tool,
                  frontend-useinterrupt-render, headless-useinterrupt-
                  primitives) with the existing prose
  promise-based → the new regions above with prose explaining the
                  Promise-based shim ('same UX, different mechanism')

Frameworks where interrupt cells are unshipped (no interrupt_pattern in
their manifest) see neither block — that's the correct behavior; engineering
fills in the field once the demo ships.

Author: samjulien

showcase/integrations/ms-agent-dotnet/agent/InterruptAgent.cs

@@ -65,6 +65,7 @@ public InterruptAgentFactory(IConfiguration configuration, ILoggerFactory logger
             });
     }
 
+    // @region[backend-tool-call]
     public AIAgent CreateInterruptAgent()
     {
         var chatClient = _openAiClient.GetChatClient("gpt-4o-mini").AsIChatClient();
@@ -75,8 +76,9 @@ public AIAgent CreateInterruptAgent()
         // and returns a generic "unscheduled" message. When the frontend
         // has the tool registered (the intended demo path), AG-UI forwards
         // the frontend tool definition and the client handles the call —
-        // this backend tool acts only as a schema hint for the model when
-        // the frontend tool isn't yet available.
+        // the frontend handler returns a Promise that only resolves once
+        // the user picks a slot, which is the MS Agent shim for the
+        // LangGraph `interrupt()` pause/resume primitive.
         //
         // The parameters intentionally mirror the LangGraph reference's
         // `schedule_meeting(topic, attendee)` signature so the model's
@@ -97,6 +99,7 @@ describing the purpose and `attendee` describing who the meeting is with. After
 
         return new SharedStateAgent(chatClientAgent, _jsonSerializerOptions, _loggerFactory.CreateLogger<SharedStateAgent>());
     }
+    // @endregion[backend-tool-call]
 
     // =================
     // Tools

showcase/integrations/ms-agent-dotnet/src/app/demos/gen-ui-interrupt/page.tsx

@@ -81,7 +81,7 @@ function Chat() {
     [],
   );
 
-  // @region[frontend-tool-schedule-meeting]
+  // @region[frontend-promise-handler]
   useFrontendTool({
     name: "schedule_meeting",
     description:
@@ -150,7 +150,7 @@ function Chat() {
       );
     },
   });
-  // @endregion[frontend-tool-schedule-meeting]
+  // @endregion[frontend-promise-handler]
 
   return (
     <CopilotChat agentId="gen-ui-interrupt" className="h-full rounded-2xl" />

showcase/integrations/ms-agent-dotnet/src/app/demos/interrupt-headless/page.tsx

@@ -100,7 +100,7 @@ function Layout() {
     available: "always",
   });
 
-  // @region[headless-frontend-tool-schedule-meeting]
+  // @region[headless-promise-primitives]
   useFrontendTool({
     name: "schedule_meeting",
     description:
@@ -140,7 +140,7 @@ function Layout() {
     // reads the `pending` state set inside the handler.
     render: () => null,
   });
-  // @endregion[headless-frontend-tool-schedule-meeting]
+  // @endregion[headless-promise-primitives]
 
   return (
     <div className="grid h-screen grid-cols-[1fr_420px] bg-[#FAFAFC]">

showcase/integrations/ms-agent-python/src/agents/interrupt_agent.py

@@ -24,6 +24,7 @@
 from agent_framework_ag_ui import AgentFrameworkAgent
 
 
+# @region[backend-tool-call]
 SYSTEM_PROMPT = dedent(
     """
     You are a scheduling assistant. Whenever the user asks you to book a call
@@ -52,6 +53,10 @@ def create_interrupt_agent(chat_client: BaseChatClient) -> AgentFrameworkAgent:
         instructions=SYSTEM_PROMPT,
         # No backend tools. `schedule_meeting` is registered on the frontend
         # via `useFrontendTool` and dispatched through the CopilotKit runtime.
+        # When the agent calls `schedule_meeting`, the request is routed to
+        # the frontend handler, which returns a Promise that only resolves
+        # once the user picks a slot — equivalent to `interrupt()` in the
+        # LangGraph reference.
         tools=[],
     )
 
@@ -64,3 +69,4 @@ def create_interrupt_agent(chat_client: BaseChatClient) -> AgentFrameworkAgent:
         ),
         require_confirmation=False,
     )
+# @endregion[backend-tool-call]

showcase/integrations/ms-agent-python/src/app/demos/gen-ui-interrupt/page.tsx

@@ -65,7 +65,7 @@ function Chat() {
     available: "always",
   });
 
-  // @region[ms-agent-frontend-tool-interrupt]
+  // @region[frontend-promise-handler]
   useFrontendTool({
     name: "schedule_meeting",
     description:
@@ -114,7 +114,7 @@ function Chat() {
       );
     },
   });
-  // @endregion[ms-agent-frontend-tool-interrupt]
+  // @endregion[frontend-promise-handler]
 
   return (
     <CopilotChat agentId="gen-ui-interrupt" className="h-full rounded-2xl" />

showcase/integrations/ms-agent-python/src/app/demos/interrupt-headless/page.tsx

@@ -74,7 +74,7 @@ function Layout() {
     available: "always",
   });
 
-  // @region[ms-agent-frontend-tool-headless]
+  // @region[headless-promise-primitives]
   useFrontendTool({
     name: "schedule_meeting",
     description:
@@ -117,7 +117,7 @@ function Layout() {
     // Render nothing inside the chat — the UI lives in the app surface.
     render: () => null,
   });
-  // @endregion[ms-agent-frontend-tool-headless]
+  // @endregion[headless-promise-primitives]
 
   const resolve = (result: PickerResult) => {
     const fn = resolverRef.current;

showcase/shell-docs/src/content/docs/human-in-the-loop/headless.mdx

@@ -37,6 +37,8 @@ mounting a chat at all.
 If you just want "a picker in chat", just use
 [`useInterrupt`](./useInterrupt).
 
+<WhenFrameworkHas flag="interrupt_pattern" equals="native">
+
 ## The primitives
 
 Under the hood, `useInterrupt` composes two public APIs:
@@ -66,6 +68,38 @@ A few things this hook is careful about:
 - `onRunFailed` drops the staged event so a transport hiccup doesn't
   leave the UI stuck showing a picker for a run that never paused.
 
+</WhenFrameworkHas>
+
+<WhenFrameworkHas flag="interrupt_pattern" equals="promise-based">
+
+## The primitives (Promise-based shim)
+
+On Microsoft Agent Framework there's no native interrupt primitive —
+the runtime can't pause a run and surface a custom event for the
+client to subscribe to. Instead, the headless variant uses
+`useFrontendTool` with an async handler that returns a Promise: the
+handler exposes its pending payload via React state (so a separate
+"app surface" can render the picker outside the chat) and resolves
+the Promise once the user interacts. Same UX, different mechanism.
+
+The render callback intentionally returns `null` — the picker UI lives
+in the app surface, not in the chat transcript. The handler's pending
+state drives whether the picker is shown:
+
+<Snippet region="headless-promise-primitives" title="frontend/src/app/page.tsx — useFrontendTool (headless Promise-based)" />
+
+A few things this pattern is careful about:
+
+- The handler stages its `resolve` callback in a ref keyed by tool-call
+  id, so concurrent tool calls don't trample each other's resolvers.
+- `setPending` is called from inside the handler so the app surface
+  re-renders the picker as soon as the agent calls the tool, and again
+  with `null` after the user interacts so the picker disappears.
+- `render: () => null` keeps the chat transcript clean — the headless
+  variant deliberately bypasses inline rendering.
+
+</WhenFrameworkHas>
+
 ## Driving it from plain UI
 
 Once `useHeadlessInterrupt` returns `{ pending, resolve }`, the rest is

showcase/shell-docs/src/content/docs/human-in-the-loop/useInterrupt.mdx

@@ -34,6 +34,8 @@ not an LLM-initiated tool call. Typical cases:
 For LLM-initiated pauses where the model decides on the fly to ask
 the user, prefer [`useHumanInTheLoop`](../human-in-the-loop).
 
+<WhenFrameworkHas flag="interrupt_pattern" equals="native">
+
 ## The backend: `interrupt()` inside a tool
 
 The example agent exposes a `schedule_meeting` tool. When the model
@@ -64,6 +66,41 @@ and `resolve(...)` is how you resume the run:
 Whatever you pass to `resolve` is round-tripped back to the agent as
 the return value of the matching `interrupt(...)` call.
 
+</WhenFrameworkHas>
+
+<WhenFrameworkHas flag="interrupt_pattern" equals="promise-based">
+
+## The Promise-based shim
+
+On Microsoft Agent Framework there's no native interrupt primitive —
+the runtime can't pause a run mid-tool and hand control to the client
+the way LangGraph's `interrupt()` does. Instead, the demo uses
+`useFrontendTool` with an async handler that returns a Promise. The
+agent calls `schedule_meeting` like any other tool, the client-side
+handler renders the picker, and the Promise only resolves once the
+user picks a slot or cancels. Same UX, different mechanism.
+
+### The frontend: `useFrontendTool` with a Promise-resolving handler
+
+The handler stores its `resolve` callback in a ref, returns a Promise
+that the user's pick eventually resolves, and renders the picker
+inline in the chat. This is the MS Agent equivalent of
+`useInterrupt`'s `event` / `resolve` pair:
+
+<Snippet region="frontend-promise-handler" title="frontend/src/app/page.tsx — useFrontendTool (Promise-based)" />
+
+### The backend: agent instructed to call the frontend tool
+
+The agent has no local `schedule_meeting` implementation — the tool is
+registered entirely on the frontend. The backend's only job is to
+instruct the model to call `schedule_meeting` whenever the user wants
+to book a meeting. AG-UI routes the tool call to the client, where
+the Promise-returning handler takes over:
+
+<Snippet region="backend-tool-call" title="backend — agent instructed to call schedule_meeting" />
+
+</WhenFrameworkHas>
+
 ### Key props
 
 - **`agentId`** — must match a runtime-registered agent. If omitted, the

showcase/shell-docs/src/content/docs/programmatic-control.mdx

@@ -58,6 +58,8 @@ object accepts every AG-UI lifecycle callback: `onCustomEvent`,
 deltas. Use it to drive custom progress UI, forward events to
 analytics, or catch LangGraph `interrupt(...)` events and resume with a payload (the pattern below).
 
+<WhenFrameworkHas flag="interrupt_pattern" equals="native">
+
 ## Resolving a LangGraph interrupt from a button
 
 The `interrupt-headless` cell demonstrates the full pattern without
@@ -74,6 +76,29 @@ The resulting `{ pending, resolve }` tuple is pure data; any UI can
 drive it. The cell itself renders a simple button grid, but the same
 hook would power a modal, a toast, a sidebar form, or a voice UI.
 
+</WhenFrameworkHas>
+
+<WhenFrameworkHas flag="interrupt_pattern" equals="promise-based">
+
+## Resolving an MS Agent tool call from a button
+
+On Microsoft Agent Framework there's no native interrupt primitive —
+the demo uses `useFrontendTool` with a Promise-based handler instead.
+The handler stages its `resolve` callback and pending payload via
+React state, the app surface renders the picker outside the chat, and
+the user's pick resolves the Promise that the agent's tool call is
+awaiting. Same UX, different mechanism — the agent never knows it's
+talking to a button grid instead of a chat picker:
+
+<Snippet region="headless-promise-primitives" cell="interrupt-headless" title="frontend/src/app/page.tsx — useFrontendTool + Promise resolver" />
+
+The resulting `{ pending, resolveActive }` pair is pure data; any UI
+can drive it. The cell itself renders a simple button grid, but the
+same pattern would power a modal, a toast, a sidebar form, or a voice
+UI.
+
+</WhenFrameworkHas>
+
 ## See also
 
 - [Headless UI](./headless) — the full `useRenderedMessages` composition