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

package/src/components/composer-attachments.ts

@@ -0,0 +1,246 @@
+/**
+ * #3282 §4d — pure logic behind the composer's attach button and drag-and-drop, kept apart from
+ * `Composer.tsx` so it is testable without React or a DOM.
+ *
+ * The runtime resolves `@relative/path` references already (`prompt-file-reference-resolver.ts` in
+ * agent-framework): inside the workspace only, 64 KiB per file, 256 KiB total per prompt, 8 references
+ * per prompt, and (as of this change) refuses a binary file outright rather than mangling it. This
+ * module mirrors those same limits client-side so a file the runtime would refuse is never even
+ * attached: the running size and count totals, and a MIME/extension heuristic that refuses a
+ * likely-binary file (images included) up front, before it ever becomes a chip. It does not (and
+ * cannot) reuse the resolver's code directly: that package is Node-only, and this one ships to a plain
+ * browser tab too (agent-ui-web SPEC: no dependency on agent-framework).
+ */
+
+/** Mirrors `DEFAULT_MAX_FILE_BYTES` in `packages/agent-framework/src/context/prompt-file-reference-resolver.ts`. */
+export const MAX_ATTACHMENT_FILE_BYTES = 64 * 1024;
+/** Mirrors `DEFAULT_MAX_TOTAL_BYTES` in the same resolver. */
+export const MAX_ATTACHMENT_TOTAL_BYTES = 256 * 1024;
+/**
+ * Mirrors `DEFAULT_MAX_REFERENCES` in the same resolver — not imported directly (agent-ui-web has no
+ * dependency on agent-framework; see the module comment above), so this is a named constant kept in
+ * sync by hand. The runtime counts every `@`-reference in the final prompt, including one a person
+ * typed by hand, so a batch that fits under this count can still be refused server-side if the typed
+ * text already carries references of its own — this client-side count only catches the common case
+ * (the chips alone) before the round trip.
+ */
+export const MAX_ATTACHMENT_COUNT = 8;
+
+/** Shown whenever a file cannot be resolved to a path inside the workspace — rule 3 (#3282 §4). */
+export const ATTACHMENT_NO_PATH_NOTICE = 'Only files inside this project folder can be attached.';
+
+/** Shown once the running count of attachments would pass `MAX_ATTACHMENT_COUNT`. */
+export const ATTACHMENT_COUNT_LIMIT_NOTICE = `You can attach up to ${MAX_ATTACHMENT_COUNT} files to one message.`;
+
+/**
+ * Shown whenever a file looks binary (images included) — refused outright, never attached. Images are
+ * not sent as native content in this version (the wire and the interactive-session runtime do not
+ * carry `parts` from a submitted prompt yet), and the `@`-reference resolver has no way to carry
+ * binary bytes as text either, so there is no path that would work today.
+ */
+export const ATTACHMENT_NON_TEXT_NOTICE = "Images and other non-text files can't be attached yet.";
+
+/** One file the composer has turned into an `@`-reference chip, kept in the draft until sent or removed. */
+export interface IDraftAttachment {
+  readonly id: string;
+  readonly name: string;
+  /** Workspace-relative, forward-slash separated — what `@` names once inserted into the prompt. */
+  readonly relativePath: string;
+  readonly size: number;
+}
+
+/**
+ * One file the desktop host's native "Attach files" dialog returned (#3282 §4d). Kept in structural
+ * sync with `IPickedFile` in `apps/agent-gui-web/src/gui-host.ts` and
+ * `apps/agent-app/electron/sidecar.ts` — the three are not imported across the Electron/browser/
+ * presentation package boundaries, same as this codebase already does for the trust question.
+ */
+export interface IPickedFile {
+  readonly path: string;
+  readonly name: string;
+  readonly size: number;
+}
+
+/** A file offered to the composer, from a drop, the plain HTML picker, or the desktop dialog. */
+export interface ICandidateFile {
+  readonly name: string;
+  readonly size: number;
+  readonly mimeType?: string;
+  /** The real filesystem path, when the host could resolve one (desktop only). */
+  readonly absolutePath?: string;
+}
+
+export type TAttachOutcome =
+  | { readonly kind: 'attached'; readonly attachment: IDraftAttachment }
+  | { readonly kind: 'rejected'; readonly message: string };
+
+function normalizeSeparators(path: string): string {
+  return path.replaceAll('\\', '/');
+}
+
+/**
+ * Collapses `.` and `..` segments the way a filesystem path would, without touching disk — this
+ * module ships to a plain browser tab too, so it cannot use `node:path`. Applied to both sides before
+ * `relativeWorkspacePath` compares them, so a non-canonical path (one carrying `./`/`../` noise, e.g.
+ * from a symlink or an odd OS report) is judged by what it actually resolves to, not by a raw string
+ * prefix match that a `..` segment could otherwise defeat (a target that merely *starts with* the
+ * root string, `../` and all, must not be treated as inside it just because the raw text lines up).
+ */
+function normalizePathSegments(path: string): string {
+  const isRooted = path.startsWith('/');
+  const out: string[] = [];
+  for (const segment of path.split('/')) {
+    if (segment === '' || segment === '.') continue;
+    if (segment === '..') {
+      if (out.length > 0 && out[out.length - 1] !== '..') out.pop();
+      else if (!isRooted) out.push('..');
+      // A rooted path cannot go above its own root — drop silently, matching path.normalize.
+      continue;
+    }
+    out.push(segment);
+  }
+  return (isRooted ? '/' : '') + out.join('/');
+}
+
+/**
+ * The file's path relative to the workspace root, or `null` when it is not inside it (an absolute
+ * root is required; a relative/empty `workspacePath` never counts as "inside" anything). Both sides
+ * are canonicalized first (see `normalizePathSegments`), then compared exactly (case-sensitive): on a
+ * case-insensitive filesystem a differently-cased root is treated as outside rather than guessed at —
+ * the composer would rather show the plain notice than attach the wrong file.
+ */
+export function relativeWorkspacePath(
+  workspacePath: string | undefined,
+  absolutePath: string,
+): string | null {
+  if (!workspacePath) return null;
+  const root = normalizePathSegments(normalizeSeparators(workspacePath));
+  if (!root || root === '/') return null;
+  const target = normalizePathSegments(normalizeSeparators(absolutePath));
+  if (target === root) return null; // the root itself is a directory, not an attachable file
+  const prefix = `${root}/`;
+  if (!target.startsWith(prefix)) return null;
+  const relative = target.slice(prefix.length);
+  return relative ? relative : null;
+}
+
+/**
+ * A MIME type the browser reports for genuinely text-ish content — never refused as binary: the type
+ * starts with `text/`, or ends with `+json`, `+xml`, `/json`, or `/xml` (e.g. `application/ld+json`,
+ * `image/svg+xml`). Kept as two separately anchored tests rather than one alternation — `|` binds
+ * looser than `^`/`$`, so a single pattern like `/^text\/|(?:\+|\/)(?:json|xml)$/` reads ambiguously
+ * (flagged by CodeQL as misleading operator precedence) even though each anchor was already scoped to
+ * the alternative it belongs to.
+ */
+function isTextyMimeType(mimeType: string): boolean {
+  return /^text\//.test(mimeType) || /[+/](?:json|xml)$/.test(mimeType);
+}
+const BINARY_EXTENSIONS = new Set([
+  'png', 'jpg', 'jpeg', 'gif', 'webp', 'bmp', 'ico', 'tiff', 'heic',
+  'pdf', 'zip', 'tar', 'gz', 'tgz', '7z', 'rar',
+  'exe', 'dll', 'so', 'dylib', 'bin', 'class', 'wasm',
+  'woff', 'woff2', 'ttf', 'otf', 'eot',
+  'mp3', 'mp4', 'mov', 'avi', 'wav', 'ogg', 'flac', 'm4a',
+]);
+
+/**
+ * Whether the file looks binary (never sniffs bytes — MIME/extension only). When the browser reports
+ * a MIME type (a drop, or the plain HTML picker), ANY non-text type refuses it — images, PDFs,
+ * archives, and anything else a browser did not call `text/…`/JSON/XML. The desktop dialog gives no
+ * MIME type at all, so a picked file falls back to the extension denylist.
+ */
+export function looksBinary(name: string, mimeType: string | undefined): boolean {
+  if (mimeType) return !isTextyMimeType(mimeType);
+  const dot = name.lastIndexOf('.');
+  if (dot < 0) return false;
+  return BINARY_EXTENSIONS.has(name.slice(dot + 1).toLowerCase());
+}
+
+/** The same terminator set `prompt-file-reference-parser.ts` stops an `@`-reference token at. */
+const UNSAFE_REFERENCE_CHARS = /[\s)\]}>,;"'`]/u;
+/**
+ * `prompt-file-reference-parser.ts`'s `stripTrailingPunctuation` also trims a trailing `.,:;!?` off
+ * every captured `@token` — `,`/`;` are already covered above (they can appear anywhere in that
+ * set), but a path merely *ending* in `.`/`:`/`!`/`?` (fine mid-string — most files have a `.`) would
+ * otherwise be silently truncated by the runtime, so the chip would name a file the reference can
+ * never actually resolve.
+ */
+const UNSAFE_TRAILING_CHAR = /[.,:;!?]$/u;
+
+function formatBytes(bytes: number): string {
+  return bytes >= 1024 ? `${Math.round(bytes / 1024)} KB` : `${bytes} B`;
+}
+
+function randomId(): string {
+  const cryptoObj = typeof crypto !== 'undefined' ? crypto : undefined;
+  if (cryptoObj?.randomUUID) return cryptoObj.randomUUID();
+  return `${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
+
+/**
+ * Decide what a candidate file becomes: a chip, or a plain rejection message. `existingTotalBytes` is
+ * the sum of what is already attached and `existingCount` is how many chips there already are, so the
+ * running 256 KiB total and the 8-file count are both enforced before the file is added rather than
+ * after. The count is checked first, matching the runtime's own `checkReferenceBudget` (which also
+ * checks its reference-count limit before it ever looks at the path) — once the cap is reached, every
+ * further file gets the same one clear reason rather than a mix of different messages depending on
+ * which check happens to run first for each one.
+ */
+export function evaluateCandidateFile(
+  file: ICandidateFile,
+  workspacePath: string | undefined,
+  existingTotalBytes: number,
+  existingCount: number,
+): TAttachOutcome {
+  if (existingCount >= MAX_ATTACHMENT_COUNT) {
+    return { kind: 'rejected', message: ATTACHMENT_COUNT_LIMIT_NOTICE };
+  }
+  if (!file.absolutePath) return { kind: 'rejected', message: ATTACHMENT_NO_PATH_NOTICE };
+  const relativePath = relativeWorkspacePath(workspacePath, file.absolutePath);
+  if (relativePath === null) return { kind: 'rejected', message: ATTACHMENT_NO_PATH_NOTICE };
+  if (UNSAFE_REFERENCE_CHARS.test(relativePath) || UNSAFE_TRAILING_CHAR.test(relativePath)) {
+    return {
+      kind: 'rejected',
+      message: `"${file.name}" has a character (such as a space, or a period/punctuation mark at the end) the @file syntax can't carry — rename it to attach it.`,
+    };
+  }
+  // Refused outright, never mangled: the runtime's own @-reference resolver now refuses a binary
+  // file the same way (a NUL byte in the first 8 KiB) — this just says so before the round trip.
+  if (looksBinary(file.name, file.mimeType)) {
+    return { kind: 'rejected', message: ATTACHMENT_NON_TEXT_NOTICE };
+  }
+  if (file.size > MAX_ATTACHMENT_FILE_BYTES) {
+    return {
+      kind: 'rejected',
+      message: `${file.name} is larger than ${formatBytes(MAX_ATTACHMENT_FILE_BYTES)} and cannot be attached.`,
+    };
+  }
+  if (existingTotalBytes + file.size > MAX_ATTACHMENT_TOTAL_BYTES) {
+    return {
+      kind: 'rejected',
+      message: `Attachments cannot total more than ${formatBytes(MAX_ATTACHMENT_TOTAL_BYTES)}.`,
+    };
+  }
+  return {
+    kind: 'attached',
+    attachment: { id: randomId(), name: file.name, relativePath, size: file.size },
+  };
+}
+
+/**
+ * Inserts each chip as the runtime's existing `@relative/path` reference syntax — rule 2 (#3282 §4).
+ * Always prefixed with `./`: the parser's `isPathLikeReference` only treats a token as a file
+ * reference when it has a `.` somewhere or an explicit relative-path prefix, so a dotless name like
+ * `Makefile`, `Dockerfile` or `LICENSE` — common, useful, and never refused for lacking one — would
+ * otherwise be sent as plain text with no file and no diagnostic (follow-up to #3282 §4d). `./` makes
+ * every path path-like regardless of its name, and the resolver collapses it back to the plain
+ * relative path before use.
+ */
+export function buildPromptWithAttachments(
+  prompt: string,
+  attachments: readonly IDraftAttachment[],
+): string {
+  if (attachments.length === 0) return prompt;
+  const refs = attachments.map((attachment) => `@./${attachment.relativePath}`).join(' ');
+  return prompt ? `${prompt}\n\n${refs}` : refs;
+}

