@robota-sdk/agent-ui-web 0.0.0-stage → 3.0.0-beta.93

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

@@ -0,0 +1,118 @@
+/**
+ * #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 type { TClientMessage } from '../client/ws-session-client.js';
+import type {
+  IExecutionDetailCursor,
+  IExecutionDetailRecord,
+} from '@robota-sdk/agent-interface-execution';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+export type TExecutionDetailStatus = 'idle' | 'loading' | 'ready' | 'error';
+
+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;
+  openExecutionDetail: (entryId: string) => void;
+  loadMoreExecutionDetail: () => void;
+  closeExecutionDetail: () => void;
+}
+
+let requestCounter = 0;
+function nextRequestId(): string {
+  requestCounter += 1;
+  return `execdetail_${requestCounter}_${Date.now()}`;
+}
+
+export function useExecutionDetailState(
+  send: (msg: TClientMessage) => void,
+): IExecutionDetailState & { handleExecutionDetailMessage: (msg: TServerMessage) => boolean } {
+  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 requestIdRef = useRef<string | null>(null);
+  const entryIdRef = useRef<string | null>(null);
+  const nextCursorRef = useRef<IExecutionDetailCursor | undefined>(undefined);
+
+  const readPage = useCallback(
+    (entryId: string, cursor?: IExecutionDetailCursor): void => {
+      const requestId = nextRequestId();
+      requestIdRef.current = requestId;
+      entryIdRef.current = entryId;
+      setStatus('loading');
+      setError(null);
+      send({ type: 'read-execution-detail', requestId, entryId, cursor });
+    },
+    [send],
+  );
+
+  const openExecutionDetail = useCallback(
+    (entryId: string): void => {
+      setOpenEntryId(entryId);
+      setRecords([]);
+      setComplete(false);
+      nextCursorRef.current = undefined;
+      readPage(entryId);
+    },
+    [readPage],
+  );
+
+  const loadMoreExecutionDetail = useCallback((): void => {
+    if (!openEntryId || status === 'loading' || complete) return;
+    readPage(openEntryId, nextCursorRef.current);
+  }, [openEntryId, status, complete, readPage]);
+
+  const closeExecutionDetail = useCallback((): void => {
+    setOpenEntryId(null);
+    requestIdRef.current = null;
+    entryIdRef.current = null;
+    setRecords([]);
+    setStatus('idle');
+    setError(null);
+    setComplete(false);
+  }, []);
+
+  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);
+      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;
+  }, []);
+
+  return {
+    openEntryId,
+    executionDetailStatus: status,
+    executionDetailRecords: records,
+    executionDetailError: error,
+    executionDetailComplete: complete,
+    openExecutionDetail,
+    loadMoreExecutionDetail,
+    closeExecutionDetail,
+    handleExecutionDetailMessage,
+  };
+}

package/src/hooks/use-media-query.ts

@@ -0,0 +1,27 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Tracks whether `query` currently matches, reactively (#3289 §2 — the narrow-window session sheet
+ * below `md`). A host without `window.matchMedia` (an older embedding, or a non-browser test) reports
+ * `false` and never subscribes, rather than throwing.
+ */
+export function useMediaQuery(query: string): boolean {
+  const [matches, setMatches] = useState<boolean>(() => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return false;
+    return window.matchMedia(query).matches;
+  });
+
+  useEffect(() => {
+    if (typeof window === 'undefined' || typeof window.matchMedia !== 'function') return undefined;
+    const mql = window.matchMedia(query);
+    const onChange = (): void => setMatches(mql.matches);
+    onChange();
+    mql.addEventListener('change', onChange);
+    return () => mql.removeEventListener('change', onChange);
+  }, [query]);
+
+  return matches;
+}
+
+/** Tailwind's `md` breakpoint (768px) — below it, the session list is a sheet rather than a column. */
+export const NARROW_WINDOW_QUERY = '(max-width: 767.98px)';

package/src/hooks/use-model-list.ts

