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

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

@@ -0,0 +1,92 @@
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+export type TServerMessageHandling =
+  'reducer-state' | 'visible-notice' | 'intentionally-not-rendered' | 'transport-control';
+
+/**
+ * ARCH-2164: exhaustive ownership for every decoded server variant on the shared GUI surface.
+ * Adding a wire variant without deciding its GUI disposition is a compile error instead of a silent
+ * reducer omission. `intentionally-not-rendered` is an explicit disposition for server-side query
+ * snapshots and domain events that this session/usage surface does not currently visualize.
+ */
+export const SERVER_MESSAGE_HANDLING = {
+  text_delta: 'reducer-state',
+  user_message: 'reducer-state',
+  tool_start: 'reducer-state',
+  tool_end: 'reducer-state',
+  thinking: 'reducer-state',
+  complete: 'reducer-state',
+  interrupted: 'reducer-state',
+  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.
+  history: 'intentionally-not-rendered',
+  history_changed: 'intentionally-not-rendered',
+  context: 'intentionally-not-rendered',
+  turn_source: 'intentionally-not-rendered',
+  commands: 'reducer-state',
+  session_status: 'reducer-state',
+  // #3282 §2 part 2: the reply to `list-models`, fed into `modelList` state by the model control's
+  // pop-up menu (`useModelListState`).
+  model_list: 'reducer-state',
+  // #3282 §4 part b-3: the agent switcher sheet's own correlated request/response state (`useAgentSwitcherState`).
+  agent_definitions: 'reducer-state',
+  sessions: 'reducer-state',
+  sessions_error: 'reducer-state',
+  session_switched: 'reducer-state',
+  session_change_failed: 'visible-notice',
+  session_renamed_in_list: 'reducer-state',
+  session_rename_failed: 'visible-notice',
+  session_deleted: 'reducer-state',
+  session_delete_failed: 'visible-notice',
+  usage_report: 'reducer-state',
+  personal_usage_report: 'reducer-state',
+  personal_usage_report_error: 'visible-notice',
+  stored_session_usage_report: 'reducer-state',
+  stored_session_usage_report_error: 'visible-notice',
+  executing: 'intentionally-not-rendered',
+  // #3280 §2: the prompt queued behind a running turn — shown above the composer with Edit/Remove.
+  pending: 'reducer-state',
+  execution_workspace_event: 'reducer-state',
+  // #3288 §1: the Agents panel's detail sheet reads a page at a time.
+  execution_detail: 'reducer-state',
+  execution_detail_error: 'reducer-state',
+  // Esc's loop stop is a TUI-only shortcut; this surface's loops stop through the Agents panel
+  // instead (`/loop stop <id>`, or `stop-waiting-loop` is simply never sent here).
+  waiting_loop_stop: 'intentionally-not-rendered',
+  // The Agents panel already reflects a task's cancel/close/send through `execution_workspace_event`;
+  // nothing here renders this narrower, task-only event on its own.
+  // #3282 §4c: the Project panel's reads — reduced into state by `useProjectPanelState`.
+  project_status: 'reducer-state',
+  project_diff: 'reducer-state',
+  project_memory: 'reducer-state',
+  background_task_event: 'intentionally-not-rendered',
+  background_job_group_event: 'intentionally-not-rendered',
+  plan_event: 'intentionally-not-rendered',
+  context_file_refreshed: 'intentionally-not-rendered',
+  branch_event: 'intentionally-not-rendered',
+  // #3282 §4 part b-3: the Agents panel's "Scheduled" group's own roster (`useSchedulesState`).
+  background_tasks: 'reducer-state',
+  background_task: 'intentionally-not-rendered',
+  background_job_groups: 'intentionally-not-rendered',
+  background_job_group: 'intentionally-not-rendered',
+  background_task_log: 'intentionally-not-rendered',
+  permission_request: 'reducer-state',
+  ask_request: 'reducer-state',
+  prompt_resolved: 'reducer-state',
+  ui_intent: 'reducer-state',
+  session_renamed: 'reducer-state',
+  history_cleared: 'reducer-state',
+  // #3288 §1: a failed Stop (e.g. a task that finished a moment before it arrived) is worth telling
+  // the operator; a success shows itself through the workspace snapshot's own update. #3282 §4 part
+  // b-3: a schedule's Delete uses this same `cancel-background-task` write — `useSchedulesState`
+  // refreshes the roster on a successful cancel, and a failure gets the same visible notice as Stop.
+  background_task_control_result: 'visible-notice',
+  protocol_error: 'visible-notice',
+  resume_gap: 'transport-control',
+  // #3282 §4a: the Settings screen's own correlated request/response state (`useSettingsState`).
+  settings: 'reducer-state',
+  settings_error: 'reducer-state',
+} as const satisfies Readonly<Record<TServerMessage['type'], TServerMessageHandling>>;

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