package/src/components/personal-usage-dashboard-types.ts

@@ -0,0 +1,26 @@
+import type { IWsSessionState } from '../hooks/useSessionClient.js';
+
+export type TUsageBreakdown = 'model' | 'provider' | 'surface' | 'source' | 'activity';
+
+export type TPersonalUsageDashboardState = Pick<
+  IWsSessionState,
+  | 'personalUsageStatus'
+  | 'personalUsageReport'
+  | 'personalUsageError'
+  | 'requestPersonalUsage'
+  | 'storedSessionUsageStatus'
+  | 'storedSessionUsageReport'
+  | 'storedSessionUsageSessionId'
+  | 'storedSessionUsageError'
+  | 'requestStoredSessionUsage'
+  | 'currentSessionUsageStatus'
+  | 'currentSessionUsageReport'
+  | 'requestCurrentSessionUsage'
+  // The dashboard names a session from this workspace's own local listing (see `sessionTitle()` in
+  // `SessionSidebar.tsx`) instead of any content carried in the report itself.
+  | 'sessionListing'
+>;
+
+export type TPersonalUsageReport = NonNullable<TPersonalUsageDashboardState['personalUsageReport']>;
+
+export type TPersonalUsageDimension = TPersonalUsageReport['byModel'][number];

package/src/driver-labels.ts

