@robota-sdk/agent-ui-web 3.1.2 → 3.3.0

package/src/hooks/useSessionClient.ts

@@ -6,6 +6,7 @@
  * WITHOUT this core depending on that surface's types — keeping the dependency direction acyclic.
  */
 
+import { isObserverMessageType } from '@robota-sdk/agent-transport';
 import { useState, useEffect, useRef, useCallback } from 'react';
 
 import { excludedCommandMessage, isExcludedCommand } from './excluded-commands.js';
@@ -53,7 +54,7 @@ import type {
   TPermissionResultValue,
 } from '@robota-sdk/agent-interface-session';
 import type { IExecutionWorkspaceSnapshot } from '@robota-sdk/agent-interface-execution';
-import type { TServerMessage } from '@robota-sdk/agent-transport';
+import type { TServerMessage, TSessionSurfaceRole } from '@robota-sdk/agent-transport';
 
 export type {
   IActiveTool,
@@ -272,6 +273,10 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   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);
+  // The role the host gave this connection; null until it answers and again once the connection drops.
+  const [role, setRole] = useState<TSessionSurfaceRole | null>(null);
+  const roleRef = useRef<TSessionSurfaceRole | null>(null);
+  const isObserving = useCallback((): boolean => roleRef.current === 'observe', []);
   const [messages, setMessages] = useState<TConversationEntry[]>([]);
   const [activeTools, setActiveTools] = useState<IActiveTool[]>([]);
   const [streamingText, setStreamingText] = useState('');
@@ -368,8 +373,21 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   // Their request ids, for this connection: a refusal names the request it answers. A switch
   // answers with no id, so an id that succeeded stays here until the connection is replaced.
   const sessionChangeRequestIdsRef = useRef(new Set<string>());
+  const [executionDetailInput, setExecutionDetailInput] = useState<{
+    taskId: string;
+    status: 'pending' | 'sent' | 'failed';
+  }>();
+  const executionDetailInputRef = useRef<string | null>(null);
   const send = useCallback(
     (msg: TClientMessage): void => {
+      // A frame an observer may not send never leaves, so nothing may start waiting for its reply.
+      // The surface's own answers (`/help`, an excluded command) still run below.
+      const refused = isObserving() && !isObserverMessageType(msg.type);
+      if (msg.type === 'send-background-task') {
+        if (refused || executionDetailInputRef.current !== null) return;
+        executionDetailInputRef.current = msg.taskId;
+        setExecutionDetailInput({ taskId: msg.taskId, status: 'pending' });
+      }
       if (msg.type === 'command') {
         // #3282 §4e: `/help` is the GUI's own Help sheet — never sent to the session.
         if (msg.name === 'help') {
@@ -393,15 +411,17 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           });
           return;
         }
+        if (refused) return;
         commandsInFlightRef.current += 1;
       }
+      if (refused) return;
       if (msg.type === 'switch-session' || msg.type === 'new-session') {
         sessionChangesInFlightRef.current += 1;
         if (msg.requestId !== undefined) sessionChangeRequestIdsRef.current.add(msg.requestId);
       }
       clientRef.current?.send(msg);
     },
-    [appendEntry],
+    [appendEntry, isObserving],
   );
   /** One session change this surface asked for has been answered. */
   const settleSessionChange = useCallback((requestId?: string): void => {
@@ -433,20 +453,24 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     [send],
   );
   const { handleUsageMessage, ...personalUsageState } = usePersonalUsageState(send);
-  const { handleExecutionDetailMessage, closeExecutionDetail, ...executionDetailState } =
-    useExecutionDetailState(send);
+  const {
+    handleExecutionDetailMessage,
+    handleExecutionWorkspace,
+    closeExecutionDetail,
+    ...executionDetailState
+  } = 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);
+    useAppViewRequests(send, isConnected, isObserving);
   const {
     handleSessionsMessage,
     canListSessions,
     markCurrent,
     armRestore,
     ...sessionDirectoryState
-  } = useSessionDirectoryState(send);
+  } = useSessionDirectoryState(send, isObserving);
   const { requestSessions, setSessionSidebarOpen } = sessionDirectoryState;
   const { handleSettingsMessage, openSettings, refreshSettings, ...settingsState } =
     useSettingsState(send);
