@robota-sdk/agent-ui-web 3.0.0-beta.94 → 3.0.0-beta.96

package/src/components/PermissionPrompt.tsx

@@ -1,6 +1,6 @@
 'use client';
 
-import { MessageCircleQuestion, ShieldAlert } from 'lucide-react';
+import { MessageCircleQuestion, ShieldAlert, Square, SquareCheck } from 'lucide-react';
 import React, {
   forwardRef,
   useEffect,
@@ -32,6 +32,12 @@ import type { TDriverId } from '@robota-sdk/agent-interface-session';
  * lives only in `FreeTextField`, keyed by `prompt.id`: a cancelled or answered prompt's text can
  * never reach the next prompt's render, masked or not, because the field is a fresh component
  * instance rather than a value carried over in this component's own state (#3280 §3 follow-up).
+ *
+ * An ask whose `maxSelect` is above 1 is a multi-select: each option is a toggle (a click or 1–9 ticks
+ * it, nothing answers yet), and Submit — or Enter at the prompt, once the selection is allowed —
+ * answers with the ticked values in option order. Unlike the free-text field, the ticks live in this
+ * component, because the dock's keys act on them; they are tagged with `prompt.id`, so a prompt never
+ * reads the ticks of another.
  */
 interface IPermissionPromptProps {
   prompts: readonly TPendingPrompt[];
@@ -77,6 +83,42 @@ function isDestructiveAskOption(requestId: string | undefined, value: string): b
   return requestId === 'provider-profile-action' && value === 'delete';
 }
 
+type TAskRequest = Extract<TPendingPrompt, { kind: 'ask' }>['request'];
+type TAskOption = NonNullable<TAskRequest['options']>[number];
+
+/** What a multi-select ask (`maxSelect` above 1) lets the person tick; see `readMultiSelect`. */
+interface IMultiSelect {
+  min: number;
+  max: number;
+  /** The options that can be ticked, in the order the answer lists them. */
+  options: readonly TAskOption[];
+  /** The ticks a prompt starts with. */
+  defaults: ReadonlySet<string>;
+}
+
+/**
+ * The multi-select shape of an ask, or undefined for every other ask (which answers on click). The
+ * rules mirror the terminal checklist (`MultiSelectList` in agent-ui-terminal): `minSelect` (default 1)
+ * gates the submit, and `maxSelect` caps the ticks — a toggle beyond the cap is ignored, never swapped
+ * for the oldest tick. `default.values` pre-select; a default that names no option is dropped, and
+ * more defaults than the cap keep the first ones in option order, so the answer never breaks the cap.
+ */
+function readMultiSelect(request: TAskRequest): IMultiSelect | undefined {
+  const max = request.maxSelect ?? 1;
+  if (max <= 1) return undefined;
+  const options = (request.options ?? []).filter(
+    (opt) => !isDestructiveAskOption(request.id, opt.value),
+  );
+  const wanted = new Set(request.default?.values ?? []);
+  const defaults = options.filter((opt) => wanted.has(opt.value)).slice(0, max);
+  return {
+    min: request.minSelect ?? 1,
+    max,
+    options,
+    defaults: new Set(defaults.map((opt) => opt.value)),
+  };
+}
+
 export function PermissionPrompt({
   prompts,
   onAnswerPermission,
@@ -106,6 +148,11 @@ export function PermissionPrompt({
   // Set at the moment of an answer if focus was inside the prompt then; consumed once the prompt list
   // empties (see below) or cleared once a next prompt shows it was not needed after all.
   const pendingFocusReturnRef = useRef(false);
+  // A multi-select ask's ticks, tagged with the prompt they belong to: another prompt (a different
+  // `prompt.id`) reads its own defaults instead, so there is no stale selection to reset.
+  const [selection, setSelection] = useState<
+    { promptId: string; values: ReadonlySet<string> } | undefined
+  >(undefined);
   useEffect(() => {
     if (promptId === undefined || armDelayMs <= 0) return undefined;
     const timer = setTimeout(() => setArmedId(promptId), armDelayMs);
@@ -200,6 +247,23 @@ export function PermissionPrompt({
     fieldHandleRef.current?.clear();
     onAnswerAsk(id, response);
   };
+  const multi = prompt.kind === 'ask' ? readMultiSelect(prompt.request) : undefined;
+  const ticks = selection?.promptId === prompt.id ? selection.values : multi?.defaults;
+  const selectedValues =
+    multi && ticks ? multi.options.map((opt) => opt.value).filter((value) => ticks.has(value)) : [];
+  const canSubmit = multi !== undefined && selectedValues.length >= multi.min;
+  const toggleOption = (value: string): void => {
+    if (!multi) return;
+    setSelection((current) => {
+      const next = new Set(current?.promptId === prompt.id ? current.values : multi.defaults);
+      if (next.has(value)) next.delete(value);
+      else if (next.size < multi.max) next.add(value);
+      return { promptId: prompt.id, values: next };
+    });
+  };
+  const submitSelection = (): void => {
+    if (canSubmit) answerAsk(prompt.id, { type: 'answer', values: selectedValues });
+  };
   /** A click anywhere in the prompt that isn't on a button or the field itself focuses the field. */
   const onContainerClick = (event: React.MouseEvent<HTMLDivElement>): void => {
     if (!hasFreeText) return;
@@ -222,6 +286,15 @@ export function PermissionPrompt({
     }
     // A key that reaches a prompt still arming (it kept focus from the one before) is dropped.
     if (!armed) return;
+    if (multi && event.key === 'Enter') {
+      // Only from the prompt itself: on a focused button (a toggle, Submit, Cancel) Enter is that
+      // button's own click, and its keydown reaches this handler as well.
+      if (event.target === event.currentTarget) {
+        event.preventDefault();
+        submitSelection();
+      }
+      return;
+    }
     const index = Number(event.key) - 1;
     if (!Number.isInteger(index) || index < 0) return;
     if (prompt.kind === 'permission') {
@@ -235,7 +308,10 @@ export function PermissionPrompt({
       (opt) => !isDestructiveAskOption(prompt.request.id, opt.value),
     );
     const option = digitOptions[index];
-    if (option) answerAsk(prompt.id, { type: 'answer', values: [option.value] });
+    if (!option) return;
+    // A multi-select's digit ticks the option; it answers only when the ask has a single answer.
+    if (multi) toggleOption(option.value);
+    else answerAsk(prompt.id, { type: 'answer', values: [option.value] });
   };
   // #3288: an Edit/Write request carries the same server-built diff `tool_end` would show.
   const hasDiff = prompt.kind === 'permission' && (prompt.diffLines?.length ?? 0) > 0;
@@ -258,9 +334,11 @@ export function PermissionPrompt({
   const askArmedHint =
     hasFreeText && fieldFocused
       ? 'Enter to submit · Esc to cancel'
-      : askOptions.length > 0
-        ? '1–9 choose · Esc cancel'
-        : 'Esc cancels';
+      : multi && askOptions.length > 0
+        ? '1–9 toggle · Enter submit · Esc cancel'
+        : askOptions.length > 0
+          ? '1–9 choose · Esc cancel'
+          : 'Esc cancels';
   return (
     <div
       className={
@@ -397,11 +475,24 @@ export function PermissionPrompt({
                       <button
                         type="button"
                         aria-keyshortcuts={dock && index < 9 ? String(index + 1) : undefined}
-                        className={index === 0 ? PRIMARY_BUTTON : SECONDARY_BUTTON}
+                        aria-pressed={multi ? selectedValues.includes(opt.value) : undefined}
+                        className={
+                          (multi ? selectedValues.includes(opt.value) : index === 0)
+                            ? PRIMARY_BUTTON
+                            : SECONDARY_BUTTON
+                        }
                         onClick={onButton(() =>
-                          answerAsk(prompt.id, { type: 'answer', values: [opt.value] }),
+                          multi
+                            ? toggleOption(opt.value)
+                            : answerAsk(prompt.id, { type: 'answer', values: [opt.value] }),
                         )}
                       >
+                        {multi &&
+                          (selectedValues.includes(opt.value) ? (
+                            <SquareCheck size={15} strokeWidth={2} />
+                          ) : (
+                            <Square size={15} strokeWidth={2} />
+                          ))}
                         <span>{opt.label}</span>
                         {dock && index < 9 && <Kbd>{index + 1}</Kbd>}
                       </button>
@@ -454,6 +545,16 @@ export function PermissionPrompt({
                 </div>
               )}
               <div className="flex flex-wrap items-center gap-2">
+                {multi && (
+                  <button
+                    type="button"
+                    className={`${PRIMARY_BUTTON} disabled:opacity-60`}
+                    disabled={!canSubmit}
+                    onClick={onButton(submitSelection)}
+                  >
+                    {canSubmit ? 'Submit' : `Submit (min ${multi.min})`}
+                  </button>
+                )}
                 <button
                   type="button"
                   className={GHOST_BUTTON}

package/src/components/SessionSurface.tsx

@@ -1,5 +1,7 @@
-import { useEffect, useRef, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 
+import { AppViewHostContext } from '../app-view/host-context.js';
+import { useProductIdentity } from '../product-identity.js';
 import { AgentActivityPanel } from './AgentActivityPanel.js';
 import { AgentSwitcherSheet } from './AgentSwitcherSheet.js';
 import { ProductMark, ProductWordmark } from './Brand.js';
@@ -32,6 +34,8 @@ import type { IWsSessionState } from '../hooks/useSessionClient.js';
 /** The column every part of the conversation shares, so messages, prompt and composer line up. */
 const COLUMN = 'mx-auto w-full max-w-[760px] px-6';
 
+const APP_VIEW_HOST_VERSION = '1.0.0';
+
 /**
  * Designed empty state shown before the first turn. Renders in the same slot as `ConversationView`
  * (never together), so it carries the same `main` landmark and label (#3289 §3 review) — nothing
@@ -46,8 +50,8 @@ function EmptyState(): React.ReactElement {
           What are we working on?
         </h2>
         <p className="text-[15px] leading-relaxed text-muted-foreground">
-          Session connected. Send a message to start — the agent works in the host runtime and
-          asks you here before anything that needs your permission.
+          Session connected. Send a message to start — the agent works in the host runtime and asks
+          you here before anything that needs your permission.
         </p>
       </div>
     </main>
@@ -107,6 +111,7 @@ export function SessionSurface({
   pickFiles,
   getPathForFile,
   onOpenMemoryInEditor,
+  appViewSandboxUrl,
 }: {
   state: IWsSessionState;
   surface?: string;
@@ -127,8 +132,21 @@ export function SessionSurface({
    * itself is hidden (only shown "if the host supports it").
    */
   onOpenMemoryInEditor?: (path: string) => void;
+
+  appViewSandboxUrl?: string;
 }): React.ReactElement {
   const [view, setView] = useState<TSessionView>('chat');
+  const { identity } = useProductIdentity();
+  const appViewHost = useMemo(
+    () => ({
+      ...(appViewSandboxUrl !== undefined ? { sandboxUrl: appViewSandboxUrl } : {}),
+      readAppView: state.readAppView,
+      callAppTool: state.callAppTool,
+      hostInfo: { name: identity.displayName, version: APP_VIEW_HOST_VERSION },
+      platform: surface === 'app' ? ('desktop' as const) : ('web' as const),
+    }),
+    [appViewSandboxUrl, state.readAppView, state.callAppTool, identity.displayName, surface],
+  );
   const composerRef = useRef<IComposerHandle>(null);
   const tasks = state.executionWorkspace?.entries ?? [];
   // The main thread alone is this conversation; the rail earns its width only for work beside it.
@@ -307,13 +325,15 @@ export function SessionSurface({
                 ) : isEmpty ? (
                   <EmptyState />
                 ) : (
-                  <ConversationView
-                    messages={state.messages}
-                    activeTools={state.activeTools}
-                    streamingText={state.streamingText}
-                    isThinking={state.isThinking}
-                    ownDriverId={state.ownDriverId}
-                  />
+                  <AppViewHostContext.Provider value={appViewHost}>
+                    <ConversationView
+                      messages={state.messages}
+                      activeTools={state.activeTools}
+                      streamingText={state.streamingText}
+                      isThinking={state.isThinking}
+                      ownDriverId={state.ownDriverId}
+                    />
+                  </AppViewHostContext.Provider>
                 )}
               </div>
               <div
@@ -375,7 +395,10 @@ export function SessionSurface({
             </div>
 
             {hasWorkInProgress && (
-              <aside aria-label="Agents" className="flex w-72 flex-shrink-0 overflow-hidden bg-sidebar">
+              <aside
+                aria-label="Agents"
+                className="flex w-72 flex-shrink-0 overflow-hidden bg-sidebar"
+              >
                 <AgentActivityPanel
                   tasks={tasks}
                   className="flex-1"
@@ -410,7 +433,11 @@ export function SessionSurface({
       <SessionNotices state={state} />
       <SettingsScreen state={state} />
       <AgentSwitcherSheet state={state} />
-      <HelpSheet open={state.helpOpen} onClose={() => state.closeHelp()} catalog={state.commandCatalog} />
+      <HelpSheet
+        open={state.helpOpen}
+        onClose={() => state.closeHelp()}
+        catalog={state.commandCatalog}
+      />
     </div>
   );
 }

package/src/hooks/server-message-handling.ts

@@ -62,6 +62,9 @@ export const SERVER_MESSAGE_HANDLING = {
   project_status: 'reducer-state',
   project_diff: 'reducer-state',
   project_memory: 'reducer-state',
+
+  app_view: 'reducer-state',
+  app_tool_result: 'reducer-state',
   background_task_event: 'intentionally-not-rendered',
   background_job_group_event: 'intentionally-not-rendered',
   plan_event: 'intentionally-not-rendered',

package/src/hooks/session-client-types.ts

@@ -1,8 +1,10 @@
+import type { TAppToolArguments, TAppToolOutcome, TAppView } from '../app-view/types.js';
 import type { TConnectionStatus, TClientMessage } from '../client/ws-session-client.js';
 import type { TPendingPrompt } from './prompt-state.js';
 import type { TActionResponse } from '@robota-sdk/agent-interface-transport';
 import type {
   IDiffLine,
+  IToolAppViewRef,
   IToolState,
   ISettingsSnapshot,
   TDriverId,
@@ -16,6 +18,8 @@ import type {
 } from '@robota-sdk/agent-interface-execution';
 import type { IWireAgentDefinitionSummary, TServerMessage } from '@robota-sdk/agent-transport';
 
+export type { TAppToolArguments, TAppToolOutcome, TAppView } from '../app-view/types.js';
+
 export type TPersonalUsageReport = Extract<
   TServerMessage,
   { type: 'personal_usage_report' }
@@ -125,6 +129,8 @@ export interface IActiveTool {
   commandName?: string;
   /** #3288: true for an internal signal tool (e.g. goal-status) — never rendered as a call. */
   internal?: boolean;
+
+  appView?: IToolAppViewRef;
 }
 
 /**
@@ -326,4 +332,12 @@ export interface IWsSessionState<TStatus extends string = TConnectionStatus> {
    * session notice) — no separate error state here.
    */
   deleteSchedule: (taskId: string) => void;
+
+  readAppView: (viewKey: string, signal?: AbortSignal) => Promise<TAppView>;
+  callAppTool: (
+    viewKey: string,
+    name: string,
+    args: TAppToolArguments,
+    signal?: AbortSignal,
+  ) => Promise<TAppToolOutcome>;
 }

package/src/hooks/use-app-view-requests.ts

@@ -0,0 +1,178 @@
+import { useCallback, useRef, useState } from 'react';
+
+import type { TClientMessage } from '../client/ws-session-client.js';
+import type { TAppToolArguments, TAppToolOutcome, TAppView } from '../app-view/types.js';
+import type { IActiveTool } from './session-client-types.js';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+type TPendingRequest = {
+  reject: (error: Error) => void;
+  dispose: () => void;
+} & (
+  | { answer: 'app_view'; resolve: (value: TAppView) => void }
+  | { answer: 'app_tool_result'; resolve: (value: TAppToolOutcome) => void }
+);
+
+let requestCounter = 0;
+function nextRequestId(prefix: string): string {
+  requestCounter += 1;
+  return `${prefix}_${requestCounter}_${Date.now()}`;
+}
+
+const CONNECTION_CLOSED = 'The connection to the session closed.';
+
+/**
+ * The key a finished call's app view is read and called by, taken from the tool row's `appView`
+ * reference; `undefined` when the row gives none. Everything outside this module treats it as an
+ * opaque string — it is read here and put on the two wire messages below, nowhere else.
+ */
+export function appViewKey(tool: IActiveTool): string | undefined {
+  return tool.appView?.viewId;
+}
+
+function readAppViewMessage(requestId: string, viewKey: string): TClientMessage {
+  return { type: 'read-app-view', requestId, viewId: viewKey };
+}
+
+function callAppToolMessage(
+  requestId: string,
+  viewKey: string,
+  name: string,
+  args: TAppToolArguments,
+): TClientMessage {
+  return { type: 'call-app-tool', requestId, viewId: viewKey, name, arguments: args };
+}
+
+/**
+ * The app-view host's two requests to the session, each a promise settled by the reply that echoes
+ * its `requestId` (`app_view` / `app_tool_result`, or a `protocol_error` naming it). Unlike the
+ * panels' latest-wins state, several can be outstanding at once (one per frame on screen), so each
+ * keeps its own entry. A reply that lost its connection never arrives: the owner of the connection
+ * rejects every outstanding request when it drops, is replaced or goes away (`rejectPendingAppRequests`).
+ */
+export function useAppViewRequests(
+  send: (msg: TClientMessage) => void,
+  isConnected: () => boolean,
+): {
+  readAppView: (viewKey: string, signal?: AbortSignal) => Promise<TAppView>;
+  callAppTool: (
+    viewKey: string,
+    name: string,
+    args: TAppToolArguments,
+    signal?: AbortSignal,
+  ) => Promise<TAppToolOutcome>;
+  handleAppViewMessage: (msg: TServerMessage) => boolean;
+  rejectPendingAppRequests: (reason?: string) => void;
+} {
+  const pendingRef = useRef(new Map<string, TPendingRequest>());
+  const [requestOwner] = useState(() => nextRequestId('app_request'));
+
+  const rejectPendingAppRequests = useCallback((reason: string = CONNECTION_CLOSED): void => {
+    const pending = [...pendingRef.current.values()];
+    pendingRef.current.clear();
+    for (const request of pending) {
+      request.dispose();
+      request.reject(new Error(reason));
+    }
+  }, []);
+
+  const request = useCallback(
+    <T extends TAppView | TAppToolOutcome>(
+      prefix: string,
+      message: (requestId: string) => TClientMessage,
+      pending: (
+        resolve: (value: T) => void,
+        reject: (error: Error) => void,
+        dispose: () => void,
+      ) => TPendingRequest,
+      signal?: AbortSignal,
+    ): Promise<T> =>
+      new Promise<T>((resolve, reject) => {
+        if (!isConnected() || signal?.aborted) {
+          reject(new Error(signal?.aborted ? 'The app view closed.' : CONNECTION_CLOSED));
+          return;
+        }
+        const requestId = nextRequestId(`${requestOwner}_${prefix}`);
+        const dispose = (): void => signal?.removeEventListener('abort', abort);
+        const abort = (): void => {
+          pendingRef.current.delete(requestId);
+          dispose();
+          reject(new Error('The app view closed.'));
+        };
+        pendingRef.current.set(requestId, pending(resolve, reject, dispose));
+        signal?.addEventListener('abort', abort, { once: true });
+        try {
+          send(message(requestId));
+        } catch (error: unknown) {
+          pendingRef.current.delete(requestId);
+          dispose();
+          reject(error instanceof Error ? error : new Error(String(error)));
+        }
+      }),
+    [isConnected, requestOwner, send],
+  );
+
+  const readAppView = useCallback(
+    (viewKey: string, signal?: AbortSignal): Promise<TAppView> =>
+      request<TAppView>(
+        'app_view',
+        (requestId) => readAppViewMessage(requestId, viewKey),
+        (resolve, reject, dispose) => ({ answer: 'app_view', resolve, reject, dispose }),
+        signal,
+      ),
+    [request],
+  );
+
+  const callAppTool = useCallback(
+    (
+      viewKey: string,
+      name: string,
+      args: TAppToolArguments,
+      signal?: AbortSignal,
+    ): Promise<TAppToolOutcome> =>
+      request<TAppToolOutcome>(
+        'app_tool',
+        (requestId) => callAppToolMessage(requestId, viewKey, name, args),
+        (resolve, reject, dispose) => ({ answer: 'app_tool_result', resolve, reject, dispose }),
+        signal,
+      ),
+    [request],
+  );
+
+  /** True when the message answered one of this hook's requests; every other message is not its own. */
+  const handleAppViewMessage = useCallback(
+    (msg: TServerMessage): boolean => {
+      if (msg.type === 'app_view' || msg.type === 'app_tool_result') {
+        const pending = pendingRef.current.get(msg.requestId);
+        // A reply to a request that already settled (or never was ours) matches nothing.
+        if (pending === undefined || pending.answer !== msg.type) return true;
+        pendingRef.current.delete(msg.requestId);
+        pending.dispose();
+        if (msg.type === 'app_view' && pending.answer === 'app_view') {
+          pending.resolve(msg.view);
+        } else if (msg.type === 'app_tool_result' && pending.answer === 'app_tool_result') {
+          const { success, data, parts, error } = msg;
+          pending.resolve({
+            success,
+            ...(data !== undefined ? { data } : {}),
+            ...(parts !== undefined ? { parts } : {}),
+            ...(error !== undefined ? { error } : {}),
+          });
+        }
+        return true;
+      }
+      if (msg.type === 'protocol_error' && msg.requestId !== undefined) {
+        const pending = pendingRef.current.get(msg.requestId);
+        if (pending === undefined) return msg.requestId.startsWith(`${requestOwner}_`);
+        pendingRef.current.delete(msg.requestId);
+        pending.dispose();
+        pending.reject(new Error(msg.message));
+        return true;
+      }
+      return false;
+    },
+    [requestOwner],
+  );
+
+  return { readAppView, callAppTool, handleAppViewMessage, rejectPendingAppRequests };
+}

package/src/hooks/useSessionClient.ts

@@ -23,6 +23,7 @@ import {
 import { createWsSessionClient } from '../client/ws-session-client.js';
 import { SERVER_MESSAGE_HANDLING } from './server-message-handling.js';
 import { useAgentSwitcherState } from './use-agent-switcher-state.js';
+import { useAppViewRequests } from './use-app-view-requests.js';
 import { useExecutionDetailState } from './use-execution-detail.js';
 import { useModelListState } from './use-model-list.js';
 import { usePersonalUsageState } from './use-personal-usage.js';
@@ -153,7 +154,7 @@ function toolEndFields(
   state: IToolState,
 ): Pick<
   IActiveTool,
-  'status' | 'result' | 'diffLines' | 'diffFile' | 'toolResultData' | 'toolResultParts'
+  'status' | 'result' | 'diffLines' | 'diffFile' | 'toolResultData' | 'toolResultParts' | 'appView'
 > {
   return {
     // A tool that finished with an error result renders failed (ToolCard/ToolGroup key off
@@ -168,6 +169,7 @@ function toolEndFields(
     ...(state.diffFile ? { diffFile: state.diffFile } : {}),
     ...(state.toolResultData !== undefined ? { toolResultData: state.toolResultData } : {}),
     ...(state.toolResultParts ? { toolResultParts: state.toolResultParts } : {}),
+    ...(state.appView ? { appView: state.appView } : {}),
   };
 }
 
@@ -268,6 +270,8 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   makeClient: TMakeSessionClient<TStatus>,
 ): IWsSessionState<TStatus> {
   const [status, setStatus] = useState<TStatus>('disconnected' as TStatus);
+  // The app-view requests read this to refuse at once when no connection exists to answer them.
+  const statusRef = useRef<TStatus>('disconnected' as TStatus);
   const [messages, setMessages] = useState<TConversationEntry[]>([]);
   const [activeTools, setActiveTools] = useState<IActiveTool[]>([]);
   const [streamingText, setStreamingText] = useState('');
@@ -433,6 +437,9 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     useExecutionDetailState(send);
   const { handleModelListMessage, ...modelListState } = useModelListState(send);
   const { handleProjectMessage, ...projectPanelState } = useProjectPanelState(send);
+  const isConnected = useCallback((): boolean => statusRef.current === 'connected', []);
+  const { handleAppViewMessage, rejectPendingAppRequests, readAppView, callAppTool } =
+    useAppViewRequests(send, isConnected);
   const {
     handleSessionsMessage,
     canListSessions,
@@ -466,6 +473,8 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       if (handleExecutionDetailMessage(msg)) return;
       if (handleModelListMessage(msg)) return;
       if (handleProjectMessage(msg)) return;
+      // A reply to a request an app view's host made (the view's document, or a tool it called).
+      if (handleAppViewMessage(msg)) return;
       if (handleSessionsMessage(msg)) return;
       if (handleSettingsMessage(msg)) return;
       if (handleAgentDefinitionsMessage(msg)) return;
@@ -649,6 +658,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
         }
         // #3189: the host made another session current — drop what this one showed, re-read it all.
         case 'session_switched': {
+          rejectPendingAppRequests('The active session changed.');
           settleSessionChange();
           // Nothing of the old session stays on screen until the new one's answers arrive.
           sessionStatusRef.current = null;
@@ -675,6 +685,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           break;
         }
         case 'history_cleared': {
+          rejectPendingAppRequests('The session history was cleared.');
           streamingTextRef.current = '';
           turnSegmentsRef.current = [];
           setStreamingText('');
@@ -868,6 +879,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       closeExecutionDetail,
       finishTurn,
       handleAgentDefinitionsMessage,
+      handleAppViewMessage,
       handleExecutionDetailMessage,
       handleModelListMessage,
       handleProjectMessage,
@@ -882,6 +894,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       requestSchedules,
       requestSessions,
       resolveSwitchResult,
+      rejectPendingAppRequests,
       send,
       setSessionSidebarOpen,
       settleSessionChange,
@@ -905,7 +918,10 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
 
   useEffect(() => {
     const onStatusChange = (next: TStatus): void => {
+      statusRef.current = next;
       setStatus(next);
+      // A reply lost with the connection never arrives; the views waiting on one learn that now.
+      if (next !== 'connected') rejectPendingAppRequests();
       // Every client learns what it can offer and what is in effect as soon as it is attached.
       if (next === 'connected') {
         // A reply lost with the old connection never arrives; stop waiting for it.
@@ -933,8 +949,16 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     return () => {
       client.disconnect();
       clientRef.current = null;
+      rejectPendingAppRequests();
     };
-  }, [makeClient, handleMessage, requestSessions, requestSchedules, armRestore]);
+  }, [
+    makeClient,
+    handleMessage,
+    requestSessions,
+    requestSchedules,
+    armRestore,
+    rejectPendingAppRequests,
+  ]);
 
   return {
     status,
@@ -966,6 +990,8 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     openAgentSwitcher,
     ...agentSwitcherState,
     ...schedulesState,
+    readAppView,
+    callAppTool,
     helpOpen,
     openHelp,
     closeHelp,

package/src/index.ts

@@ -16,7 +16,13 @@ export type {
   ISessionClientHandle,
   TMakeSessionClient,
 } from './hooks/useSessionClient.js';
-export type { TSessionListing, TSessionsError } from './hooks/session-client-types.js';
+export type {
+  TAppToolArguments,
+  TAppToolOutcome,
+  TAppView,
+  TSessionListing,
+  TSessionsError,
+} from './hooks/session-client-types.js';
 // Issue #3280 §5: a host that can restart the runtime calls this before reloading the page, so the
 // first session listing after reconnecting can switch back to the session the person was in.
 export { rememberSessionForRestore } from './hooks/use-session-directory.js';