@@ -0,0 +1,88 @@
+/**
+ * #3289 §3 — plain, human labels for a REMOTE-014 E5 driver id, and whether one names the SAME KIND
+ * of surface as this connection's own. Shared by every place the GUI shows who drove a turn (a
+ * message, a permission/ask prompt): the person's own input never carries a label, and a turn from a
+ * different kind of surface does — in words, never a raw id.
+ *
+ * The server hands every WebSocket connection of one `--serve` process the SAME driver id (there is
+ * no per-connection id), so two browser tabs of one local page cannot be told apart — and are the
+ * same person anyway. A label therefore names the KIND of surface a turn came from (terminal, desktop
+ * app, browser, remote device), not a specific window, and is shown only when that kind differs from
+ * this window's own.
+ */
+
+import { AGENT_DRIVER_ID, OWNER_DRIVER_ID } from '@robota-sdk/agent-interface-session';
+
+import type { TDriverId } from '@robota-sdk/agent-interface-session';
+
+/**
+ * `remote` (a plain WS remote connection's own id, `'remote:ws'`) and `peer` (an unrelated REMOTE-014
+ * mesh peer's turn, `'peer:<sessionId>'`) are kept as DIFFERENT kinds even though both render the same
+ * label text: a plain WS viewer's own id is `'remote:ws'`, and folding a peer's turn into that same
+ * kind would make `isSameSurface` treat a co-driver's turn as this connection's own and hide it — the
+ * exact class of bug this module exists to prevent.
+ */
+type TSurfaceKind = 'terminal' | 'desktop-app' | 'browser' | 'remote' | 'peer';
+
+/**
+ * The kind of surface a driver id names. `null` for an id this function does not recognize — it still
+ * gets a label (see `humanDriverLabel`), just not one claimed to match anything else's kind.
+ */
+function surfaceKindOf(driverId: TDriverId): TSurfaceKind | null {
+  if (driverId.startsWith('attach:')) return 'terminal';
+  if (driverId === 'app') return 'desktop-app';
+  if (driverId === 'browser') return 'browser';
+  if (driverId === 'remote:ws') return 'remote';
+  if (driverId.startsWith('peer:')) return 'peer';
+  return null;
+}
+
+/**
+ * True when `driverId` names the reserved local-operator id, or a surface of the SAME KIND as this
+ * connection's own (once learned) — so this window never labels its own kind of turn as a co-driver's.
+ * The agent's own wake-ups (`AGENT_DRIVER_ID`) are never "the same surface": automatic is always
+ * labelled, even though no human window could ever learn that as its own id.
+ */
+export function isSameSurface(driverId: TDriverId, ownDriverId: TDriverId | null): boolean {
+  if (driverId === OWNER_DRIVER_ID) return true;
+  if (driverId === AGENT_DRIVER_ID) return false;
+  if (ownDriverId === null) return false;
+  if (driverId === ownDriverId) return true;
+  const kind = surfaceKindOf(driverId);
+  return kind !== null && kind === surfaceKindOf(ownDriverId);
+}
+
+/**
+ * A plain noun phrase for the kind of surface that drove a turn which was not this connection's own.
+ * Never returns a raw id: an id this function does not recognize still gets the least presumptuous
+ * label ("another surface") rather than being echoed back.
+ */
+export function humanDriverLabel(driverId: TDriverId): string {
+  const kind = surfaceKindOf(driverId);
+  switch (kind) {
+    case 'terminal':
+      return 'the terminal';
+    case 'desktop-app':
+      return 'the desktop app';
+    case 'browser':
+      return 'the browser';
+    case 'remote':
+    case 'peer':
+      return 'a remote device';
+    default:
+      return 'another surface';
+  }
+}
+
+/**
+ * The ready-to-render attribution phrase: "from <label>" for a co-driver, or "Automatic — loop"
+ * for the agent's own wake-ups — "from automatic" reads as a typo, not a source. #3288 §1: every
+ * `AGENT_DRIVER_ID` turn is, today, a loop's own injected iteration (fixed or self-paced —
+ * `requestWakeup` in `interactive-session.ts` is the one place that stamps this id); if a
+ * differently-sourced agent-wakeup turn is ever added, this label needs to name that source
+ * instead of assuming "loop".
+ */
+export function driverAttributionText(driverId: TDriverId): string {
+  if (driverId === AGENT_DRIVER_ID) return 'Automatic — loop';
+  return `from ${humanDriverLabel(driverId)}`;
+}

