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

package/src/index.ts

@@ -0,0 +1,72 @@
+// @robota-sdk/agent-ui-web — the GUI presentation layer for a agent session.
+// React components + a wire-protocol session reducer + a desktop shell, rendered over the transport-neutral
+// TServerMessage stream. The GUI analog of agent-ui-terminal; consumed by apps/agent-app (desktop) and the
+// browser surface (agent-transport-webrtc-web).
+
+// ── Session reducer (transport-neutral) ─────────────────────
+export { useSessionClient, useWsSession } from './hooks/useSessionClient.js';
+export type {
+  IConversationMessage,
+  ICommandOutputEntry,
+  IToolGroupEntry,
+  TConversationEntry,
+  IActiveTool,
+  ISessionNotice,
+  IWsSessionState,
+  ISessionClientHandle,
+  TMakeSessionClient,
+} from './hooks/useSessionClient.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';
+
+// ── WS session client (loopback / localhost) ────────────────
+export { createWsSessionClient } from './client/ws-session-client.js';
+export type { IWsSessionClientCallbacks, TConnectionStatus } from './client/ws-session-client.js';
+export { resolveClientRuntimeHost } from './client/runtime-host.js';
+export type {
+  IClientRuntimeBridge,
+  IClientRuntimeEnvironment,
+  IClientRuntimeHost,
+  IClientTrustQuestion,
+  TClientRuntimeState,
+  TClientTrustChoice,
+} from './client/runtime-host.js';
+
+// ── Prompt (permission/ask) state ───────────────────────────
+export { applyPromptEvent, permissionResponse, askResponse } from './hooks/prompt-state.js';
+export type { TPendingPrompt } from './hooks/prompt-state.js';
+
+// ── UI-intent (command screen-request) state — CMD-004 Stage D ──
+export { describeUiIntentForGui, guiScreenForUiIntent } from './hooks/ui-intent-state.js';
+
+// ── Presentation components ─────────────────────────────────
+export { ConversationView } from './components/ConversationView.js';
+export { AgentActivityPanel } from './components/AgentActivityPanel.js';
+export { AgentSwitcherSheet } from './components/AgentSwitcherSheet.js';
+export { PermissionPrompt } from './components/PermissionPrompt.js';
+export { PersonalUsageDashboard } from './components/PersonalUsageDashboard.js';
+export type { TPersonalUsageDashboardState } from './components/personal-usage-dashboard-types.js';
+export { SessionSurface, CenteredChrome } from './components/SessionSurface.js';
+export type { IComposerHandle, IPickedFile } from './components/Composer.js';
+export { SessionSidebar } from './components/SessionSidebar.js';
+export { SessionMonitor } from './components/SessionMonitor.js';
+// #3282 §4a: the shared modal-shell primitive (also consumed by #3282 §2's mode-change confirmation
+// and #3289 §1's session-delete confirmation) and the Settings screen it backs.
+export { Dialog, ConfirmDialog } from './components/Dialog.js';
+export type { IDialogProps, IConfirmDialogProps } from './components/Dialog.js';
+export { SettingsScreen } from './components/SettingsScreen.js';
+// #3282 §4e: the Help sheet `/help` opens instead of the terminal-style text list.
+export { HelpSheet } from './components/HelpSheet.js';
+// Pieces of a surface's chrome, not roots: render them inside a `agent-ui` scope.
+export { ProductMark, ProductWordmark } from './components/Brand.js';
+
+export { ProductIdentityProvider, useProductIdentity } from './product-identity.js';
+export type { IWebProductIdentity } from './product-identity.js';

package/src/product-identity.tsx

@@ -0,0 +1,26 @@
+import { createContext, useContext, type ReactNode } from 'react';
+
+/** Only the public identity needed by a browser surface; hosts resolve its values. */
+export interface IWebProductIdentity {
+  readonly identity: { readonly displayName: string; readonly cliName: string };
+  readonly storage: { readonly browserNamespace: string };
+}
+
+const ProductIdentityContext = createContext<IWebProductIdentity | null>(null);
+
+export function ProductIdentityProvider({ value, children }: {
+  readonly value: IWebProductIdentity;
+  readonly children?: ReactNode;
+}): React.ReactElement {
+  if (!value.identity.displayName || !value.identity.cliName || !value.storage.browserNamespace) {
+    throw new Error('A public product identity is required');
+  }
+  // Changing product replaces the subtree so drafts, in-flight requests and session refs cannot cross it.
+  return <ProductIdentityContext.Provider key={value.storage.browserNamespace} value={value}>{children}</ProductIdentityContext.Provider>;
+}
+
+export function useProductIdentity(): IWebProductIdentity {
+  const identity = useContext(ProductIdentityContext);
+  if (identity === null) throw new Error('ProductIdentityProvider is required');
+  return identity;
+}