@@ -0,0 +1,329 @@
+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,
+  IToolState,
+  ISettingsSnapshot,
+  TDriverId,
+  TPermissionResultValue,
+  TSettingsPatch,
+} from '@robota-sdk/agent-interface-session';
+import type {
+  IBackgroundTaskState,
+  IExecutionDetailRecord,
+  IExecutionWorkspaceSnapshot,
+} from '@robota-sdk/agent-interface-execution';
+import type { IWireAgentDefinitionSummary, TServerMessage } from '@robota-sdk/agent-transport';
+
+export type TPersonalUsageReport = Extract<
+  TServerMessage,
+  { type: 'personal_usage_report' }
+>['report'];
+export type TStoredSessionUsageReport = Extract<
+  TServerMessage,
+  { type: 'stored_session_usage_report' }
+>['report'];
+/** The commands and skills the session offers — what a `/` menu lists. */
+export type TCommandCatalog = Omit<Extract<TServerMessage, { type: 'commands' }>, 'type'>;
+/** The session's status beside the conversation: model, permission mode, effort, context. */
+export type TSessionStatus = Extract<TServerMessage, { type: 'session_status' }>['status'];
+
+/**
+ * #3282 §2 (part 2): the models a person may switch to, grouped by configured provider profile —
+ * what the model control's pop-up menu is built from. `null` until requested (`list-models`).
+ */
+export type TModelListSnapshot = Omit<
+  Extract<TServerMessage, { type: 'model_list' }>,
+  'type' | 'requestId'
+>;
+
+/** The host's sessions in this workspace, which one is current, and the records it could not read. */
+export type TSessionListing = Extract<TServerMessage, { type: 'sessions' }>['listing'];
+/** Why the host did not list its sessions: it cannot (`not_available`), or listing failed. */
+export type TSessionsError = Omit<
+  Extract<TServerMessage, { type: 'sessions_error' }>,
+  'type' | 'requestId'
+>;
+
+export type TCurrentSessionUsageReport = Extract<
+  TServerMessage,
+  { type: 'usage_report' }
+>['report'];
+
+/** #3282 §4c — the Project panel's reads. Each result crosses the wire unchanged from the session
+ *  method's own return value (see `wire-messages.ts`'s doc comment on `project_status`). */
+export type TProjectStatusRead = Extract<TServerMessage, { type: 'project_status' }>['result'];
+export type TProjectDiffRead = Extract<TServerMessage, { type: 'project_diff' }>['result'];
+export type TProjectMemoryRead = Extract<TServerMessage, { type: 'project_memory' }>['result'];
+
+export interface IConversationMessage {
+  id: string;
+  role: 'user' | 'assistant';
+  content: string;
+  isStreaming?: boolean;
+  /** REMOTE-014 E5: the co-driving author of a user turn. */
+  author?: string;
+}
+
+/**
+ * The outcome of a slash command, shown in the conversation where it was typed — the TUI adds the
+ * same outcome to its transcript. `info` is a command this surface cannot carry out.
+ */
+export interface ICommandOutputEntry {
+  id: string;
+  role: 'command';
+  name: string;
+  content: string;
+  tone: 'success' | 'error' | 'info';
+}
+
+/** The tool calls of one finished turn, kept in the conversation ahead of the reply they led to. */
+export interface IToolGroupEntry {
+  id: string;
+  role: 'tools';
+  tools: readonly IActiveTool[];
+}
+
+/** One file an Edit/Write call touched during a turn, and the (latest) diff a click can open. */
+export interface IChangedFileSummary {
+  path: string;
+  added: number;
+  removed: number;
+  diffLines: readonly IDiffLine[];
+}
+
+/** #3288: a turn that changed files ends with this compact summary row. */
+export interface IChangedFilesEntry {
+  id: string;
+  role: 'changed-files';
+  files: readonly IChangedFileSummary[];
+}
+
+export type TConversationEntry =
+  IConversationMessage | ICommandOutputEntry | IToolGroupEntry | IChangedFilesEntry;
+
+export interface IActiveTool {
+  id: string;
+  name: string;
+  status: 'running' | 'done' | 'error';
+  input?: string;
+  result?: IToolState['result'];
+  /** #3288: correlates this call across `tool_start`/`tool_end` — how a finished call is matched. */
+  executionId?: string;
+  /** #3288: a unified diff (Edit/Write), built server-side — the same one an approval prompt showed. */
+  diffLines?: readonly IDiffLine[];
+  /** #3288: the file `diffLines` concerns, workspace-relative when the server could make it so. */
+  diffFile?: string;
+  /** #3288: the tool's raw result payload (Shell output, Read content, …), already capped server-side. */
+  toolResultData?: string;
+  /** Admitted observations; opaque resource URIs do not authorize a client-side fetch. */
+  toolResultParts?: IToolState['toolResultParts'];
+  /** #3288: a workspace-relative display form of a path argument, additive to `input`/`firstArg`. */
+  displayPath?: string;
+  /** #3288: set when this call is a projected `/command` tool — render "Ran /<commandName>". */
+  commandName?: string;
+  /** #3288: true for an internal signal tool (e.g. goal-status) — never rendered as a call. */
+  internal?: boolean;
+}
+
+/**
+ * #3280 §2: a prompt the host queued behind the running turn — the server has already taken it, so it
+ * is not lost, but it will not run until the turn ends. `count` is the TOTAL number waiting (the shown
+ * `text` plus any behind it), matching the wire's `pendingCount`.
+ */
+export interface IQueuedPrompt {
+  text: string;
+  count: number;
+}
+
+export interface ISessionNotice {
+  id: string;
+  /**
+   * `session-change-refused`: the host refused a new or switch this surface asked for.
+   * `background-task-control-failed`: a Stop in the Agents panel did not take effect.
+   * `command-failed` (#3282 §2 part 2): a change made through a status control (model/mode/effort)
+   * failed — a plain notice rather than a conversation card, since the control's own label is where
+   * a successful change confirms itself and the label stays unchanged when it fails.
+   */
+  kind:
+    | 'session-error'
+    | 'protocol-error'
+    | 'session-change-refused'
+    | 'background-task-control-failed'
+    | 'command-failed';
+  message: string;
+  /**
+   * A `session-error` classified at the wire boundary (#3289 §3) — present only when the host could
+   * tell what kind of failure this was. `SessionNotices` maps it to one plain sentence and keeps
+   * `message` behind a "Details" disclosure; absent, it shows `message` as before.
+   */
+  code?: 'auth' | 'rate_limit' | 'model_unavailable' | 'network' | 'provider';
+  provider?: string;
+  retryAfterSeconds?: number;
+  /**
+   * For `code: 'model_unavailable'`, the model the failed request tried — captured when the notice
+   * was created (from the wire frame's own `model`, or `sessionStatus` at that moment), never read
+   * live off the CURRENT session status. The person may switch models before dismissing the notice,
+   * and a live read would then blame the new model for the old failure.
+   */
+  model?: string;
+}
+
+export interface ISessionClientHandle {
+  connect: () => void;
+  disconnect: () => void;
+  send: (msg: TClientMessage) => void;
+}
+
+export type TMakeSessionClient<TStatus extends string = TConnectionStatus> = (callbacks: {
+  onMessage: (msg: TServerMessage) => void;
+  onStatusChange: (status: TStatus) => void;
+}) => ISessionClientHandle;
+
+export interface IWsSessionState<TStatus extends string = TConnectionStatus> {
+  status: TStatus;
+  /**
+   * Set by `useWsSession` once its reconnect retries give up (issue #3280 §5): the runtime is not
+   * coming back by itself. Cleared again once `status` reaches `connected`. Undefined for a reducer
+   * with no such concept (e.g. the WebRTC surface, which has its own `failed`/`refused` statuses).
+   */
+  connectionLost?: boolean;
+  messages: TConversationEntry[];
+  activeTools: IActiveTool[];
+  streamingText: string;
+  isThinking: boolean;
+  executionWorkspace: IExecutionWorkspaceSnapshot | null;
+  sessionName: string | null;
+  /** This connection's own driver id, learned from the server's first frame; null until then. */
+  ownDriverId: TDriverId | 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. */
+  sessionStatus: TSessionStatus | null;
+  /**
+   * #3282 §2 (part 2): the models the model control's pop-up menu offers. Null until requested — the
+   * menu asks for it when it opens (or refreshes it) rather than every surface fetching it eagerly.
+   */
+  modelList: TModelListSnapshot | null;
+  /** Ask the session for the current model list (a fresh `list-models` round trip). */
+  requestModelList: () => void;
+  /** Null until the host has answered; refreshed on connect, after a switch, a rename and a turn. */
+  sessionListing: TSessionListing | null;
+  /** Set when the host answered the latest listing request with an error instead. */
+  sessionsError: TSessionsError | null;
+  requestSessions: () => void;
+  /** Make another stored session current. A refusal arrives as a notice saying why. */
+  switchSession: (sessionId: string) => void;
+  /** Start a fresh session and make it current. */
+  newSession: () => void;
+  /** Rename a row in the list — current or not. A refusal arrives as a notice saying why. */
+  renameSessionInList: (sessionId: string, name: string) => void;
+  /** Delete a stored session for good. A refusal arrives as a notice saying why. */
+  deleteSession: (sessionId: string) => void;
+  /** Whether the session sidebar is shown; `/resume` opens it. */
+  sessionSidebarOpen: boolean;
+  setSessionSidebarOpen: (open: boolean) => void;
+  send: (msg: TClientMessage) => void;
+  /**
+   * #3282 §2 (part 2): run a command the SAME way `send({type:'command', ...})` does, but mark its
+   * outcome as controls-triggered — `useSessionClient` skips the conversation card for a change made
+   * this way (the control's own label confirms it instead), while a typed command keeps its card.
+   */
+  sendCommandSilently: (name: string, args?: string) => void;
+  pendingPrompts: readonly TPendingPrompt[];
+  /** #3280 §2: the prompt queued behind a running turn, or null when none is queued. */
+  queuedPrompt: IQueuedPrompt | null;
+  answerPermission: (id: string, result: TPermissionResultValue) => void;
+  answerAsk: (id: string, response: TActionResponse) => void;
+  personalUsageStatus: 'idle' | 'loading' | 'ready' | 'error';
+  personalUsageReport: TPersonalUsageReport | null;
+  personalUsageError: string | null;
+  requestPersonalUsage: (period: '7d' | '30d') => void;
+  storedSessionUsageStatus: 'idle' | 'loading' | 'ready' | 'error';
+  storedSessionUsageReport: TStoredSessionUsageReport | null;
+  storedSessionUsageSessionId: string | null;
+  storedSessionUsageError: string | null;
+  requestStoredSessionUsage: (sessionId: string) => void;
+  currentSessionUsageStatus: 'idle' | 'loading' | 'ready' | 'error';
+  currentSessionUsageReport: TCurrentSessionUsageReport | null;
+  requestCurrentSessionUsage: () => void;
+  sessionNotices: readonly ISessionNotice[];
+  dismissSessionNotice: (id: string) => void;
+  /** #3282 §4a: whether the Settings modal is shown. `/settings` and the gear button both open it. */
+  settingsOpen: boolean;
+  settingsStatus: 'idle' | 'loading' | 'ready' | 'error';
+  /** Null until the first `get-settings` reply arrives. */
+  settingsSnapshot: ISettingsSnapshot | null;
+  /** The plain message from the most recent failed read or write, if any. */
+  settingsError: string | null;
+  /** #3282 §4 part b-2: which section the screen should land on for the open in progress. */
+  settingsInitialSectionId: string | null;
+  /**
+   * Opens the screen and (re-)fetches its snapshot — the "reopen and see the new value" path.
+   * `sectionId` jumps straight to that section (e.g. `/plugin` → `'plugins'`, "Manage providers…"
+   * (#3282 §2/§4b) → `'providers'`); omitted opens on the screen's own default (General).
+   */
+  openSettings: (sectionId?: string) => void;
+  closeSettings: () => void;
+  /** A failed write leaves `settingsSnapshot` at its previous value; `settingsError` names why. */
+  updateSettings: (patch: TSettingsPatch) => void;
+  /** #3282 §4e: whether the Help sheet is shown. `/help` opens it instead of reaching the session. */
+  helpOpen: boolean;
+  openHelp: () => void;
+  closeHelp: () => void;
+  /** #3288 §1: the id of the execution-workspace entry open in the detail sheet, or null when closed. */
+  openEntryId: string | null;
+  executionDetailStatus: 'idle' | 'loading' | 'ready' | 'error';
+  executionDetailRecords: readonly IExecutionDetailRecord[];
+  executionDetailError: string | null;
+  /** True once the last page read had no further cursor — nothing more to load. */
+  executionDetailComplete: boolean;
+  openExecutionDetail: (entryId: string) => void;
+  loadMoreExecutionDetail: () => void;
+  closeExecutionDetail: () => void;
+  /** #3282 §4c — the Project panel's "Changes" section (git status). */
+  projectStatusState: 'idle' | 'loading' | 'ready' | 'error';
+  projectStatus: TProjectStatusRead | null;
+  requestProjectStatus: () => void;
+  /** #3282 §4c — the Project panel's "File diff" section, for the file `projectDiffPath` names. */
+  projectDiffState: 'idle' | 'loading' | 'ready' | 'error';
+  projectDiffPath: string | null;
+  projectDiff: TProjectDiffRead | null;
+  requestProjectDiff: (path: string) => void;
+  /** #3282 §4c — the Project panel's "Memory" section. */
+  projectMemoryState: 'idle' | 'loading' | 'ready' | 'error';
+  projectMemory: TProjectMemoryRead | null;
+  requestProjectMemory: () => void;
+  /**
+   * #3282 §4 part b-3: whether the agent switcher sheet is shown. `/agent` (bare) and this surface's
+   * own control both open it.
+   */
+  agentSwitcherOpen: boolean;
+  agentSwitcherStatus: 'idle' | 'loading' | 'ready' | 'error';
+  /** The available agents: name, one-line description, and where each is defined in plain words. */
+  agentDefinitions: readonly IWireAgentDefinitionSummary[];
+  /** The agent type `/agent <name>` (no prompt) currently selects — the checked row. */
+  currentAgentType: string | null;
+  /** The plain confirmation of the last selection's result, shown in the sheet — never a conversation card. */
+  agentSwitchMessage: string | null;
+  /** Opens the sheet and (re-)fetches its roster. */
+  openAgentSwitcher: () => void;
+  closeAgentSwitcher: () => void;
+  /** Runs the same path as `/agent <name>`. */
+  selectAgent: (agentType: string) => void;
+  /**
+   * #3282 §4 part b-3: the schedules shown in the Agents panel's "Scheduled" group — every
+   * `IBackgroundTaskState` of `kind: 'scheduled'`, refreshed on connect and after a write.
+   */
+  scheduledTasks: readonly IBackgroundTaskState<'scheduled'>[];
+  /** Runs the same path as `/schedule pause <id>` / `/schedule resume <id>`. */
+  pauseSchedule: (taskId: string) => void;
+  resumeSchedule: (taskId: string) => void;
+  /**
+   * Permanently stops a schedule — the same `cancel-background-task` write Stop already uses. A
+   * failure surfaces the same way a failed Stop does (#3288 §1's `background-task-control-failed`
+   * session notice) — no separate error state here.
+   */
+  deleteSchedule: (taskId: string) => void;
+}