package/src/execution-entry-status.ts

@@ -0,0 +1,55 @@
+/**
+ * #3288 §1: one true-status label for an execution-workspace entry, shared by the Agents panel row
+ * and its detail sheet so the two never say something different about the same entry.
+ *
+ * A completed task whose result still reports a refused tool call is not "Done" — it is "Needs
+ * permission" (retrospective: the run is over, but something in it was refused). That is distinct
+ * from `attention === 'permission'`, which means a turn is PARKED waiting for an answer right now
+ * ("Needs you").
+ */
+import type {
+  IExecutionWorkspaceEntry,
+  TExecutionAttention,
+  TExecutionWorkspaceStatus,
+} from '@robota-sdk/agent-interface-execution';
+
+export type TExecutionStatusTone = 'warning' | 'destructive' | 'success' | 'muted';
+
+export interface IExecutionStatusLabel {
+  readonly label: string;
+  readonly tone: TExecutionStatusTone;
+}
+
+export function hadDeniedToolCalls(
+  status: TExecutionWorkspaceStatus,
+  deniedToolCalls: number | undefined,
+): boolean {
+  return status === 'completed' && (deniedToolCalls ?? 0) > 0;
+}
+
+export function describeExecutionEntryStatus(
+  entry: Pick<IExecutionWorkspaceEntry, 'status' | 'attention' | 'deniedToolCalls'>,
+): IExecutionStatusLabel | null {
+  return describeExecutionStatus(entry.status, entry.attention, entry.deniedToolCalls);
+}
+
+export function describeExecutionStatus(
+  status: TExecutionWorkspaceStatus,
+  attention: TExecutionAttention,
+  deniedToolCalls: number | undefined,
+): IExecutionStatusLabel | null {
+  if (attention === 'permission' || status === 'waiting_permission') {
+    return { label: 'Needs you', tone: 'warning' };
+  }
+  if (attention === 'failed' || status === 'failed') {
+    return { label: 'Failed', tone: 'destructive' };
+  }
+  if (hadDeniedToolCalls(status, deniedToolCalls)) {
+    return { label: 'Needs permission', tone: 'warning' };
+  }
+  if (status === 'completed') return { label: 'Done', tone: 'muted' };
+  if (status === 'cancelled') return { label: 'Stopped', tone: 'muted' };
+  if (status === 'queued') return { label: 'Queued', tone: 'muted' };
+  if (status === 'running') return { label: 'Running', tone: 'muted' };
+  return null;
+}