package/src/schedule-view.ts

@@ -0,0 +1,92 @@
+/**
+ * #3282 §4 part b-3 — plain-words presentation for the Agents panel's "Scheduled" group. Never an
+ * ISO string or a cron expression: a concrete `nextFireAt` is shown in local time as "Today 9:00" /
+ * "Tomorrow 9:00" / a weekday / a date; a handful of common cron shapes are phrased ("Every weekday
+ * at 9:00"); anything else falls back to "Repeats".
+ */
+
+import type {
+  IBackgroundTaskState,
+  TBackgroundTaskStatus,
+} from '@robota-sdk/agent-interface-execution';
+
+type TScheduleTask = IBackgroundTaskState<'scheduled'>;
+
+const WEEKDAY_NAMES = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
+
+function formatClock(date: Date): string {
+  return date.toLocaleTimeString('en-US', { hour: 'numeric', minute: '2-digit' });
+}
+
+function isSameLocalDay(a: Date, b: Date): boolean {
+  return (
+    a.getFullYear() === b.getFullYear() &&
+    a.getMonth() === b.getMonth() &&
+    a.getDate() === b.getDate()
+  );
+}
+
+/** A concrete fire time, in plain local words — never the raw ISO string. */
+export function formatPlainLocalTime(iso: string, now: Date = new Date()): string {
+  const when = new Date(iso);
+  if (Number.isNaN(when.getTime())) return 'Unknown';
+  const clock = formatClock(when);
+  if (isSameLocalDay(when, now)) return `Today ${clock}`;
+  const tomorrow = new Date(now);
+  tomorrow.setDate(now.getDate() + 1);
+  if (isSameLocalDay(when, tomorrow)) return `Tomorrow ${clock}`;
+  const sixDaysOut = new Date(now);
+  sixDaysOut.setDate(now.getDate() + 6);
+  if (when.getTime() > now.getTime() && when.getTime() <= sixDaysOut.getTime()) {
+    return `${WEEKDAY_NAMES[when.getDay()]} ${clock}`;
+  }
+  const date = when.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });
+  return `${date} ${clock}`;
+}
+
+/** A handful of common 5-field cron shapes phrased plainly; anything else is `undefined`. */
+function describeCronPlainly(cronExpression: string): string | undefined {
+  const fields = cronExpression.trim().split(/\s+/);
+  if (fields.length !== 5) return undefined;
+  const [minute, hour, dayOfMonth, month, dayOfWeek] = fields;
+  if (dayOfMonth !== '*' || month !== '*') return undefined;
+  if (!/^\d{1,2}$/.test(minute!) || !/^\d{1,2}$/.test(hour!)) return undefined;
+  const clock = `${hour!.padStart(2, '0')}:${minute!.padStart(2, '0')}`;
+  if (dayOfWeek === '*') return `Every day at ${clock}`;
+  if (dayOfWeek === '1-5') return `Every weekday at ${clock}`;
+  if (dayOfWeek === '0,6' || dayOfWeek === '6,0') return `Every weekend at ${clock}`;
+  if (/^\d$/.test(dayOfWeek!)) {
+    const name = WEEKDAY_NAMES[Number(dayOfWeek)];
+    return name ? `Every ${name} at ${clock}` : undefined;
+  }
+  return undefined;
+}
+
+/** "When it runs next" — the Scheduled row's own line, in plain local time (never raw wire data). */
+export function describeScheduleTiming(task: TScheduleTask, now: Date = new Date()): string {
+  if (task.nextFireAt) return formatPlainLocalTime(task.nextFireAt, now);
+  const cronExpression = task.schedule?.cronExpression;
+  if (!cronExpression) return '—';
+  return describeCronPlainly(cronExpression) ?? 'Repeats';
+}
+
+/** What a schedule runs — its one-line instruction, never the raw label/id. */
+export function describeScheduleInstruction(task: TScheduleTask): string {
+  return task.schedule?.agentInstruction ?? task.label;
+}
+
+const STATUS_LABELS: Partial<Record<TBackgroundTaskStatus, string>> = {
+  sleeping: 'Active',
+  paused: 'Paused',
+  running: 'Running',
+  queued: 'Queued',
+  cancelled: 'Deleted',
+  failed: 'Failed',
+  completed: 'Done',
+  waiting_permission: 'Needs you',
+};
+
+/** The schedule's status in plain words. */
+export function describeScheduleStatus(task: TScheduleTask): string {
+  return STATUS_LABELS[task.status] ?? task.status;
+}

package/src/styles/surface.css