@@ -465,7 +489,9 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   const { handleSchedulesMessage, requestSchedules, ...schedulesState } = useSchedulesState(send);
 
   const clearCompactionNotices = useCallback((): void => {
-    setSessionNotices((previous) => previous.filter((notice) => notice.kind !== 'context-compacted'));
+    setSessionNotices((previous) =>
+      previous.filter((notice) => notice.kind !== 'context-compacted'),
+    );
   }, []);
 
   const handleMessage = useCallback(
@@ -488,6 +514,11 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       // types already do below, never in place of it.
       if (handleSchedulesMessage(msg)) return;
       switch (msg.type) {
+        case 'surface_role': {
+          roleRef.current = msg.role;
+          setRole(msg.role);
+          break;
+        }
         case 'messages': {
           // #3288 §2: `display` is the server's projection of this same history into tool rows,
           // diffs and "Changed files" — a reload/reconnect/resume replay renders THAT. `display` is
@@ -552,19 +583,29 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           break;
         }
         case 'execution_workspace_event': {
+          handleExecutionWorkspace(msg.snapshot);
           setExecutionWorkspace(msg.snapshot);
           break;
         }
         // #3288 §1: a Stop that did not take effect (e.g. the task/loop had already finished) is
         // worth telling the operator; a success shows itself through the snapshot update above.
         case 'background_task_control_result': {
+          if (msg.action === 'send' && executionDetailInputRef.current === msg.taskId) {
+            executionDetailInputRef.current = null;
+            setExecutionDetailInput({
+              taskId: msg.taskId,
+              status: msg.success ? 'sent' : 'failed',
+            });
+          }
           if (!msg.success) {
             setSessionNotices((previous) => [
               ...previous,
               {
                 id: nextId(),
                 kind: 'background-task-control-failed',
-                message: msg.message ?? `Could not stop ${msg.taskId}.`,
+                message:
+                  msg.message ??
+                  `Could not ${msg.action === 'send' ? 'send to' : 'stop'} ${msg.taskId}.`,
               },
             ]);
           }
@@ -765,6 +806,13 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           break;
         }
         case 'protocol_error': {
+          if (
+            executionDetailInputRef.current !== null &&
+            msg.message === 'Not permitted for an observer: send-background-task'
+          ) {
+            setExecutionDetailInput({ taskId: executionDetailInputRef.current, status: 'failed' });
+            executionDetailInputRef.current = null;
+          }
           if (sessionChangesInFlightRef.current > 0) {
             // A host older than `session_change_failed` refuses a session change with this.
             settleSessionChange();
@@ -911,6 +959,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       handleAgentDefinitionsMessage,
       handleAppViewMessage,
       handleExecutionDetailMessage,
+      handleExecutionWorkspace,
       handleModelListMessage,
       handleProjectMessage,
       handleSchedulesMessage,
@@ -950,10 +999,19 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     const onStatusChange = (next: TStatus): void => {
       statusRef.current = next;
       setStatus(next);
+      if (next !== 'connected') {
+        roleRef.current = null;
+        setRole(null);
+      }
       // A reply lost with the connection never arrives; the views waiting on one learn that now.
       if (next !== 'connected') {
         rejectPendingAppRequests();
         clearCompactionNotices();
+        closeExecutionDetail();
+        if (executionDetailInputRef.current !== null) {
+          setExecutionDetailInput({ taskId: executionDetailInputRef.current, status: 'failed' });
+          executionDetailInputRef.current = null;
+        }
       }
       // Every client learns what it can offer and what is in effect as soon as it is attached.
       if (next === 'connected') {
@@ -963,6 +1021,8 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
         sessionChangesInFlightRef.current = 0;
         sessionChangeRequestIdsRef.current.clear();
         pendingIntentRef.current = null;
+        // First, so its reply precedes the session listing the reconnect restore reads.
+        client.send({ type: 'get-surface-role' });
         client.send({ type: 'get-commands' });
         client.send({ type: 'get-status' });
         // #3280 §2: a reconnect that lands back on the SAME session (the common case) fires no
@@ -976,7 +1036,16 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
         requestSchedules();
       }
     };
-    const client = makeClient({ onMessage: handleMessage, onStatusChange });
+    const inner = makeClient({ onMessage: handleMessage, onStatusChange });
+    // The host is the authority; this only keeps an observer from sending what the host would refuse.
+    const client: ISessionClientHandle = {
+      connect: () => inner.connect(),
+      disconnect: () => inner.disconnect(),
+      send: (msg) => {
+        if (roleRef.current === 'observe' && !isObserverMessageType(msg.type)) return;
+        inner.send(msg);
+      },
+    };
     clientRef.current = client;
     client.connect();
     return () => {
@@ -988,6 +1057,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     makeClient,
     handleMessage,
     clearCompactionNotices,
+    closeExecutionDetail,
     requestSessions,
     requestSchedules,
     armRestore,
@@ -1005,6 +1075,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     commandCatalog,
     sessionStatus,
     ownDriverId,
+    role,
     send,
     sendCommandSilently,
     pendingPrompts,
@@ -1013,6 +1084,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     answerAsk,
     ...personalUsageState,
     ...executionDetailState,
+    executionDetailInput,
     closeExecutionDetail,
     ...modelListState,
     ...projectPanelState,

package/src/index.ts

@@ -29,6 +29,8 @@ export { rememberSessionForRestore } from './hooks/use-session-directory.js';
 
 // ── WS session client (loopback / localhost) ────────────────
 export { createWsSessionClient } from './client/ws-session-client.js';
+export { createDesktopSessionClient } from './client/desktop-session-client.js';
+export type { IDesktopSessionBridge } from './client/desktop-session-client.js';
 export type { IWsSessionClientCallbacks, TConnectionStatus } from './client/ws-session-client.js';
 export { resolveClientRuntimeHost } from './client/runtime-host.js';
 export type {