package/src/goal-view.ts

@@ -0,0 +1,19 @@
+/**
+ * #3282 §4 part b-3 — the Agents panel's Goal row: the objective, and its status in plain words.
+ */
+
+import type { IGoalState } from '@robota-sdk/agent-interface-session';
+
+const STOP_REASON_LABELS: Record<NonNullable<IGoalState['stopReason']>, string> = {
+  satisfied: 'Satisfied',
+  'max-iterations': 'Stopped — reached the iteration limit',
+  cancelled: 'Cancelled',
+  'no-progress': 'Stopped — no progress',
+};
+
+/** The goal's status in plain words — never the raw `status`/`stopReason` identifiers. */
+export function describeGoalStatus(goal: IGoalState): string {
+  if (goal.status === 'active') return 'Active';
+  if (goal.status === 'satisfied') return 'Satisfied';
+  return goal.stopReason ? STOP_REASON_LABELS[goal.stopReason] : 'Stopped';
+}

package/src/hooks/command-menu.ts

@@ -0,0 +1,65 @@
+/**
+ * #3186 — what the composer's `/` menu offers for a draft. Pure, so the matching is testable without
+ * rendering: the TUI's autocomplete offers commands and skills the same way.
+ *
+ * #3282 §4e: a command the GUI cannot run at all (`isExcludedCommand`) never appears here — there is
+ * nothing useful for choosing it to do, and typing it by hand is answered separately (see
+ * `excluded-commands.ts`, `useSessionClient.ts`). Commands are listed before skills, each in its own
+ * group, so the menu can head them "Commands" and "Skills".
+ */
+
+import { isExcludedCommand } from './excluded-commands.js';
+
+import type { TCommandCatalog } from './session-client-types.js';
+
+export interface ICommandMenuItem {
+  readonly name: string;
+  readonly description: string;
+  readonly kind: 'command' | 'skill';
+}
+
+/** How many rows the menu shows before it scrolls — a CSS sizing constant, not a data limit. */
+export const COMMAND_MENU_VISIBLE_ROWS = 8;
+
+/** A generous ceiling on total matches, so a huge personal skill folder can never make the menu unusable. */
+const COMMAND_MENU_MAX_MATCHES = 200;
+
+/**
+ * The menu for a draft, or null when no menu applies: the draft is not a bare `/name` being typed
+ * (it has arguments, or does not start with `/`), or nothing matches. Within each group (commands,
+ * then skills), names that start with what was typed come first, then names that merely contain it.
+ */
+export function commandMenuFor(
+  catalog: TCommandCatalog | null,
+  draft: string,
+): readonly ICommandMenuItem[] | null {
+  if (!catalog || !draft.startsWith('/') || /\s/u.test(draft)) return null;
+  const query = draft.slice(1).toLowerCase();
+  const commandItems: ICommandMenuItem[] = catalog.commands
+    .filter((c) => !isExcludedCommand(c))
+    .map((c) => ({ name: c.name, description: c.description, kind: 'command' as const }));
+  const skillItems: ICommandMenuItem[] = catalog.skills
+    .filter((s) => s.userInvocable)
+    .map((s) => ({ name: s.name, description: s.description, kind: 'skill' as const }));
+  const matched = [...matchGroup(commandItems, query), ...matchGroup(skillItems, query)].slice(
+    0,
+    COMMAND_MENU_MAX_MATCHES,
+  );
+  return matched.length > 0 ? matched : null;
+}
+
+/** One group's matches: names starting with the query, then names merely containing it, each alphabetical. */
+function matchGroup(
+  items: readonly ICommandMenuItem[],
+  query: string,
+): readonly ICommandMenuItem[] {
+  const starts = items.filter((i) => i.name.toLowerCase().startsWith(query));
+  const contains = items.filter(
+    (i) => !i.name.toLowerCase().startsWith(query) && i.name.toLowerCase().includes(query),
+  );
+  return [...starts.sort(byName), ...contains.sort(byName)];
+}
+
+function byName(a: ICommandMenuItem, b: ICommandMenuItem): number {
+  return a.name.localeCompare(b.name);
+}