package/src/hooks/ui-intent-state.ts

@@ -0,0 +1,74 @@
+/**
+ * CMD-004 Stage D — how the GUI surface answers a `ui_intent`.
+ *
+ * The server requester-routes `ui_intent`, so everything that arrives here was asked for by THIS
+ * surface and must be answered visibly. An intent with a GUI screen opens it (the session picker is
+ * the session sidebar, #3189; settings and the plugin manager both open the Settings modal, #3282
+ * §4a/§4 part b-2; the agent switcher is a sheet, #3282 §4 part b-3). #3282 §4e: an intent whose
+ * command is on the GUI's exclusion list never reaches here at all (`excluded-commands.ts` catches it
+ * before the session is asked) — this module only answers a screen this HOST cannot back even though
+ * the GUI knows how to render it (the session picker, when the host cannot list sessions), or a kind
+ * this build does not know at all — and it never says "not available on this surface": each gets its
+ * own plain, honest sentence instead.
+ */
+
+import { excludedCommandMessage } from './excluded-commands.js';
+
+import type { TCommandUiIntent } from '@robota-sdk/agent-interface-command';
+
+/** The command a user runs for the screen an intent asks for — how the info line is labelled. */
+export function uiIntentCommandName(intent: TCommandUiIntent): string {
+  switch (intent.type) {
+    case 'show-plugin-manager':
+      return 'plugin';
+    case 'show-settings':
+      return 'settings';
+    case 'show-session-picker':
+      return 'resume';
+    case 'show-agent-switcher':
+      return 'agent';
+    case 'show-theme-picker':
+      return 'theme';
+    default:
+      return (intent as { type: string }).type;
+  }
+}
+
+/** The GUI screen an intent opens, or null when this surface has none for it. */
+export function guiScreenForUiIntent(
+  intent: TCommandUiIntent,
+): 'session-sidebar' | 'settings' | 'settings-plugins' | 'agent-switcher' | null {
+  if (intent.type === 'show-session-picker') return 'session-sidebar';
+  if (intent.type === 'show-settings') return 'settings';
+  // #3282 §4 part b-2: `/plugin` opens the Settings screen's Plugins section, the way #3331 mapped
+  // `show-settings` — replacing the "not available on this surface" line this intent used to get.
+  if (intent.type === 'show-plugin-manager') return 'settings-plugins';
+  if (intent.type === 'show-agent-switcher') return 'agent-switcher';
+  return null;
+}
+
+/**
+ * Describe one intent for this surface: a plain, honest sentence for a screen this HOST cannot back
+ * right now (a session picker with no session list), the `/theme` exclusion this intent defensively
+ * reuses, or an unrecognized future kind. Never called for `show-settings`, `show-plugin-manager` or
+ * `show-agent-switcher` — all three always have a screen now (#3282 §4a, §4 part b-2, §4 part b-3) —
+ * but their cases are left out of this switch rather than kept as dead branches that would claim
+ * otherwise; an unknown wire-level kind (a newer host) still yields an explicit notice naming the raw
+ * kind, so the "never a silent no-op" floor holds for future intents too.
+ */
+export function describeUiIntentForGui(intent: TCommandUiIntent): string {
+  switch (intent.type) {
+    case 'show-session-picker':
+      // The GUI knows how to render this screen (`guiScreenForUiIntent` says so); it is only reached
+      // here when the HOST itself cannot list sessions, which is this host's limitation, not a
+      // missing GUI feature.
+      return 'This host cannot list sessions, so there is nothing to resume.';
+    case 'show-theme-picker':
+      // Defensive only: `/theme` is on the exclusion list and never reaches the session from the GUI.
+      return excludedCommandMessage('theme');
+    default:
+      // Spec-mandated unsupported signal for an intent kind this build does not know (not a
+      // fallback: the explicit notice IS the defined behavior for an unrenderable intent).
+      return `This client does not have a screen for '${(intent as { type: string }).type}' yet.`;
+  }
+}

