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

package/src/components/SessionSurface.tsx

@@ -106,7 +106,8 @@ function SetupPanel({
 export function SessionSurface({
   state,
   surface,
-  personalUsageEnabled = false,
+  personalUsageEnabled: personalUsageRequested = false,
+  draftMode = 'persistent',
   onReconnect,
   pickFiles,
   getPathForFile,
@@ -117,6 +118,8 @@ export function SessionSurface({
   surface?: string;
   /** Desktop shells opt in; embedded/session-only surfaces keep their existing chat-only contract. */
   personalUsageEnabled?: boolean;
+  /** Secure desktop discards unsent text and attachment paths when the session closes. */
+  draftMode?: 'persistent' | 'volatile';
   /**
    * Present only when the host can restart the runtime after the connection is lost for good (issue
    * #3280 §5, the desktop app); absent in the browser, where the banner says how to reopen it instead.
@@ -135,6 +138,8 @@ export function SessionSurface({
 
   appViewSandboxUrl?: string;
 }): React.ReactElement {
+  // An observer sees the session but changes nothing; the host stays the authority, this is presentation.
+  const readOnly = state.role === 'observe';
   const [view, setView] = useState<TSessionView>('chat');
   const { identity } = useProductIdentity();
   const appViewHost = useMemo(
@@ -147,6 +152,8 @@ export function SessionSurface({
     }),
     [appViewSandboxUrl, state.readAppView, state.callAppTool, identity.displayName, surface],
   );
+  // The personal usage read is not admitted for an observer.
+  const personalUsageEnabled = personalUsageRequested && !readOnly;
   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.
@@ -177,8 +184,10 @@ export function SessionSurface({
   // #3282 §3: no provider is configured — the session is running (a placeholder stands in for the
   // real one), but there is nothing to reply with yet.
   const setupRequired = state.sessionStatus?.setupRequired === true;
+  // Switching, starting, renaming and deleting sessions are driver actions: an observer has no sidebar.
   const hasSessionList =
-    (state.sessionListing ?? null) !== null || state.sessionsError?.code === 'list_failed';
+    !readOnly &&
+    ((state.sessionListing ?? null) !== null || state.sessionsError?.code === 'list_failed');
   const sidebarOpen = hasSessionList && state.sessionSidebarOpen;
   const usage = personalUsageEnabled && view === 'usage';
   const project = view === 'project';
@@ -289,24 +298,28 @@ export function SessionSurface({
           <div className="min-h-0 flex-1">
             <PersonalUsageDashboard state={state} />
             {/* A gated turn waits on this answer, so it shows over whatever view is open. */}
-            <PermissionPrompt
-              layout="modal"
-              prompts={state.pendingPrompts}
-              onAnswerPermission={state.answerPermission}
-              onAnswerAsk={state.answerAsk}
-              ownDriverId={state.ownDriverId}
-            />
+            {readOnly ? null : (
+              <PermissionPrompt
+                layout="modal"
+                prompts={state.pendingPrompts}
+                onAnswerPermission={state.answerPermission}
+                onAnswerAsk={state.answerAsk}
+                ownDriverId={state.ownDriverId}
+              />
+            )}
           </div>
         ) : project ? (
           <div className="min-h-0 flex-1">
             <ProjectPanel state={state} onOpenMemoryInEditor={onOpenMemoryInEditor} />
-            <PermissionPrompt
-              layout="modal"
-              prompts={state.pendingPrompts}
-              onAnswerPermission={state.answerPermission}
-              onAnswerAsk={state.answerAsk}
-              ownDriverId={state.ownDriverId}
-            />
+            {readOnly ? null : (
+              <PermissionPrompt
+                layout="modal"
+                prompts={state.pendingPrompts}
+                onAnswerPermission={state.answerPermission}
+                onAnswerAsk={state.answerAsk}
+                ownDriverId={state.ownDriverId}
+              />
+            )}
           </div>
         ) : (
           <div className="flex min-h-0 flex-1">
@@ -317,7 +330,7 @@ export function SessionSurface({
                 onReconnect={onReconnect}
               />
               <div className="min-h-0 flex-1 overflow-hidden">
-                {setupRequired ? (
+                {setupRequired && !readOnly ? (
                   <SetupPanel
                     onSetUp={() => state.send({ type: 'command', name: 'provider', args: 'add' })}
                     disabled={state.status !== 'connected'}
@@ -325,7 +338,7 @@ export function SessionSurface({
                 ) : isEmpty ? (
                   <EmptyState />
                 ) : (
-                  <AppViewHostContext.Provider value={appViewHost}>
+                  <AppViewHostContext.Provider value={readOnly ? null : appViewHost}>
                     <ConversationView
                       messages={state.messages}
                       activeTools={state.activeTools}
@@ -341,21 +354,35 @@ export function SessionSurface({
               >
                 <GoalBar
                   status={state.sessionStatus ?? null}
-                  onStop={() => state.send({ type: 'command', name: 'goal', args: 'cancel' })}
-                />
-                <PermissionPrompt
-                  layout="dock"
-                  prompts={state.pendingPrompts}
-                  onAnswerPermission={state.answerPermission}
-                  onAnswerAsk={state.answerAsk}
-                  ownDriverId={state.ownDriverId}
-                  onFocusReturn={() => composerRef.current?.focus()}
+                  onStop={
+                    readOnly
+                      ? undefined
+                      : () => state.send({ type: 'command', name: 'goal', args: 'cancel' })
+                  }
                 />
+                {readOnly ? null : (
+                  <PermissionPrompt
+                    layout="dock"
+                    prompts={state.pendingPrompts}
+                    onAnswerPermission={state.answerPermission}
+                    onAnswerAsk={state.answerAsk}
+                    ownDriverId={state.ownDriverId}
+                    onFocusReturn={() => composerRef.current?.focus()}
+                  />
+                )}
                 {/* #3282 §3: hidden while there is no provider to send to — the setup panel's own
                     button is the only way in, so nobody types into a composer that goes nowhere. */}
-                {setupRequired ? null : (
+                {readOnly ? (
+                  <p
+                    role="status"
+                    className="rounded-2xl bg-card px-4 py-3 text-center text-[14px] text-muted-foreground"
+                  >
+                    Read-only: you are watching this session.
+                  </p>
+                ) : setupRequired ? null : (
                   <Composer
                     ref={composerRef}
+                    draftMode={draftMode}
                     catalog={state.commandCatalog ?? null}
                     status={state.sessionStatus ?? null}
                     connected={state.status === 'connected'}
@@ -405,13 +432,17 @@ export function SessionSurface({
                   selectedEntryId={state.openEntryId ?? undefined}
                   onSelect={(entry) => state.openExecutionDetail(entry.id)}
                   onReturnToConversation={() => state.closeExecutionDetail()}
-                  onStop={stopExecutionEntry}
+                  onStop={readOnly ? undefined : stopExecutionEntry}
                   schedules={state.scheduledTasks}
                   goal={currentGoal}
-                  onPauseSchedule={state.pauseSchedule}
-                  onResumeSchedule={state.resumeSchedule}
-                  onDeleteSchedule={state.deleteSchedule}
-                  onCancelGoal={() => state.send({ type: 'command', name: 'goal', args: 'cancel' })}
+                  onPauseSchedule={readOnly ? undefined : state.pauseSchedule}
+                  onResumeSchedule={readOnly ? undefined : state.resumeSchedule}
+                  onDeleteSchedule={readOnly ? undefined : state.deleteSchedule}
+                  onCancelGoal={
+                    readOnly
+                      ? undefined
+                      : () => state.send({ type: 'command', name: 'goal', args: 'cancel' })
+                  }
                 />
               </aside>
             )}
@@ -424,15 +455,37 @@ export function SessionSurface({
               complete={state.executionDetailComplete}
               onClose={() => state.closeExecutionDetail()}
               onLoadMore={() => state.loadMoreExecutionDetail()}
-              onStop={openEntry ? () => stopExecutionEntry(openEntry) : undefined}
+              onStop={openEntry && !readOnly ? () => stopExecutionEntry(openEntry) : undefined}
+              inputState={state.executionDetailInput}
+              mode={state.executionDetailMode}
+              unreadable={state.executionDetailUnreadable}
+              onShowEarlier={state.showEarlierExecutionDetail}
+              onShowLive={state.showLiveExecutionDetail}
+              onSend={
+                openEntry && !readOnly
+                  ? (prompt) =>
+                      state.send({
+                        type: 'send-background-task',
+                        taskId: openEntry.sourceId,
+                        input: { prompt },
+                      })
+                  : undefined
+              }
+              onContinue={
+                openEntry?.resumeSessionId && !readOnly
+                  ? () => {
+                      if (openEntry.resumeSessionId) state.switchSession(openEntry.resumeSessionId);
+                    }
+                  : undefined
+              }
             />
           </div>
         )}
       </div>
 
       <SessionNotices state={state} />
-      <SettingsScreen state={state} />
-      <AgentSwitcherSheet state={state} />
+      {readOnly ? null : <SettingsScreen state={state} />}
+      {readOnly ? null : <AgentSwitcherSheet state={state} />}
       <HelpSheet
         open={state.helpOpen}
         onClose={() => state.closeHelp()}

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

@@ -89,6 +89,8 @@ export const SERVER_MESSAGE_HANDLING = {
   background_task_control_result: 'visible-notice',
   protocol_error: 'visible-notice',
   resume_gap: 'transport-control',
+  // The connection's effective role: the session client holds it and stops sending what an observer may not.
+  surface_role: 'reducer-state',
   // #3282 §4a: the Settings screen's own correlated request/response state (`useSettingsState`).
   settings: 'reducer-state',
   settings_error: 'reducer-state',

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

@@ -16,7 +16,11 @@ import type {
   IExecutionDetailRecord,
   IExecutionWorkspaceSnapshot,
 } from '@robota-sdk/agent-interface-execution';
-import type { IWireAgentDefinitionSummary, TServerMessage } from '@robota-sdk/agent-transport';
+import type {
+  IWireAgentDefinitionSummary,
+  TServerMessage,
+  TSessionSurfaceRole,
+} from '@robota-sdk/agent-transport';
 
 export type { TAppToolArguments, TAppToolOutcome, TAppView } from '../app-view/types.js';
 
@@ -204,6 +208,8 @@ export interface IWsSessionState<TStatus extends string = TConnectionStatus> {
   sessionName: string | null;
   /** This connection's own driver id, learned from the server's first frame; null until then. */
   ownDriverId: TDriverId | null;
+  /** The role the host gave this connection, learned when it connects; null until the host answers. */
+  role: TSessionSurfaceRole | null;
   /** Null until the session has answered; refreshed after every command. */
   commandCatalog: TCommandCatalog | null;
   /** Null until the session has answered; refreshed after every command and turn. */
@@ -286,6 +292,11 @@ export interface IWsSessionState<TStatus extends string = TConnectionStatus> {
   executionDetailError: string | null;
   /** True once the last page read had no further cursor — nothing more to load. */
   executionDetailComplete: boolean;
+  executionDetailInput?: { taskId: string; status: 'pending' | 'sent' | 'failed' };
+  executionDetailMode?: 'live' | 'transcript';
+  executionDetailUnreadable?: { locked: number; noKeys: number; doesNotOpen: number };
+  showEarlierExecutionDetail?: () => void;
+  showLiveExecutionDetail?: () => void;
   openExecutionDetail: (entryId: string) => void;
   loadMoreExecutionDetail: () => void;
   closeExecutionDetail: () => void;

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

@@ -20,6 +20,7 @@ function nextRequestId(prefix: string): string {
 }
 
 const CONNECTION_CLOSED = 'The connection to the session closed.';
+const READ_ONLY = 'This session is read-only.';
 
 /**
  * The key a finished call's app view is read and called by, taken from the tool row's `appView`
@@ -53,6 +54,7 @@ function callAppToolMessage(
 export function useAppViewRequests(
   send: (msg: TClientMessage) => void,
   isConnected: () => boolean,
+  isObserving: () => boolean,
 ): {
   readAppView: (viewKey: string, signal?: AbortSignal) => Promise<TAppView>;
   callAppTool: (
@@ -92,6 +94,11 @@ export function useAppViewRequests(
           reject(new Error(signal?.aborted ? 'The app view closed.' : CONNECTION_CLOSED));
           return;
         }
+        // An observer's request is never sent, so no reply would come.
+        if (isObserving()) {
+          reject(new Error(READ_ONLY));
+          return;
+        }
         const requestId = nextRequestId(`${requestOwner}_${prefix}`);
         const dispose = (): void => signal?.removeEventListener('abort', abort);
         const abort = (): void => {
@@ -109,7 +116,7 @@ export function useAppViewRequests(
           reject(error instanceof Error ? error : new Error(String(error)));
         }
       }),
-    [isConnected, requestOwner, send],
+    [isConnected, isObserving, requestOwner, send],
   );
 
   const readAppView = useCallback(

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/use-session-directory.ts

@@ -81,7 +81,10 @@ function initialSidebarOpen(): boolean {
  * on its primary one. After a reconnect to such a host this surface goes back to the session it was
  * on; an older host has one session for everyone, so there is nothing to go back to.
  */
-export function useSessionDirectoryState(send: (msg: TClientMessage) => void): TSessionDirectoryState & {
+export function useSessionDirectoryState(
+  send: (msg: TClientMessage) => void,
+  isObserving: () => boolean,
+): TSessionDirectoryState & {
   handleSessionsMessage: (msg: TServerMessage) => boolean;
   /** Whether the host can list sessions, as far as its last answer says. */
   canListSessions: () => boolean;
@@ -148,12 +151,14 @@ export function useSessionDirectoryState(send: (msg: TClientMessage) => void): T
       // launch with no remembered id never reaches here (target stays null), so nothing switches.
       clearStoredRestoreId(browserNamespace);
       if (target === listing.currentSessionId) return;
+      // An observer never moves the session, so there is nothing to go back to.
+      if (isObserving()) return;
       if (!keepsSessionsLive(listing)) return;
       // A session the host no longer lists (an empty one it never saved) is nothing to go back to.
       if (!listing.sessions.some((row) => row.id === target)) return;
       send({ type: 'switch-session', sessionId: target, requestId: nextRequestId('session_change') });
     },
-    [send, browserNamespace],
+    [send, browserNamespace, isObserving],
   );
 
   const handleSessionsMessage = useCallback(