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

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';