@robota-sdk/agent-ui-web 3.1.1 → 3.2.1

package/src/hooks/use-execution-detail.ts

@@ -1,33 +1,29 @@
-/**
- * #3288 §1: the detail sheet's own correlated request/response state — which entry is open, its
- * accumulated transcript records, and whether more can be loaded. Owned independently from chat
- * state, the same way `use-personal-usage.ts` owns the usage-report protocol: one `requestId` per
- * outstanding read, so a stale reply for an entry the operator already closed (or a page they moved
- * past) is dropped rather than clobbering what is now on screen.
- */
-
-import { useCallback, useRef, useState } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
 
 import type { TClientMessage } from '../client/ws-session-client.js';
 import type {
+  IBackgroundTaskLogUnreadable,
   IExecutionDetailCursor,
   IExecutionDetailRecord,
+  IExecutionWorkspaceSnapshot,
 } from '@robota-sdk/agent-interface-execution';
 import type { TServerMessage } from '@robota-sdk/agent-transport';
 
 export type TExecutionDetailStatus = 'idle' | 'loading' | 'ready' | 'error';
+type TDetailMode = 'live' | 'transcript';
 
 export interface IExecutionDetailState {
-  /** The entry currently open in the detail sheet, or null when it is closed. */
   openEntryId: string | null;
   executionDetailStatus: TExecutionDetailStatus;
-  /** Every record read so far for the open entry, oldest first — pages accumulate via loadMoreExecutionDetail. */
   executionDetailRecords: readonly IExecutionDetailRecord[];
   executionDetailError: string | null;
-  /** True once a page came back with no `nextCursor` — nothing more to load. */
   executionDetailComplete: boolean;
+  executionDetailMode: TDetailMode;
+  executionDetailUnreadable: IBackgroundTaskLogUnreadable | undefined;
   openExecutionDetail: (entryId: string) => void;
   loadMoreExecutionDetail: () => void;
+  showEarlierExecutionDetail: () => void;
+  showLiveExecutionDetail: () => void;
   closeExecutionDetail: () => void;
 }
 
@@ -39,37 +35,65 @@ function nextRequestId(): string {
 
 export function useExecutionDetailState(
   send: (msg: TClientMessage) => void,
-): IExecutionDetailState & { handleExecutionDetailMessage: (msg: TServerMessage) => boolean } {
+): IExecutionDetailState & {
+  handleExecutionDetailMessage: (msg: TServerMessage) => boolean;
+  handleExecutionWorkspace: (snapshot: IExecutionWorkspaceSnapshot) => void;
+} {
   const [openEntryId, setOpenEntryId] = useState<string | null>(null);
   const [status, setStatus] = useState<TExecutionDetailStatus>('idle');
   const [records, setRecords] = useState<readonly IExecutionDetailRecord[]>([]);
   const [error, setError] = useState<string | null>(null);
   const [complete, setComplete] = useState(false);
+  const [mode, setMode] = useState<TDetailMode>('live');
+  const [unreadable, setUnreadable] = useState<IBackgroundTaskLogUnreadable>();
   const requestIdRef = useRef<string | null>(null);
   const entryIdRef = useRef<string | null>(null);
+  const modeRef = useRef<TDetailMode>('live');
   const nextCursorRef = useRef<IExecutionDetailCursor | undefined>(undefined);
+  const queuedRef = useRef<{ cursor?: IExecutionDetailCursor; refresh: boolean } | null>(null);
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const lastReadAtRef = useRef(0);
 
   const readPage = useCallback(
-    (entryId: string, cursor?: IExecutionDetailCursor): void => {
+    (entryId: string, cursor?: IExecutionDetailCursor, refresh = false): void => {
+      if (requestIdRef.current !== null) {
+        if (!refresh || queuedRef.current === null || queuedRef.current.refresh) {
+          queuedRef.current = { cursor, refresh };
+        }
+        return;
+      }
       const requestId = nextRequestId();
       requestIdRef.current = requestId;
-      entryIdRef.current = entryId;
-      setStatus('loading');
+      lastReadAtRef.current = Date.now();
+      if (!refresh) setStatus('loading');
       setError(null);
       send({ type: 'read-execution-detail', requestId, entryId, cursor });
     },
     [send],
   );
 
+  const clearPending = useCallback(() => {
+    if (timerRef.current !== null) clearTimeout(timerRef.current);
+    timerRef.current = null;
+    queuedRef.current = null;
+  }, []);
+  useEffect(() => clearPending, [clearPending]);
+
   const openExecutionDetail = useCallback(
     (entryId: string): void => {
+      clearPending();
+      requestIdRef.current = null;
+      entryIdRef.current = entryId;
+      modeRef.current = 'live';
+      setMode('live');
       setOpenEntryId(entryId);
       setRecords([]);
+      setUnreadable(undefined);
       setComplete(false);
       nextCursorRef.current = undefined;
       readPage(entryId);
     },
-    [readPage],
+    [clearPending, readPage],
   );
 
   const loadMoreExecutionDetail = useCallback((): void => {
@@ -77,32 +101,103 @@ export function useExecutionDetailState(
     readPage(openEntryId, nextCursorRef.current);
   }, [openEntryId, status, complete, readPage]);
 
+  const changeMode = useCallback(
+    (next: TDetailMode): void => {
+      const entryId = entryIdRef.current;
+      if (!entryId) return;
+      clearPending();
+      modeRef.current = next;
+      setMode(next);
+      setRecords([]);
+      setUnreadable(undefined);
+      setComplete(false);
+      setStatus('loading');
+      nextCursorRef.current = undefined;
+      readPage(entryId, next === 'transcript' ? { offset: 0 } : undefined);
+    },
+    [clearPending, readPage],
+  );
+
+  const showEarlierExecutionDetail = useCallback(() => changeMode('transcript'), [changeMode]);
+  const showLiveExecutionDetail = useCallback(() => changeMode('live'), [changeMode]);
+
   const closeExecutionDetail = useCallback((): void => {
+    clearPending();
     setOpenEntryId(null);
     requestIdRef.current = null;
     entryIdRef.current = null;
     setRecords([]);
+    setUnreadable(undefined);
     setStatus('idle');
     setError(null);
     setComplete(false);
-  }, []);
+  }, [clearPending]);
+
+  const scheduleRefresh = useCallback(
+    (entryId: string): void => {
+      if (timerRef.current !== null) return;
+      const delay = Math.max(0, 250 - (Date.now() - lastReadAtRef.current));
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        if (entryIdRef.current === entryId && modeRef.current === 'live') {
+          readPage(entryId, undefined, true);
+        }
+      }, delay);
+    },
+    [readPage],
+  );
 