package/src/hooks/excluded-commands.ts

@@ -0,0 +1,52 @@
+/**
+ * #3282 §4e — built-in commands left out of the GUI on purpose (the design decisions in
+ * `packages/agent-gui-web/docs/SPEC.md` group them by reason). The `/` menu never lists one of these
+ * (`command-menu.ts`), and typing one by hand anyway is caught before it reaches the session
+ * (`useSessionClient.ts`'s `send`) and answered with the plain sentence here — never the session's own
+ * refusal, and never the generic "not available on this surface" line CMD-004 uses for a screen this
+ * surface simply has not built yet (see `ui-intent-state.ts`).
+ */
+
+import type { TCommandRunner, TCommandSurface } from '@robota-sdk/agent-interface-command';
+
+/** The minimum a catalog entry needs for the exclusion check below. */
+export interface IExcludableCommandEntry {
+  readonly name: string;
+  readonly runner?: TCommandRunner;
+  readonly surfaces?: readonly TCommandSurface[];
+}
+
+/**
+ * One plain sentence per excluded command, naming what to use instead — never the command's own
+ * name again, never "not available on this surface". `theme`, `keybindings`, `editor` and `shell`
+ * also declare `runner: 'client', surfaces: ['terminal']` server-side (a second, independent way to
+ * reach the same "excluded" answer, checked by {@link isExcludedCommand} below); `statusline`,
+ * `exit` and `devices` do not, and are excluded here only because the GUI has its own, better answer.
+ */
+const EXCLUDED_COMMAND_MESSAGES: ReadonlyMap<string, string> = new Map([
+  ['theme', 'This app follows your system appearance.'],
+  ['keybindings', 'This app uses standard keyboard shortcuts here.'],
+  ['editor', 'Type your message directly in the composer.'],
+  ['statusline', 'The GUI shows session status in its own status row, not a terminal status line.'],
+  ['shell', 'Use the Terminal app for shell commands.'],
+  ['exit', 'Close the window or tab to end this session; delete it from the sidebar to remove it for good.'],
+  ['devices', 'Device pairing is managed from the terminal for now.'],
+]);
+
+/** A terminal-client command with no curated sentence above still gets a plain, honest one. */
+const GENERIC_CLIENT_MESSAGE = 'This command runs in the host terminal.';
+
+/**
+ * Whether a catalog entry is left out of the GUI: named above, or declared `runner: 'client'` for
+ * surfaces that do not include `'gui'` (a client-only command the GUI cannot run itself, whether or
+ * not this file has a curated sentence for it yet).
+ */
+export function isExcludedCommand(entry: IExcludableCommandEntry): boolean {
+  if (EXCLUDED_COMMAND_MESSAGES.has(entry.name)) return true;
+  return entry.runner === 'client' && !(entry.surfaces ?? []).includes('gui');
+}
+
+/** The plain sentence for an excluded command name — a safe generic one when none is curated. */
+export function excludedCommandMessage(name: string): string {
+  return EXCLUDED_COMMAND_MESSAGES.get(name) ?? GENERIC_CLIENT_MESSAGE;
+}