@@ -0,0 +1,231 @@
+/*
+ * The GUI surface's design (agent-ui-web), scoped to `.agent-ui`: a calm desktop-app surface where the
+ * conversation is the product. Readable sizes, one humanist family (Pretendard, bundled — a page's CSP may
+ * load fonts only from itself), monospace kept for code and paths, and a neutral palette with one accent.
+ *
+ * Every root component of the surface carries `agent-ui`, so its tokens apply inside it and nowhere else:
+ * a host with tokens of its own under the same names keeps them. The host owns the Tailwind entry
+ * (`@import 'tailwindcss'` + `@source '…/agent-ui-web/src'`) and `@import`s this file there, so Tailwind
+ * maps the tokens below onto utilities. A page that is the surface imports `theme.css` instead.
+ */
+@import 'pretendard/dist/web/variable/pretendardvariable-dynamic-subset.css';
+
+/* Map the design tokens (CSS vars below) onto Tailwind color/font utilities (bg-card, text-primary, …). */
+@theme inline {
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-sidebar: var(--sidebar);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-raised: var(--raised);
+  --color-hover: var(--hover);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-subtle: var(--subtle);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-warning: var(--warning);
+  --color-success: var(--success);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+  --font-mono: var(--font-mono);
+  --font-sans: var(--font-sans);
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+}
+
+/*
+ * Paper (light) and graphite (dark), one token each: `light-dark()` picks by `color-scheme`, which follows
+ * the system unless the host pins `data-theme` on the scope or above it. Text colours keep WCAG AA (4.5:1)
+ * on every surface they sit on.
+ */
+.agent-ui {
+  color-scheme: light dark;
+  --radius: 0.75rem;
+
+  --background: light-dark(#ffffff, #1a1a1c); /* conversation canvas */
+  --foreground: light-dark(#1c1c1e, #ededee);
+  --sidebar: light-dark(#f7f7f5, #141416); /* the quieter frame around it */
+  --card: light-dark(
+    #f4f4f2,
+    #242427
+  ); /* cards, menus, the composer — one tonal step, no outline */
+  --card-foreground: light-dark(#1c1c1e, #ededee);
+  --raised: light-dark(#ececea, #2c2c30); /* user bubble, selected row, pressed chips */
+  --hover: light-dark(#e8e8e5, #303035);
+  --popover: light-dark(#ffffff, #232326);
+  --popover-foreground: light-dark(#1c1c1e, #ededee);
+  --primary: light-dark(#1c1c1e, #f2f2f3); /* the send button and primary actions: ink on paper */
+  --primary-foreground: light-dark(#ffffff, #151517);
+  --secondary: light-dark(#f1f1ef, #29292d);
+  --secondary-foreground: light-dark(#1c1c1e, #ededee);
+  --muted: light-dark(#f4f4f2, #232326);
+  --muted-foreground: light-dark(#55555c, #a8a8af); /* secondary text */
+  --subtle: light-dark(#68686f, #8e8e97); /* tertiary text: still >= 4.5:1 on every surface */
+  --accent: light-dark(#0a7a55, #5fd4a8); /* agent's mark, live state — sparingly */
+  --accent-foreground: light-dark(#ffffff, #0b1a14);
+  --destructive: light-dark(#c42f40, #f2727f);
+  --warning: light-dark(#8f5a0b, #f0b35b);
+  --success: light-dark(#0a7a55, #5fd4a8);
+  --border: light-dark(rgb(0 0 0 / 0.08), rgb(255 255 255 / 0.08));
+  --input: light-dark(rgb(0 0 0 / 0.12), rgb(255 255 255 / 0.1));
+  --ring: light-dark(rgb(10 122 85 / 0.4), rgb(95 212 168 / 0.45));
+
+  --font-sans:
+    'Pretendard Variable', Pretendard, -apple-system, BlinkMacSystemFont, 'Apple SD Gothic Neo',
+    'Segoe UI', 'Noto Sans KR', sans-serif;
+  --font-mono:
+    'SF Mono', ui-monospace, 'Cascadia Code', 'JetBrains Mono', Menlo, Consolas, monospace;
+}
+.agent-ui[data-theme='light'],
+[data-theme='light'] .agent-ui {
+  color-scheme: light;
+}
+.agent-ui[data-theme='dark'],
+[data-theme='dark'] .agent-ui {
+  color-scheme: dark;
+}
+
+@layer base {
+  /*
+   * The surface's type, set where it renders and never on the root element: on a page that is only
+   * the surface (`<html class="agent-ui">`) it goes on the body, so `1rem` stays the browser's and the
+   * rem-based spacing keeps its size. In the base layer, so a utility class on a root still wins.
+   */
+  .agent-ui:not(:root),
+  :root.agent-ui > body {
+    color: var(--foreground);
+    font-family: var(--font-sans);
+    font-size: 15px;
+    line-height: 1.6;
+    letter-spacing: -0.005em;
+    font-feature-settings:
+      'ss06' 1,
+      'tnum' 0;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+  }
+
+  .agent-ui,
+  .agent-ui *,
+  .agent-ui ::before,
+  .agent-ui ::after {
+    border-color: var(--border);
+  }
+
+  .agent-ui ::selection {
+    background: color-mix(in oklab, var(--accent) 32%, transparent);
+  }
+
+  .agent-ui ::placeholder {
+    color: var(--subtle);
+  }
+
+  .agent-ui button {
+    cursor: pointer;
+  }
+  .agent-ui button:disabled {
+    cursor: default;
+  }
+
+  .agent-ui :focus-visible {
+    outline: 2px solid var(--ring);
+    outline-offset: 2px;
+  }
+}
+
+/* The live dot: a soft halo, not a glow. */
+.status-glow {
+  box-shadow: 0 0 0 3px color-mix(in oklab, var(--accent) 22%, transparent);
+}
+
+/* Entrances. */
+@keyframes gui-rise {
+  from {
+    opacity: 0;
+    transform: translateY(6px);
+  }
+  to {
+    opacity: 1;
+    transform: none;
+  }
+}
+.gui-rise {
+  animation: gui-rise 0.36s cubic-bezier(0.2, 0.7, 0.2, 1) both;
+}
+
+/* Work in progress reads as a sweep of light across the label. */
+@keyframes gui-shimmer {
+  from {
+    background-position: 150% 0;
+  }
+  to {
+    background-position: -50% 0;
+  }
+}
+.gui-shimmer {
+  background-image: linear-gradient(
+    100deg,
+    var(--muted-foreground) 30%,
+    var(--foreground) 50%,
+    var(--muted-foreground) 70%
+  );
+  background-size: 250% 100%;
+  -webkit-background-clip: text;
+  background-clip: text;
+  color: transparent;
+  animation: gui-shimmer 2.2s linear infinite;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .gui-rise,
+  .gui-shimmer,
+  .agent-ui .animate-pulse,
+  .agent-ui .animate-spin,
+  .agent-ui .animate-ping {
+    animation: none;
+  }
+  .gui-shimmer {
+    color: var(--muted-foreground);
+  }
+}
+
+/* Agent prose: comfortable measure and rhythm for long answers. In the components layer, so the
+   utilities on its children (a heading's larger top margin) still win. */
+@layer components {
+  .gui-prose {
+    font-size: 15px;
+    line-height: 1.7;
+    color: var(--foreground);
+    overflow-wrap: anywhere;
+  }
+  .gui-prose > * + * {
+    margin-top: 0.75em;
+  }
+}
+
+/*
+ * A code block's own horizontal scrollbar (#3289 §2) stays visible rather than only-on-hover like the
+ * rest of the page (`theme.css`'s quiet overlay scrollbar) — a long unwrapped line needs a standing
+ * signal that there is more of it, not one that only appears once the person already found the edge.
+ * `.gui-code-scroll::-webkit-scrollbar-thumb` outranks that page-wide bare `::-webkit-scrollbar-thumb`
+ * rule on specificity alone, so it wins regardless of which stylesheet loads first.
+ */
+.gui-code-scroll {
+  scrollbar-width: thin;
+  scrollbar-color: color-mix(in oklab, var(--foreground) 28%, transparent) transparent;
+}
+.gui-code-scroll::-webkit-scrollbar-thumb {
+  background-color: color-mix(in oklab, var(--foreground) 28%, transparent);
+}

package/src/styles/surface.css.d.mts

@@ -0,0 +1 @@
+export {};

package/src/styles/theme.css

@@ -0,0 +1,38 @@
+/*
+ * The GUI as a whole page (the GUI web app, and the desktop app and `agent --serve --open` that load its
+ * build): the surface's design from `surface.css`, plus what only a page that is the surface owns — its
+ * height, its background and its scrollbars. The page puts `agent-ui` on its `<html>`, so the tokens
+ * reach the body too.
+ */
+@import './surface.css';
+
+@layer base {
+  html,
+  body,
+  #root {
+    height: 100%;
+    margin: 0;
+  }
+
+  body {
+    background: var(--background);
+  }
+}
+
+/* Quiet overlay scrollbars. */
+::-webkit-scrollbar {
+  width: 10px;
+  height: 10px;
+}
+::-webkit-scrollbar-track {
+  background: transparent;
+}
+::-webkit-scrollbar-thumb {
+  background: transparent;
+  border-radius: 999px;
+  border: 3px solid transparent;
+  background-clip: padding-box;
+}
+:hover::-webkit-scrollbar-thumb {
+  background-color: color-mix(in oklab, var(--foreground) 16%, transparent);
+}

package/src/styles/theme.css.d.mts

@@ -0,0 +1 @@
+export {};