package/src/hooks/use-agent-switcher-state.ts

@@ -0,0 +1,125 @@
+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 { IWireAgentDefinitionSummary } from '@robota-sdk/agent-transport';
+import type { TServerMessage } from '@robota-sdk/agent-transport';
+
+type TAgentSwitcherState = Pick<
+  IWsSessionState,
+  | 'agentSwitcherOpen'
+  | 'agentSwitcherStatus'
+  | 'agentDefinitions'
+  | 'currentAgentType'
+  | 'agentSwitchMessage'
+  | 'openAgentSwitcher'
+  | 'closeAgentSwitcher'
+  | 'selectAgent'
+>;
+
+let requestCounter = 0;
+function nextRequestId(prefix: string): string {
+  requestCounter += 1;
+  return `${prefix}_${requestCounter}_${Date.now()}`;
+}
+
+/**
+ * #3282 §4 part b-3: the agent switcher sheet's own correlated request/response state, the same
+ * shape `useSettingsState` already uses for `get-settings`/`update-settings` — independent from the
+ * chat conversation, because choosing an agent is answered by the sheet's own confirmation line
+ * ("Default agent: Explore"), never a conversation card (issue #3282 §4's decided design).
+ *
+ * `openAgentSwitcher` re-fetches every time (`/agent` bare, or reopening after a close), so a change
+ * made elsewhere reaches an open-then-reopened sheet, matching `useSettingsState`'s own reasoning.
+ *
+ * Choosing an agent runs the SAME path as typing `/agent <name>` — a plain `command` wire message —
+ * so the write goes through `executeCommand` exactly like every other command; this hook only
+ * correlates its own request so the reply lands in the sheet, not the conversation. The central
+ * `command_result` case in `useSessionClient` calls `resolveSwitchResult` to hand it the reply
+ * (and, critically, still performs the shared `commandsInFlightRef` bookkeeping itself — this hook
+ * never short-circuits `command_result` the way `handleAgentDefinitionsMessage` short-circuits reads).
+ */
+export function useAgentSwitcherState(send: (msg: TClientMessage) => void): TAgentSwitcherState & {
+  /** Handles `agent_definitions` only — never `command_result` (see the note above). */
+  handleAgentDefinitionsMessage: (msg: TServerMessage) => boolean;
+  /**
+   * Called from the central `command_result` case. Returns true when this requestId was the
+   * sheet's own pending switch, meaning the central handler must not also add a conversation card.
+   */
+  resolveSwitchResult: (
+    requestId: string | undefined,
+    result: { success: boolean; message: string },
+  ) => boolean;
+} {
+  const [agentSwitcherOpen, setAgentSwitcherOpen] = useState(false);
+  const [agentSwitcherStatus, setAgentSwitcherStatus] =
+    useState<IWsSessionState['agentSwitcherStatus']>('idle');
+  const [agentDefinitions, setAgentDefinitions] = useState<
+    readonly IWireAgentDefinitionSummary[]
+  >([]);
+  const [currentAgentType, setCurrentAgentType] = useState<string | null>(null);
+  const [agentSwitchMessage, setAgentSwitchMessage] = useState<string | null>(null);
+  const listRequestRef = useRef<string | null>(null);
+  const switchRequestRef = useRef<string | null>(null);
+
+  const handleAgentDefinitionsMessage = useCallback((msg: TServerMessage): boolean => {
+    if (msg.type !== 'agent_definitions') return false;
+    if (listRequestRef.current !== msg.requestId) return true; // superseded by a later request
+    setAgentDefinitions(msg.agents);
+    setCurrentAgentType(msg.current);
+    setAgentSwitcherStatus('ready');
+    return true;
+  }, []);
+
+  const requestAgentDefinitions = useCallback((): void => {
+    const requestId = nextRequestId('get_agent_definitions');
+    listRequestRef.current = requestId;
+    send({ type: 'get-agent-definitions', requestId });
+  }, [send]);
+
+  const openAgentSwitcher = useCallback((): void => {
+    setAgentSwitcherOpen(true);
+    setAgentSwitcherStatus((current) => (current === 'ready' ? 'ready' : 'loading'));
+    setAgentSwitchMessage(null);
+    requestAgentDefinitions();
+  }, [requestAgentDefinitions]);
+
+  const closeAgentSwitcher = useCallback((): void => {
+    setAgentSwitcherOpen(false);
+  }, []);
+
+  const selectAgent = useCallback(
+    (agentType: string): void => {
+      const requestId = nextRequestId('agent_switch');
+      switchRequestRef.current = requestId;
+      setAgentSwitchMessage(null);
+      // The SAME path `/agent <name>` runs: a plain command, not a dedicated write message.
+      send({ type: 'command', name: 'agent', args: agentType, requestId });
+    },
+    [send],
+  );
+
+  const resolveSwitchResult = useCallback(
+    (requestId: string | undefined, result: { success: boolean; message: string }): boolean => {
+      if (requestId === undefined || switchRequestRef.current !== requestId) return false;
+      switchRequestRef.current = null;
+      setAgentSwitchMessage(result.message);
+      if (result.success) requestAgentDefinitions();
+      return true;
+    },
+    [requestAgentDefinitions],
+  );
+
+  return {
+    agentSwitcherOpen,
+    agentSwitcherStatus,
+    agentDefinitions,
+    currentAgentType,
+    agentSwitchMessage,
+    openAgentSwitcher,
+    closeAgentSwitcher,
+    selectAgent,
+    handleAgentDefinitionsMessage,
+    resolveSwitchResult,
+  };
+}