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

package/src/components/SessionSurfaceChrome.tsx

@@ -268,7 +268,7 @@ function noticeSentence(notice: ISessionNotice): string | null {
 }
 
 /**
- * Session and protocol failures, as dismissible toasts over the top-right corner: they stay until
+ * Session outcomes and protocol failures, as dismissible toasts over the top-right corner: they stay until
  * dismissed, and never push the conversation or the composer out of view. Command output is not
  * here — it belongs to the conversation. A provider error classified at the wire boundary shows one
  * plain sentence with the next step; its raw text sits behind "Details" rather than as the headline.
@@ -280,13 +280,16 @@ export function SessionNotices({ state }: { state: IWsSessionState }): React.Rea
     <div className="pointer-events-none absolute right-4 top-16 z-40 flex w-[min(400px,calc(100%-32px))] flex-col gap-2">
       {notices.slice(-3).map((notice) => {
         const sentence = noticeSentence(notice);
+        const compacted = notice.kind === 'context-compacted';
         return (
           <div
             key={notice.id}
-            role="alert"
+            role={compacted ? 'status' : 'alert'}
             className="gui-rise pointer-events-auto flex items-start gap-3 rounded-xl bg-popover px-4 py-3 text-[14px] leading-snug text-popover-foreground shadow-xl shadow-black/30"
           >
-            <span className="mt-[7px] h-2 w-2 flex-shrink-0 rounded-full bg-destructive" />
+            <span
+              className={`mt-[7px] h-2 w-2 flex-shrink-0 rounded-full ${compacted ? 'bg-primary' : 'bg-destructive'}`}
+            />
             <span className="max-h-40 flex-1 overflow-y-auto whitespace-pre-wrap break-words">
               {sentence ?? notice.message}
               {sentence && (

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

@@ -20,11 +20,11 @@ export const SERVER_MESSAGE_HANDLING = {
   error: 'visible-notice',
   command_result: 'reducer-state',
   messages: 'reducer-state',
-  // #3189: the full history and its change signal serve a client that renders the whole session
-  // (the TUI); this surface builds its transcript from `messages` and the streamed turn.
+  // The full system history serves the TUI; this transcript uses `messages` and streamed turns.
+  // A history change carries optional compaction metadata for a notice without replacing the turn.
   history: 'intentionally-not-rendered',
-  history_changed: 'intentionally-not-rendered',
-  context: 'intentionally-not-rendered',
+  history_changed: 'visible-notice',
+  context: 'reducer-state',
   turn_source: 'intentionally-not-rendered',
   commands: 'reducer-state',
   session_status: 'reducer-state',
@@ -62,10 +62,9 @@ export const SERVER_MESSAGE_HANDLING = {
   project_status: 'reducer-state',
   project_diff: 'reducer-state',
   project_memory: 'reducer-state',
-  // The app-view host (the next step) consumes both: the document a finished call named, and the
-  // outcome of a tool call it made for that view.
-  app_view: 'intentionally-not-rendered',
-  app_tool_result: 'intentionally-not-rendered',
+
+  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;
 }
 
 /**
@@ -151,7 +157,8 @@ export interface ISessionNotice {
     | 'protocol-error'
     | 'session-change-refused'
     | 'background-task-control-failed'
-    | 'command-failed';
+    | 'command-failed'
+    | 'context-compacted';
   message: string;
   /**
    * A `session-error` classified at the wire boundary (#3289 §3) — present only when the host could
@@ -326,4 +333,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,
@@ -457,6 +464,10 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
   } = useAgentSwitcherState(send);
   const { handleSchedulesMessage, requestSchedules, ...schedulesState } = useSchedulesState(send);
 
+  const clearCompactionNotices = useCallback((): void => {
+    setSessionNotices((previous) => previous.filter((notice) => notice.kind !== 'context-compacted'));
+  }, []);
+
   const handleMessage = useCallback(
     (msg: TServerMessage): void => {
       // ARCH-2164: touching the exhaustive registry here keeps every decoded variant tied to an
@@ -466,6 +477,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,10 +662,12 @@ 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;
           setSessionStatus(null);
+          clearCompactionNotices();
           streamingTextRef.current = '';
           turnSegmentsRef.current = [];
           setStreamingText('');
@@ -675,6 +690,8 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           break;
         }
         case 'history_cleared': {
+          clearCompactionNotices();
+          rejectPendingAppRequests('The session history was cleared.');
           streamingTextRef.current = '';
           turnSegmentsRef.current = [];
           setStreamingText('');
@@ -782,6 +799,29 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
           setCommandCatalog(catalog);
           break;
         }
+        case 'context': {
+          // A later status snapshot supplies identity and the latest context when none is known yet.
+          if (sessionStatusRef.current !== null) {
+            const next = { ...sessionStatusRef.current, context: msg.state };
+            sessionStatusRef.current = next;
+            setSessionStatus(next);
+          }
+          break;
+        }
+        case 'history_changed': {
+          const compact = msg.compact;
+          if (compact?.trigger === 'auto') {
+            setSessionNotices((previous) => [
+              ...previous,
+              {
+                id: nextId(),
+                kind: 'context-compacted',
+                message: `Auto compacted context: ${Math.round(compact.beforeUsedPercentage)}% → ${Math.round(compact.afterUsedPercentage)}%`,
+              },
+            ]);
+          }
+          break;
+        }
         case 'session_status': {
           sessionStatusRef.current = msg.status;
           setSessionStatus(msg.status);
@@ -866,8 +906,10 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       appendEntry,
       canListSessions,
       closeExecutionDetail,
+      clearCompactionNotices,
       finishTurn,
       handleAgentDefinitionsMessage,
+      handleAppViewMessage,
       handleExecutionDetailMessage,
       handleModelListMessage,
       handleProjectMessage,
@@ -882,6 +924,7 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
       requestSchedules,
       requestSessions,
       resolveSwitchResult,
+      rejectPendingAppRequests,
       send,
       setSessionSidebarOpen,
       settleSessionChange,
@@ -905,7 +948,13 @@ 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();
+        clearCompactionNotices();
+      }
       // 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 +982,17 @@ export function useSessionClient<TStatus extends string = TConnectionStatus>(
     return () => {
       client.disconnect();
       clientRef.current = null;
+      rejectPendingAppRequests();
     };
-  }, [makeClient, handleMessage, requestSessions, requestSchedules, armRestore]);
+  }, [
+    makeClient,
+    handleMessage,
+    clearCompactionNotices,
+    requestSessions,
+    requestSchedules,
+    armRestore,
+    rejectPendingAppRequests,
+  ]);
 
   return {
     status,
@@ -966,6 +1024,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';