@@ -0,0 +1,45 @@
+import { useCallback, useRef, useState } from 'react';
+
+import type { IWsSessionState, TModelListSnapshot } from './session-client-types.js';
+import type { TClientMessage } from '../client/ws-session-client.js';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+type TModelListState = Pick<IWsSessionState, 'modelList' | 'requestModelList'>;
+
+let requestCounter = 0;
+function nextRequestId(): string {
+  requestCounter += 1;
+  return `model_list_${requestCounter}_${Date.now()}`;
+}
+
+/**
+ * #3282 §2 (part 2) — the model list the model control's pop-up menu is built from, requested on
+ * demand (`list-models`) and correlated by `requestId` (mirrors `usePersonalUsageState`'s pattern) so
+ * a reply to an older request — one already superseded by a newer one, e.g. across a reconnect — is
+ * never applied over the list a still-open menu is currently showing.
+ */
+export function useModelListState(send: (msg: TClientMessage) => void): TModelListState & {
+  handleModelListMessage: (msg: TServerMessage) => boolean;
+} {
+  const [modelList, setModelList] = useState<TModelListSnapshot | null>(null);
+  const requestRef = useRef<string | null>(null);
+
+  const handleModelListMessage = useCallback((msg: TServerMessage): boolean => {
+    if (msg.type !== 'model_list') return false;
+    if (requestRef.current !== msg.requestId) return true;
+    setModelList({
+      groups: msg.groups,
+      currentModel: msg.currentModel,
+      ...(msg.currentProfile !== undefined ? { currentProfile: msg.currentProfile } : {}),
+    });
+    return true;
+  }, []);
+
+  const requestModelList = useCallback((): void => {
+    const requestId = nextRequestId();
+    requestRef.current = requestId;
+    send({ type: 'list-models', requestId });
+  }, [send]);
+
+  return { modelList, requestModelList, handleModelListMessage };
+}

package/src/hooks/use-personal-usage.ts