package/src/hooks/prompt-state.ts

@@ -0,0 +1,83 @@
+/**
+ * Pure prompt-state derivation for the web UI (REMOTE-009 Step 4 / REMOTE-007 render+answer).
+ *
+ * The paired browser is the session OWNER (local == remote), so it must render and ANSWER the owner's own
+ * permission/ask prompts. The server carries `permission_request`/`ask_request` (a prompt appears) and
+ * `prompt_resolved` (it was answered — by this or a co-driving surface — and must dismiss). The answer travels
+ * back as `permission-response`/`ask-response`. This module is the pure list-transition + message-builder logic,
+ * consumed by `useWsSession` and shared unchanged by BOTH the WS and RTC session clients (same `TServerMessage`s).
+ */
+
+import type { TActionResponse } from '@robota-sdk/agent-interface-transport';
+import type {
+  IAskRequestEvent,
+  IPermissionRequestEvent,
+  TPermissionResultValue,
+} from '@robota-sdk/agent-interface-session';
+import type { TClientMessage, TServerMessage } from '@robota-sdk/agent-transport';
+
+/** A prompt awaiting the owner's answer, rendered by the UI (built from the server event payloads). */
+export type TPendingPrompt =
+  | ({ readonly kind: 'permission' } & IPermissionRequestEvent)
+  | ({ readonly kind: 'ask' } & IAskRequestEvent);
+
+/**
+ * Fold a server message into the pending-prompt list: append on `permission_request`/`ask_request`, remove on
+ * `prompt_resolved`. Any other message returns the list unchanged (referential-equality preserved). Duplicate
+ * ids are not re-appended (idempotent against a resend).
+ */
+export function applyPromptEvent(
+  prompts: readonly TPendingPrompt[],
+  msg: TServerMessage,
+): readonly TPendingPrompt[] {
+  switch (msg.type) {
+    case 'permission_request': {
+      // REMOTE-014 E5: keep requesterDriverId so the surface can show WHICH driver's turn raised the
+      // prompt. Issue #3288 §1: keep `requester` too, so it can show WHICH background agent did.
+      // #3288 §2: diffLines/diffFile (Edit/Write) and cwd (Shell, only when it differs) are the
+      // server's diff/command preview — carried through unchanged so the prompt can render them
+      // instead of raw args.
+      const { id, toolName, toolArgs, requesterDriverId, requester, diffLines, diffFile, cwd } =
+        msg.event;
+      if (prompts.some((p) => p.id === id)) return prompts;
+      return [
+        ...prompts,
+        {
+          kind: 'permission',
+          id,
+          toolName,
+          toolArgs,
+          ...(requesterDriverId ? { requesterDriverId } : {}),
+          ...(requester ? { requester } : {}),
+          ...(diffLines ? { diffLines, diffFile } : {}),
+          ...(cwd ? { cwd } : {}),
+        },
+      ];
+    }
+    case 'ask_request': {
+      const { id, request, requesterDriverId } = msg.event;
+      if (prompts.some((p) => p.id === id)) return prompts;
+      return [
+        ...prompts,
+        { kind: 'ask', id, request, ...(requesterDriverId ? { requesterDriverId } : {}) },
+      ];
+    }
+    case 'prompt_resolved': {
+      const { id } = msg.event;
+      const next = prompts.filter((p) => p.id !== id);
+      return next.length === prompts.length ? prompts : next;
+    }
+    default:
+      return prompts;
+  }
+}
+
+/** Build the client message that answers a permission prompt. */
+export function permissionResponse(id: string, result: TPermissionResultValue): TClientMessage {
+  return { type: 'permission-response', id, result };
+}
+
+/** Build the client message that answers an ask prompt. */
+export function askResponse(id: string, response: TActionResponse): TClientMessage {
+  return { type: 'ask-response', id, response };
+}