-  const handleExecutionDetailMessage = useCallback((msg: TServerMessage): boolean => {
-    if (msg.type !== 'execution_detail' && msg.type !== 'execution_detail_error') return false;
-    if (requestIdRef.current !== msg.requestId) return true; // A stale/superseded read — ignored.
-    if (msg.type === 'execution_detail_error') {
-      setStatus('error');
-      setError(msg.message);
+  const handleExecutionWorkspace = useCallback(
+    (snapshot: IExecutionWorkspaceSnapshot): void => {
+      const entryId = entryIdRef.current;
+      if (!entryId || modeRef.current !== 'live') return;
+      const entry = snapshot.entries.find((item) => item.id === entryId);
+      if (entry?.resumeSessionId && entry.controls.includes('attach')) scheduleRefresh(entryId);
+    },
+    [scheduleRefresh],
+  );
+
+  const handleExecutionDetailMessage = useCallback(
+    (msg: TServerMessage): boolean => {
+      if (msg.type !== 'execution_detail' && msg.type !== 'execution_detail_error') return false;
+      if (requestIdRef.current !== msg.requestId) return true;
+      requestIdRef.current = null;
+      const queued = queuedRef.current;
+      queuedRef.current = null;
+      if (!queued || queued.refresh) {
+        if (msg.type === 'execution_detail_error') {
+          setStatus('error');
+          setError(msg.message);
+        } else {
+          setRecords((previous) =>
+            msg.page.cursor === undefined || msg.page.cursor.offset === 0
+              ? msg.page.records
+              : [...previous, ...msg.page.records],
+          );
+          setUnreadable((previous) => {
+            const current = msg.page.unreadable;
+            if (msg.page.cursor === undefined || msg.page.cursor.offset === 0) return current;
+            if (!previous) return current;
+            if (!current) return previous;
+            return {
+              locked: previous.locked + current.locked,
+              noKeys: previous.noKeys + current.noKeys,
+              doesNotOpen: previous.doesNotOpen + current.doesNotOpen,
+            };
+          });
+          nextCursorRef.current = msg.page.nextCursor;
+          setComplete(msg.page.nextCursor === undefined);
+          setStatus('ready');
+        }
+      }
+      if (queued && entryIdRef.current) {
+        if (queued.refresh) scheduleRefresh(entryIdRef.current);
+        else readPage(entryIdRef.current, queued.cursor);
+      }
       return true;
-    }
-    setRecords((previous) =>
-      msg.page.cursor === undefined ? msg.page.records : [...previous, ...msg.page.records],
-    );
-    nextCursorRef.current = msg.page.nextCursor;
-    setComplete(msg.page.nextCursor === undefined);
-    setStatus('ready');
-    return true;
-  }, []);
+    },
+    [readPage, scheduleRefresh],
+  );
 
   return {
     openEntryId,
@@ -110,9 +205,14 @@ export function useExecutionDetailState(
     executionDetailRecords: records,
     executionDetailError: error,
     executionDetailComplete: complete,
+    executionDetailMode: mode,
+    executionDetailUnreadable: unreadable,
     openExecutionDetail,
     loadMoreExecutionDetail,
+    showEarlierExecutionDetail,
+    showLiveExecutionDetail,
     closeExecutionDetail,
     handleExecutionDetailMessage,
+    handleExecutionWorkspace,
   };
 }

package/src/hooks/useSessionClient.ts

@@ -368,8 +368,18 @@ 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 => {
+      if (msg.type === 'send-background-task') {
+        if (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') {
@@ -433,8 +443,12 @@ 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', []);
@@ -465,7 +479,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(
@@ -552,19 +568,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 +791,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 +944,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       handleAgentDefinitionsMessage,
       handleAppViewMessage,
       handleExecutionDetailMessage,
+      handleExecutionWorkspace,
       handleModelListMessage,
       handleProjectMessage,
       handleSchedulesMessage,
@@ -954,6 +988,11 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       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') {
@@ -988,6 +1027,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     makeClient,
     handleMessage,
     clearCompactionNotices,
+    closeExecutionDetail,
     requestSessions,
     requestSchedules,
     armRestore,
@@ -1013,6 +1053,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 {