@@ -0,0 +1,138 @@
+import { useCallback, useRef, useState } from 'react';
+
+import type {
+  IWsSessionState,
+  TCurrentSessionUsageReport,
+  TPersonalUsageReport,
+  TStoredSessionUsageReport,
+} from './session-client-types.js';
+import type { TClientMessage } from '../client/ws-session-client.js';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+type TPersonalUsageState = Pick<
+  IWsSessionState,
+  | 'personalUsageStatus'
+  | 'personalUsageReport'
+  | 'personalUsageError'
+  | 'requestPersonalUsage'
+  | 'storedSessionUsageStatus'
+  | 'storedSessionUsageReport'
+  | 'storedSessionUsageSessionId'
+  | 'storedSessionUsageError'
+  | 'requestStoredSessionUsage'
+  | 'currentSessionUsageStatus'
+  | 'currentSessionUsageReport'
+  | 'requestCurrentSessionUsage'
+>;
+
+let requestCounter = 0;
+function nextRequestId(prefix: string): string {
+  requestCounter += 1;
+  return `${prefix}_${requestCounter}_${Date.now()}`;
+}
+
+/** Own the correlated aggregate/stored/current usage protocol state independently from chat state. */
+export function usePersonalUsageState(send: (msg: TClientMessage) => void): TPersonalUsageState & {
+  handleUsageMessage: (msg: TServerMessage) => boolean;
+} {
+  const [personalUsageStatus, setPersonalUsageStatus] =
+    useState<IWsSessionState['personalUsageStatus']>('idle');
+  const [personalUsageReport, setPersonalUsageReport] = useState<TPersonalUsageReport | null>(null);
+  const [personalUsageError, setPersonalUsageError] = useState<string | null>(null);
+  const [storedSessionUsageStatus, setStoredSessionUsageStatus] =
+    useState<IWsSessionState['storedSessionUsageStatus']>('idle');
+  const [storedSessionUsageReport, setStoredSessionUsageReport] =
+    useState<TStoredSessionUsageReport | null>(null);
+  const [storedSessionUsageSessionId, setStoredSessionUsageSessionId] = useState<string | null>(
+    null,
+  );
+  const [storedSessionUsageError, setStoredSessionUsageError] = useState<string | null>(null);
+  const [currentSessionUsageStatus, setCurrentSessionUsageStatus] =
+    useState<IWsSessionState['currentSessionUsageStatus']>('idle');
+  const [currentSessionUsageReport, setCurrentSessionUsageReport] =
+    useState<TCurrentSessionUsageReport | null>(null);
+  const personalRequestRef = useRef<string | null>(null);
+  const storedRequestRef = useRef<string | null>(null);
+
+  const handleUsageMessage = useCallback((msg: TServerMessage): boolean => {
+    if (msg.type === 'personal_usage_report' || msg.type === 'personal_usage_report_error') {
+      if (personalRequestRef.current !== msg.requestId) return true;
+      setPersonalUsageReport(msg.type === 'personal_usage_report' ? msg.report : null);
+      setPersonalUsageError(msg.type === 'personal_usage_report_error' ? msg.message : null);
+      setPersonalUsageStatus(msg.type === 'personal_usage_report' ? 'ready' : 'error');
+      return true;
+    }
+    if (msg.type === 'usage_report') {
+      setCurrentSessionUsageReport(msg.report);
+      setCurrentSessionUsageStatus('ready');
+      return true;
+    }
+    if (
+      msg.type === 'stored_session_usage_report' ||
+      msg.type === 'stored_session_usage_report_error'
+    ) {
+      if (storedRequestRef.current !== msg.requestId) return true;
+      setStoredSessionUsageReport(msg.type === 'stored_session_usage_report' ? msg.report : null);
+      setStoredSessionUsageSessionId(msg.sessionId);
+      setStoredSessionUsageError(
+        msg.type === 'stored_session_usage_report_error' ? msg.message : null,
+      );
+      setStoredSessionUsageStatus(msg.type === 'stored_session_usage_report' ? 'ready' : 'error');
+      return true;
+    }
+    if (msg.type === 'protocol_error') {
+      setCurrentSessionUsageStatus((current) => (current === 'loading' ? 'error' : current));
+    }
+    return false;
+  }, []);
+
+  const requestPersonalUsage = useCallback(
+    (period: '7d' | '30d'): void => {
+      const requestId = nextRequestId('personal_usage');
+      personalRequestRef.current = requestId;
+      setPersonalUsageStatus('loading');
+      setPersonalUsageError(null);
+      send({
+        type: 'get-personal-usage-report',
+        requestId,
+        period,
+        timezone: Intl.DateTimeFormat().resolvedOptions().timeZone || 'UTC',
+      });
+    },
+    [send],
+  );
+
+  const requestStoredSessionUsage = useCallback(
+    (sessionId: string): void => {
+      const requestId = nextRequestId('stored_session_usage');
+      storedRequestRef.current = requestId;
+      setStoredSessionUsageStatus('loading');
+      setStoredSessionUsageReport(null);
+      setStoredSessionUsageSessionId(sessionId);
+      setStoredSessionUsageError(null);
+      send({ type: 'get-stored-session-usage-report', requestId, sessionId });
+    },
+    [send],
+  );
+
+  const requestCurrentSessionUsage = useCallback((): void => {
+    setCurrentSessionUsageStatus('loading');
+    send({ type: 'get-usage-report' });
+  }, [send]);
+
+  return {
+    personalUsageStatus,
+    personalUsageReport,
+    personalUsageError,
+    requestPersonalUsage,
+    storedSessionUsageStatus,
+    storedSessionUsageReport,
+    storedSessionUsageSessionId,
+    storedSessionUsageError,
+    requestStoredSessionUsage,
+    currentSessionUsageStatus,
+    currentSessionUsageReport,
+    requestCurrentSessionUsage,
+    handleUsageMessage,
+  };
+}

package/src/hooks/use-project-panel.ts

@@ -0,0 +1,117 @@
+import { useCallback, useRef, useState } from 'react';
+
+import type { IWsSessionState } from './session-client-types.js';
+import type { TClientMessage } from '../client/ws-session-client.js';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+type TProjectPanelState = Pick<
+  IWsSessionState,
+  | 'projectStatusState'
+  | 'projectStatus'
+  | 'requestProjectStatus'
+  | 'projectDiffState'
+  | 'projectDiffPath'
+  | 'projectDiff'
+  | 'requestProjectDiff'
+  | 'projectMemoryState'
+  | 'projectMemory'
+  | 'requestProjectMemory'
+>;
+
+let requestCounter = 0;
+function nextRequestId(prefix: string): string {
+  requestCounter += 1;
+  return `${prefix}_${requestCounter}_${Date.now()}`;
+}
+
+/**
+ * #3282 §4c — the Project panel's correlated request/response state (status, one file's diff, project
+ * memory), independent from chat state. Mirrors `usePersonalUsageState`'s shape: a status per read, a
+ * `requestId` ref that drops a stale reply (a diff request superseded by clicking another file before
+ * the first answered), and a request function per read.
+ */
+export function useProjectPanelState(
+  send: (msg: TClientMessage) => void,
+): TProjectPanelState & { handleProjectMessage: (msg: TServerMessage) => boolean } {
+  const [projectStatusState, setProjectStatusState] =
+    useState<IWsSessionState['projectStatusState']>('idle');
+  const [projectStatus, setProjectStatus] = useState<IWsSessionState['projectStatus']>(null);
+  const [projectDiffState, setProjectDiffState] =
+    useState<IWsSessionState['projectDiffState']>('idle');
+  const [projectDiffPath, setProjectDiffPath] = useState<string | null>(null);
+  const [projectDiff, setProjectDiff] = useState<IWsSessionState['projectDiff']>(null);
+  const [projectMemoryState, setProjectMemoryState] =
+    useState<IWsSessionState['projectMemoryState']>('idle');
+  const [projectMemory, setProjectMemory] = useState<IWsSessionState['projectMemory']>(null);
+
+  const statusRequestRef = useRef<string | null>(null);
+  const diffRequestRef = useRef<string | null>(null);
+  const memoryRequestRef = useRef<string | null>(null);
+
+  const handleProjectMessage = useCallback((msg: TServerMessage): boolean => {
+    if (msg.type === 'project_status') {
+      if (statusRequestRef.current !== msg.requestId) return true;
+      setProjectStatus(msg.result);
+      setProjectStatusState('ready');
+      return true;
+    }
+    if (msg.type === 'project_diff') {
+      if (diffRequestRef.current !== msg.requestId) return true;
+      setProjectDiff(msg.result);
+      setProjectDiffState('ready');
+      return true;
+    }
+    if (msg.type === 'project_memory') {
+      if (memoryRequestRef.current !== msg.requestId) return true;
+      setProjectMemory(msg.result);
+      setProjectMemoryState('ready');
+      return true;
+    }
+    if (msg.type === 'protocol_error' && msg.requestId !== undefined) {
+      if (statusRequestRef.current === msg.requestId) setProjectStatusState('error');
+      if (diffRequestRef.current === msg.requestId) setProjectDiffState('error');
+      if (memoryRequestRef.current === msg.requestId) setProjectMemoryState('error');
+    }
+    return false;
+  }, []);
+
+  const requestProjectStatus = useCallback((): void => {
+    const requestId = nextRequestId('project_status');
+    statusRequestRef.current = requestId;
+    setProjectStatusState('loading');
+    send({ type: 'project-status', requestId });
+  }, [send]);
+
+  const requestProjectDiff = useCallback(
+    (path: string): void => {
+      const requestId = nextRequestId('project_diff');
+      diffRequestRef.current = requestId;
+      setProjectDiffPath(path);
+      setProjectDiffState('loading');
+      setProjectDiff(null);
+      send({ type: 'project-diff', requestId, path });
+    },
+    [send],
+  );
+
+  const requestProjectMemory = useCallback((): void => {
+    const requestId = nextRequestId('project_memory');
+    memoryRequestRef.current = requestId;
+    setProjectMemoryState('loading');
+    send({ type: 'project-memory', requestId });
+  }, [send]);
+
+  return {
+    projectStatusState,
+    projectStatus,
+    requestProjectStatus,
+    projectDiffState,
+    projectDiffPath,
+    projectDiff,
+    requestProjectDiff,
+    projectMemoryState,
+    projectMemory,
+    requestProjectMemory,
+    handleProjectMessage,
+  };
+}

package/src/hooks/use-schedules-state.ts

@@ -0,0 +1,92 @@
+import { useCallback, useState } from 'react';
+
+import type { IWsSessionState } from './session-client-types.js';
+import type { TClientMessage } from '../client/ws-session-client.js';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+type TSchedulesState = Pick<
+  IWsSessionState,
+  'scheduledTasks' | 'pauseSchedule' | 'resumeSchedule' | 'deleteSchedule'
+>;
+
+/**
+ * #3282 §4 part b-3: the Agents panel's "Scheduled" group. No `requestId` correlates
+ * `get-background-tasks`/`background_tasks` (the message carries none — see `wire-messages.ts`), so
+ * this owns that whole message type for the GUI: every reply is a full refresh of the roster,
+ * filtered server-side to `kind: 'scheduled'` (the same tasks `/schedule list` shows).
+ *
+ * Pause/resume send the SAME `command` text `/schedule pause <id>` / `/schedule resume <id>` runs.
+ * Delete sends the existing `cancel-background-task` write — the same one Stop already uses for any
+ * other background-task kind (#3288/#3332) — since a schedule IS a background task, and cancelling
+ * one is permanent (distinct from the reversible pause), matching #3282 §4's "Delete…" requirement.
+ */
+export function useSchedulesState(send: (msg: TClientMessage) => void): TSchedulesState & {
+  /** Handles `background_tasks` and a `cancel` `background_task_control_result` — both refresh. */
+  handleSchedulesMessage: (msg: TServerMessage) => boolean;
+  requestSchedules: () => void;
+} {
+  const [scheduledTasks, setScheduledTasks] = useState<IWsSessionState['scheduledTasks']>([]);
+
+  const requestSchedules = useCallback((): void => {
+    send({ type: 'get-background-tasks', filter: { kind: 'scheduled' } });
+  }, [send]);
+
+  const handleSchedulesMessage = useCallback(
+    (msg: TServerMessage): boolean => {
+      if (msg.type === 'background_tasks') {
+        // Defensive narrowing: the request already asked for `kind: 'scheduled'` only, but the wire
+        // type carries the full union — this is the one place that turns "should be" into "is".
+        setScheduledTasks(
+          msg.tasks.filter(
+            (task): task is IWsSessionState['scheduledTasks'][number] => task.kind === 'scheduled',
+          ),
+        );
+        return true;
+      }
+      if (msg.type === 'background_task_control_result' && msg.action === 'cancel') {
+        // A schedule's Delete — refresh so a successful cancel drops it from the group at once; a
+        // refused one leaves the row exactly as it was (the central reducer's own case already
+        // turns a failure into a plain-message session notice — #3288 §1 — so this never duplicates it).
+        if (msg.success) requestSchedules();
+        return false; // not exclusively ours — other future consumers may still want this event
+      }
+      if (msg.type === 'command_result' && msg.name === 'schedule' && msg.success) {
+        // Pause/resume ran through the command path — refresh so the row's status/next-run follows.
+        requestSchedules();
+        return false; // the normal command-result handling (the conversation card) still applies
+      }
+      return false;
+    },
+    [requestSchedules],
+  );
+
+  const pauseSchedule = useCallback(
+    (taskId: string): void => {
+      send({ type: 'command', name: 'schedule', args: `pause ${taskId}` });
+    },
+    [send],
+  );
+
+  const resumeSchedule = useCallback(
+    (taskId: string): void => {
+      send({ type: 'command', name: 'schedule', args: `resume ${taskId}` });
+    },
+    [send],
+  );
+
+  const deleteSchedule = useCallback(
+    (taskId: string): void => {
+      send({ type: 'cancel-background-task', taskId });
+    },
+    [send],
+  );
+
+  return {
+    scheduledTasks,
+    pauseSchedule,
+    resumeSchedule,
+    deleteSchedule,
+    handleSchedulesMessage,
+    requestSchedules,
+  };
+}