@talgent/workbench-ui 0.0.0 → 0.2.0

package/components/preview/file-preview.tsx

@@ -0,0 +1,153 @@
+import { Alert, Button, Spinner } from "@heroui/react";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { Download } from "lucide-react";
+import { useEffect, useRef, useState, type ReactNode } from "react";
+import { fileExtension, textFormat } from "./file-format";
+import { decodeUtf8Prefix, formatBytes, refusalText, type PreviewVerdict } from "./preview-verdict";
+import { SourcePreview, TextPreview } from "./text-preview";
+
+type Shown = { text: string; blob: null } | { text: null; blob: Blob };
+
+// While a Preview Copy is made the verdict is asked again this often.
+const renderingPollMs = 2000;
+
+// Workbooks render as printed pages, which may leave cells out.
+const workbookExtensions = new Set(["xlsx", "xls", "ods"]);
+
+/**
+ * One file shown as Storage's verdict says: directly, truncated, as its
+ * Preview Copy, or refused with its reason and the original to download.
+ * A file needing a Preview Copy asks for it on opening, then polls until it
+ * shows; closing or switching files stops polling, and a late answer never
+ * replaces the current file's. `verdictKey` identifies the file's current
+ * content; a new key asks again. `requestRender` is absent where no Preview
+ * Copy can be made.
+ */
+export function FilePreview({ name, verdictKey, loadVerdict, requestRender, toolbar, onDownload }: {
+  name: string;
+  verdictKey: readonly unknown[];
+  loadVerdict: (signal: AbortSignal) => Promise<PreviewVerdict>;
+  requestRender?: () => Promise<PreviewVerdict>;
+  toolbar: HTMLElement | null;
+  onDownload: () => void;
+}) {
+  const queryClient = useQueryClient();
+  const queryKey = ["file-preview-verdict", ...verdictKey];
+  const verdict = useQuery({
+    queryKey,
+    queryFn: ({ signal }) => loadVerdict(signal),
+    retry: false, gcTime: 0, refetchOnWindowFocus: false,
+    refetchInterval: query => query.state.data?.mode === "render" && query.state.data.rendering ? renderingPollMs : false,
+  });
+  const render = useMutation({
+    mutationFn: async () => {
+      if (!requestRender) throw new Error("No Preview Copy can be made here.");
+      return requestRender();
+    },
+  });
+  const ask = () => render.mutate(undefined, {
+    // Per-call callbacks never run after unmount, so a late answer is dropped.
+    onSuccess: answer => queryClient.setQueryData(queryKey, answer),
+  });
+  const firstAsk = verdict.data?.mode === "render" && !verdict.data.rendering && Boolean(requestRender) && render.isIdle;
+  useEffect(() => {
+    // The first opening asks once; after that only Retry asks again.
+    if (firstAsk) ask();
+    // ask is rebuilt each render; firstAsk alone decides when to call it.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [firstAsk]);
+  const readable = verdict.data && (verdict.data.mode === "direct" || verdict.data.mode === "truncated" || verdict.data.mode === "preview_copy") && verdict.data.url;
+  const shown = useQuery({
+    // The link reads once and expires, so its URL identifies this read.
+    queryKey: ["file-preview-content", verdict.data?.url],
+    enabled: Boolean(readable),
+    queryFn: ({ signal }) => readShown(verdict.data!, signal),
+    retry: false, gcTime: 0, staleTime: Infinity, refetchOnWindowFocus: false,
+  });
+  // A failed read is retried with a new link from a new verdict.
+  const retry = () => void verdict.refetch();
+
+  if (verdict.isPending) return <p className="sr-only" role="status">Loading preview…</p>;
+  if (verdict.isError) return <PreviewAlert status="danger" message="Could not load the preview." action={<Button size="sm" variant="secondary" onPress={retry}>Retry preview</Button>} />;
+  const { data } = verdict;
+  if (data.mode === "refused") {
+    return <PreviewAlert status="default" message={refusalText(data)} action={<DownloadOriginal onDownload={onDownload} />} />;
+  }
+  if (data.mode === "render") {
+    if (!requestRender) return <PreviewAlert status="default" message="Preview isn't available for this kind of file." action={<DownloadOriginal onDownload={onDownload} />} />;
+    if (data.rendering || render.isPending || render.isIdle) {
+      return <PreviewAlert status="default" indicator={<Spinner size="sm" />} message="Generating preview… It appears here when ready." action={<DownloadOriginal onDownload={onDownload} />} />;
+    }
+    // The rendering ended without a copy: a temporary failure, or the request failed.
+    return <PreviewAlert status="default" message="Preview isn't available right now."
+      action={<div className="pv-actions"><Button size="sm" variant="secondary" onPress={ask}>Retry</Button><DownloadOriginal onDownload={onDownload} /></div>} />;
+  }
+  return <div className="pr-file-document">
+    {shown.isPending && <p className="sr-only" role="status">Loading preview…</p>}
+    {shown.isError && <PreviewAlert status="danger" message="Could not load this file." action={<Button size="sm" variant="secondary" onPress={retry}>Retry preview</Button>} />}
+    {data.mode === "truncated" && <TruncationNotice name={name} verdict={data} />}
+    {data.mode === "preview_copy" && workbookExtensions.has(fileExtension(name) ?? "") && <PreviewAlert status="default" message="Previewed as printed pages; some cells may not appear. Download the original for the full workbook." />}
+    {shown.data && (shown.data.text !== null
+      ? <ShownText name={name} text={shown.data.text} truncated={data.mode === "truncated"} toolbar={toolbar} />
+      : <BinaryPreview key={shown.dataUpdatedAt} blob={shown.data.blob} name={name} image={data.display === "image"} onRetry={retry} />)}
+  </div>;
+}
+
+async function readShown(verdict: PreviewVerdict, signal: AbortSignal): Promise<Shown> {
+  const truncated = verdict.mode === "truncated";
+  const response = await fetch(verdict.url!, { signal, headers: truncated ? { Range: `bytes=0-${verdict.limitBytes - 1}` } : undefined });
+  if (!response.ok) throw new Error("Could not load this file.");
+  if (verdict.display === "text") {
+    const bytes = new Uint8Array(await response.arrayBuffer());
+    // A server ignoring Range still sends the whole file; show only the start.
+    return { text: decodeUtf8Prefix(truncated ? bytes.subarray(0, verdict.limitBytes) : bytes), blob: null };
+  }
+  // Fetch the authorized bytes before rendering: the content endpoint denies
+  // framing, and a link does not prove the read will succeed.
+  return { text: null, blob: new Blob([await response.blob()], { type: verdict.display === "pdf" ? "application/pdf" : response.headers.get("Content-Type") ?? "" }) };
+}
+
+function isMarkup(name: string) {
+  const kind = textFormat(name).kind;
+  return kind === "html" || kind === "svg";
+}
+
+// Truncated markup is never rendered: its source shows instead.
+function ShownText({ name, text, truncated, toolbar }: { name: string; text: string; truncated: boolean; toolbar: HTMLElement | null }) {
+  return truncated && isMarkup(name) ? <SourcePreview path={name} content={text} /> : <TextPreview path={name} content={text} toolbar={toolbar} />;
+}
+
+function TruncationNotice({ name, verdict }: { name: string; verdict: PreviewVerdict }) {
+  const limit = formatBytes(verdict.limitBytes);
+  const message = isMarkup(name)
+    ? `This file is over ${limit}, too large to render. Showing the source of its first ${limit}.`
+    : `Showing the first ${limit} of this file.`;
+  return <PreviewAlert status="default" message={message} />;
+}
+
+function PreviewAlert({ status, message, action, indicator }: { status: "default" | "danger"; message: string; action?: ReactNode; indicator?: ReactNode }) {
+  return <Alert status={status} className="pv-alert" role={status === "danger" ? "alert" : "status"}>
+    <Alert.Indicator>{indicator}</Alert.Indicator>
+    <Alert.Content><Alert.Description>{message}</Alert.Description></Alert.Content>
+    {action}
+  </Alert>;
+}
+
+function DownloadOriginal({ onDownload }: { onDownload: () => void }) {
+  return <Button size="sm" variant="secondary" onPress={onDownload}><Download size={14} />Download original</Button>;
+}
+
+function BinaryPreview({ blob, name, image, onRetry }: { blob: Blob; name: string; image: boolean; onRetry: () => void }) {
+  const imageElement = useRef<HTMLImageElement>(null);
+  const frameElement = useRef<HTMLIFrameElement>(null);
+  const [failed, setFailed] = useState(false);
+  useEffect(() => {
+    const element = imageElement.current ?? frameElement.current;
+    if (!element) return;
+    const url = URL.createObjectURL(blob);
+    element.src = url;
+    return () => URL.revokeObjectURL(url);
+  }, [blob]);
+  if (failed) return <PreviewAlert status="danger" message="Could not display this file." action={<Button size="sm" variant="secondary" onPress={onRetry}>Retry preview</Button>} />;
+  return image ? <img ref={imageElement} alt={name} onError={() => setFailed(true)} /> : <iframe ref={frameElement} title={name} onError={() => setFailed(true)} />;
+}

package/components/preview/preview-verdict.ts

@@ -0,0 +1,44 @@
+/** How Storage shows a file; the reading area follows it and nothing else. */
+export type PreviewVerdict = {
+  mode: "refused" | "preview_copy" | "render" | "direct" | "truncated";
+  display: "text" | "pdf" | "image" | "none";
+  refusal?: "unsupported" | "structure_mismatch" | "encrypted" | "too_large" | "corrupt" | "converter_refused" | "rendering_too_large";
+  /** Shown length of a truncated file, or the limit a too large file exceeds. */
+  limitBytes: number;
+  /** One inline read of the shown bytes. */
+  url?: string;
+  /** With mode "render": a Preview Copy of the content is queued or being made. */
+  rendering: boolean;
+};
+
+export function formatBytes(bytes: number): string {
+  const mib = bytes / (1 << 20);
+  if (mib >= 1) return `${Number.isInteger(mib) ? mib : mib.toFixed(1)} MiB`;
+  if (bytes >= 1024) return `${Math.round(bytes / 1024)} KiB`;
+  return `${bytes} bytes`;
+}
+
+export function refusalText(verdict: PreviewVerdict): string {
+  switch (verdict.refusal) {
+    case "structure_mismatch": return "The content doesn't match the file type.";
+    case "encrypted": return "This file is encrypted.";
+    case "too_large": return `This file is over ${formatBytes(verdict.limitBytes)}, too large to preview.`;
+    case "corrupt": return "This file is damaged and can't be previewed.";
+    case "converter_refused": return "This file can't be converted for preview.";
+    case "rendering_too_large": return "The preview of this file came out too large to show.";
+    default: return "Preview isn't available for this kind of file.";
+  }
+}
+
+/** Cuts bytes at the last whole UTF-8 character, so a truncated read decodes cleanly. */
+export function decodeUtf8Prefix(bytes: Uint8Array): string {
+  let end = bytes.length;
+  for (let back = 1; back <= 3 && back <= bytes.length; back++) {
+    const byte = bytes[bytes.length - back];
+    if ((byte & 0xc0) === 0x80) continue;
+    const length = byte >= 0xf0 ? 4 : byte >= 0xe0 ? 3 : byte >= 0xc0 ? 2 : 1;
+    if (length > back) end = bytes.length - back;
+    break;
+  }
+  return new TextDecoder().decode(bytes.subarray(0, end));
+}

package/components/preview/preview.css

@@ -0,0 +1,19 @@
+.pv-plain { margin: 0; padding: 12px 14px; border-radius: var(--radius); background: var(--surface-secondary); font-family: var(--font-mono); font-size: 13px; line-height: 1.6; white-space: pre-wrap; overflow-wrap: anywhere; }
+.pv-inline-tools { display: flex; justify-content: flex-end; margin-bottom: 12px; }
+.pv-svg { display: grid; gap: 12px; min-width: 0; }
+.pv-svg > img { display: block; max-width: 100%; max-height: 70vh; width: auto; height: auto; margin-inline: auto; object-fit: contain; }
+/* A previewed Markdown file reads as a document, not a card, with its
+   headings scaled below the reading area's own title. */
+.pv-markdown-document { min-width: 0; max-width: 100%; overflow: auto; }
+.pv-markdown-document h1 { font-size: 24px; }
+.pv-markdown-document h2 { font-size: 17px; margin-top: 28px; }
+.pv-markdown-document h3 { font-size: 15px; }
+.pv-html { position: relative; min-width: 0; }
+.pv-html > iframe { display: block; width: 100%; min-height: 100vh; border: 1px solid var(--separator); border-radius: var(--radius); background: var(--background); }
+.pv-html > .button { position: absolute; top: 8px; right: 8px; }
+.pv-diff { margin: 0; padding-block: 8px; border: 1px solid var(--separator); border-radius: var(--radius); background: var(--background); font-family: var(--font-mono); font-size: 12px; line-height: 20px; white-space: pre-wrap; overflow-wrap: anywhere; }
+.pv-diff > span { display: block; padding-inline: 12px; color: var(--muted); }
+.pv-diff > [data-diff-line="added"] { background: color-mix(in oklab, var(--success) 10%, transparent); color: var(--success); }
+.pv-diff > [data-diff-line="removed"] { background: color-mix(in oklab, var(--danger) 10%, transparent); color: var(--danger); }
+.pv-alert { margin-bottom: 16px; align-items: center; }
+.pv-actions { display: flex; gap: 8px; }

package/components/preview/text-preview.tsx

@@ -0,0 +1,174 @@
+import { Button, Disclosure, ToggleButton, ToggleButtonGroup, Tooltip } from "@heroui/react";
+import { Maximize2 } from "lucide-react";
+import { useEffect, useMemo, useRef, useState } from "react";
+import { createPortal } from "react-dom";
+import { CodeListing, Markdown } from "../markdown";
+import { sourceLanguage, textFormat } from "./file-format";
+import "./preview.css";
+
+/**
+ * Above this many characters a listing is shown unhighlighted: Shiki's
+ * JavaScript engine tokenizes on the main thread and React renders one span
+ * per token, so a large file would freeze the page.
+ */
+export const HIGHLIGHT_LIMIT = 100_000;
+
+const PREVIEW_CSP = "default-src 'none'; img-src data: blob:; style-src 'unsafe-inline'; font-src data:; script-src 'unsafe-inline'; base-uri 'none'; form-action 'none';";
+const PREVIEW_RESIZE_MESSAGE_TYPE = "talgent:artifact-preview:resize";
+const PREVIEW_RESIZE_BRIDGE = `<script>
+(() => {
+  const messageType = "${PREVIEW_RESIZE_MESSAGE_TYPE}";
+  const report = () => {
+    const body = document.body;
+    const root = document.documentElement;
+    const height = Math.max(
+      body?.scrollHeight || 0,
+      body?.offsetHeight || 0,
+      root?.scrollHeight || 0,
+      root?.offsetHeight || 0
+    );
+    if (height > 0) {
+      window.parent.postMessage({ type: messageType, height: Math.ceil(height) }, "*");
+    }
+  };
+  window.addEventListener("load", report);
+  document.addEventListener("DOMContentLoaded", report);
+  try {
+    new ResizeObserver(report).observe(document.documentElement);
+  } catch {
+    window.setInterval(report, 1000);
+  }
+  window.setTimeout(report, 0);
+})();
+</script>`;
+
+/**
+ * Text content shown by its path's extension. `toolbar` is the reading area's
+ * context-action slot, where a Markdown document puts its Rendered/Source switch.
+ */
+export function TextPreview({ content, path, toolbar = null }: { content: string; path?: string; toolbar?: HTMLElement | null }) {
+  const format = textFormat(path);
+  switch (format.kind) {
+    case "markdown": return <MarkdownDocument content={content} toolbar={toolbar} />;
+    case "html": return <HtmlPreview content={content} />;
+    case "svg": return <SvgPreview content={content} name={path} />;
+    case "diff": return <DiffView content={content} />;
+    default: return <CodeView code={content} language={sourceLanguage(format)} />;
+  }
+}
+
+/** Source in the format's highlighting, as a partial read or a refused render shows it. */
+export function SourcePreview({ content, path, startLine }: { content: string; path?: string; startLine?: number }) {
+  return <CodeView code={content} language={sourceLanguage(textFormat(path))} startLine={startLine} />;
+}
+
+/** Numbered, highlighted source; too long to highlight, it falls back to plain text. */
+export function CodeView({ code, language, startLine = 1 }: { code: string; language: string; startLine?: number }) {
+  if (code.length > HIGHLIGHT_LIMIT) return <pre className="pv-plain" tabIndex={0} aria-label="Source">{code}</pre>;
+  return <CodeListing code={code} language={language} startLine={startLine} />;
+}
+
+type MarkdownMode = "rendered" | "source";
+
+// A previewed Markdown file reads as a document, not a card.
+function MarkdownDocument({ content, toolbar }: { content: string; toolbar: HTMLElement | null }) {
+  const [mode, setMode] = useState<MarkdownMode>("rendered");
+  const toggle = (
+    <ToggleButtonGroup aria-label="Markdown view" size="sm" selectionMode="single" disallowEmptySelection
+      selectedKeys={[mode]} onSelectionChange={keys => { const [next] = keys; if (next) setMode(next as MarkdownMode); }}>
+      <ToggleButton id="rendered">Rendered</ToggleButton>
+      <ToggleButton id="source"><ToggleButtonGroup.Separator />Source</ToggleButton>
+    </ToggleButtonGroup>
+  );
+  return <>
+    {toolbar ? createPortal(toggle, toolbar) : <div className="pv-inline-tools">{toggle}</div>}
+    {mode === "rendered"
+      ? <div className="pv-markdown-document"><Markdown>{content}</Markdown></div>
+      : <CodeView code={content} language="markdown" />}
+  </>;
+}
+
+/** An SVG shows as an image at its own proportions: as an image it runs no script and loads nothing. */
+function SvgPreview({ content, name }: { content: string; name?: string }) {
+  const src = useMemo(() => `data:image/svg+xml;charset=utf-8,${encodeURIComponent(content)}`, [content]);
+  return <div className="pv-svg">
+    <img src={src} alt={name ?? "SVG image"} />
+    <Disclosure>
+      <Disclosure.Heading>
+        <Button slot="trigger" size="sm" variant="ghost">View source<Disclosure.Indicator /></Button>
+      </Disclosure.Heading>
+      <Disclosure.Content><Disclosure.Body><CodeView code={content} language="xml" /></Disclosure.Body></Disclosure.Content>
+    </Disclosure>
+  </div>;
+}
+
+// The frame is sandboxed without same-origin, so only its own bridge script
+// can report the document height.
+function HtmlPreview({ content }: { content: string }) {
+  const iframeRef = useRef<HTMLIFrameElement>(null);
+  const [previewHeight, setPreviewHeight] = useState<number | null>(null);
+
+  useEffect(() => {
+    const onMessage = (event: MessageEvent) => {
+      if (event.source !== iframeRef.current?.contentWindow) return;
+      const data = event.data as { type?: unknown; height?: unknown } | null;
+      if (!data || typeof data !== "object" || data.type !== PREVIEW_RESIZE_MESSAGE_TYPE) return;
+      const height = Number(data.height);
+      if (Number.isFinite(height) && height > 0) setPreviewHeight(Math.ceil(height));
+    };
+    window.addEventListener("message", onMessage);
+    return () => window.removeEventListener("message", onMessage);
+  }, []);
+
+  return (
+    <div className="pv-html">
+      <iframe
+        allow="fullscreen"
+        allowFullScreen
+        ref={iframeRef}
+        referrerPolicy="no-referrer"
+        sandbox="allow-scripts"
+        srcDoc={previewDocument(content)}
+        style={previewHeight === null ? undefined : { height: previewHeight }}
+        title="HTML preview"
+      />
+      <Tooltip>
+        <Button isIconOnly size="sm" variant="secondary" aria-label="Open HTML preview fullscreen" onPress={() => void iframeRef.current?.requestFullscreen?.()}>
+          <Maximize2 size={16} />
+        </Button>
+        <Tooltip.Content>Open fullscreen</Tooltip.Content>
+      </Tooltip>
+    </div>
+  );
+}
+
+/** Unified diff lines, added and removed lines marked. */
+export function DiffView({ content }: { content: string }) {
+  return (
+    <pre className="pv-diff">
+      {content.split("\n").map((line, index) => (
+        <span data-diff-line={diffLineType(line)} key={index}>{line || " "}</span>
+      ))}
+    </pre>
+  );
+}
+
+function diffLineType(line: string): "added" | "removed" | "context" {
+  if (line.startsWith("+") && !line.startsWith("+++")) {
+    return "added";
+  }
+  if (line.startsWith("-") && !line.startsWith("---")) {
+    return "removed";
+  }
+  return "context";
+}
+
+function previewDocument(content: string): string {
+  const meta = `<meta http-equiv="Content-Security-Policy" content="${escapeAttribute(PREVIEW_CSP)}">`;
+
+  return `<!doctype html><html><head>${meta}${PREVIEW_RESIZE_BRIDGE}</head><body>${content}</body></html>`;
+}
+
+function escapeAttribute(value: string): string {
+  return value.replace(/&/g, "&amp;").replace(/"/g, "&quot;");
+}

package/components/profile/provider-callback.tsx

@@ -0,0 +1,43 @@
+import { useEffect, useRef } from "react";
+import { useQueryClient } from "@tanstack/react-query";
+import { useLocation, useNavigate } from "react-router-dom";
+import { marketplaceQueryKey } from "../../lib/marketplace-catalog";
+import { completeProviderAuthorization, providerName, takeProviderReturn } from "../../lib/marketplace-connections";
+import { notify } from "../../lib/notifications";
+
+// Completes a Provider authorization returning on the registered callback URL,
+// then returns to the page that started it. The OAuth code is used once.
+export function useProviderAuthorizationCallback() {
+  const handled = useRef(false);
+  const navigate = useNavigate();
+  const cache = useQueryClient();
+  const params = new URLSearchParams(useLocation().search);
+  const code = params.get("code") ?? "", state = params.get("state") ?? "";
+  // The Provider returns `error` instead of a code when the user declines.
+  const declined = Boolean(params.get("error") && state);
+  const pending = Boolean(code && state) || declined;
+  useEffect(() => {
+    if (!pending || handled.current) return;
+    handled.current = true;
+    const provider = "github";
+    const name = providerName(provider);
+    if (declined) {
+      notify(`provider:${provider}`, "warning", `${name} wasn’t connected`, "Authorization was cancelled. You can connect again at any time.");
+      navigate(takeProviderReturn(provider), { replace: true });
+      return;
+    }
+    notify(`provider:${provider}`, "default", `Connecting ${name}…`, undefined, { timeout: 0 });
+    completeProviderAuthorization(provider, code, state).then(({ authorization, returnTo }) => {
+      void cache.invalidateQueries({ queryKey: marketplaceQueryKey });
+      void cache.invalidateQueries({ queryKey: ["work-start-options"] });
+      // A new authorization reaches different repositories.
+      void cache.invalidateQueries({ queryKey: ["work-start-repositories"] });
+      notify(`provider:${provider}`, "success", `${name} connected`, `Signed in as ${authorization.providerLogin}. Works you start from now on can use it.`);
+      navigate(returnTo, { replace: true });
+    }, () => {
+      notify(`provider:${provider}`, "danger", `${name} couldn’t be connected`, "Start connecting again from the Provider page.");
+      navigate(`/marketplace/providers/${provider}`, { replace: true });
+    });
+  }, [pending, declined, code, state, navigate, cache]);
+  return pending;
+}

package/components/profile/work-agent-appearance.tsx

@@ -0,0 +1,109 @@
+import { useState, type FormEvent } from "react";
+import { Alert, Button, Card, FieldError, Input, Label, Skeleton, TextField, ToggleButton, ToggleButtonGroup, type Selection } from "@heroui/react";
+import { Check } from "lucide-react";
+import { AgentIcon } from "../agent/agent-icon";
+import { agentColors, agentGlyphs, type AgentColor } from "../../lib/agent-icon";
+import { agentAppearanceErrorMessage, useChangeMyWorkAgentAppearance, useMyWorkAgent, type MyWorkAgent } from "../../lib/agent-appearance-service";
+
+const MAX_NAME = 40;
+
+// Profile › Your Work Agent: the person names their Work Agent and picks its
+// icon. Every place the Agent appears shows what is saved here.
+export function WorkAgentAppearance() {
+  const agent = useMyWorkAgent();
+  return (
+    <section className="mk-section" aria-labelledby="pf-agent">
+      <h3 id="pf-agent" className="mk-section-title">Your Work Agent</h3>
+      {agent.data ? <AppearanceEditor key={`${agent.data.agentId}:${agent.data.name}:${agent.data.icon.glyph}:${agent.data.icon.color}`} saved={agent.data} />
+        : agent.isError ? (
+          <Alert status="danger">
+            <Alert.Indicator />
+            <Alert.Content>
+              <Alert.Title>Your Work Agent could not be loaded.</Alert.Title>
+              <Alert.Description>Its name and icon stay as they were.</Alert.Description>
+            </Alert.Content>
+            <Button size="sm" variant="secondary" isPending={agent.isFetching} onPress={() => void agent.refetch()}>Retry</Button>
+          </Alert>
+        ) : (
+          <Card className="mk-group" aria-busy="true">
+            <Card.Content className="flex items-center gap-4 p-5">
+              <p className="sr-only" role="status">Loading your Work Agent…</p>
+              <Skeleton className="size-14 rounded-2xl" />
+              <div className="grid flex-1 gap-2"><Skeleton className="h-3 w-16 rounded" /><Skeleton className="h-9 rounded-lg" /></div>
+            </Card.Content>
+          </Card>
+        )}
+    </section>
+  );
+}
+
+function nameProblem(name: string) {
+  if (!name) return "Enter a name.";
+  if (Array.from(name).length > MAX_NAME) return `Use at most ${MAX_NAME} characters.`;
+  return "";
+}
+
+function AppearanceEditor({ saved }: { saved: MyWorkAgent }) {
+  const change = useChangeMyWorkAgentAppearance();
+  const [draft, setDraft] = useState(saved);
+  const name = draft.name.trim();
+  const problem = nameProblem(name);
+  const dirty = name !== saved.name || draft.icon.glyph !== saved.icon.glyph || draft.icon.color !== saved.icon.color;
+  const pick = (part: "glyph" | "color") => (keys: Selection) => {
+    const id = [...keys][0];
+    if (id !== undefined) setDraft(current => ({ ...current, icon: { ...current.icon, [part]: String(id) } }));
+  };
+  const save = (event: FormEvent) => {
+    event.preventDefault();
+    if (!dirty || problem || change.isPending) return;
+    change.mutate({ ...draft, name });
+  };
+  const discard = () => { change.reset(); setDraft(saved); };
+  return (
+    <Card className="mk-group">
+      <form onSubmit={save} aria-label="Your Work Agent">
+        <Card.Content className="grid gap-5 p-5">
+          <div className="flex items-start gap-4">
+            <AgentIcon icon={draft.icon} size={56} />
+            <TextField className="min-w-0 flex-1" value={draft.name} onChange={value => setDraft(current => ({ ...current, name: value }))} isInvalid={Boolean(problem)} isDisabled={change.isPending}>
+              <Label>Name</Label>
+              <Input />
+              <FieldError>{problem}</FieldError>
+            </TextField>
+          </div>
+          <div className="grid gap-2">
+            <span id="pf-agent-glyph" className="text-[13px] font-medium">Icon</span>
+            <ToggleButtonGroup aria-labelledby="pf-agent-glyph" selectionMode="single" disallowEmptySelection isDetached isDisabled={change.isPending} size="sm" className="flex-wrap justify-start"
+              selectedKeys={new Set([draft.icon.glyph])} onSelectionChange={pick("glyph")}>
+              {agentGlyphs.map(({ id, label, Icon }) => <ToggleButton key={id} id={id} isIconOnly aria-label={label} variant="ghost"><Icon size={16} aria-hidden="true" /></ToggleButton>)}
+            </ToggleButtonGroup>
+          </div>
+          <div className="grid gap-2">
+            <span id="pf-agent-color" className="text-[13px] font-medium">Color</span>
+            <ToggleButtonGroup aria-labelledby="pf-agent-color" selectionMode="single" disallowEmptySelection isDetached isDisabled={change.isPending} size="sm" className="flex-wrap justify-start"
+              selectedKeys={new Set([draft.icon.color])} onSelectionChange={pick("color")}>
+              {(Object.keys(agentColors) as AgentColor[]).map(color => (
+                <ToggleButton key={color} id={color} isIconOnly aria-label={color[0].toUpperCase() + color.slice(1)} variant="ghost">
+                  <span aria-hidden="true" className="agent-color-swatch" style={{ background: agentColors[color] }}>{draft.icon.color === color && <Check size={12} strokeWidth={3} />}</span>
+                </ToggleButton>
+              ))}
+            </ToggleButtonGroup>
+          </div>
+          {change.isError && (
+            <Alert status="danger">
+              <Alert.Indicator />
+              <Alert.Content><Alert.Title>{agentAppearanceErrorMessage(change.error)}</Alert.Title></Alert.Content>
+            </Alert>
+          )}
+          <div className="flex flex-wrap items-center justify-between gap-3">
+            <p className="mk-muted min-w-[16rem] flex-1 text-[13px]">Shown wherever your Work Agent appears, including comments it wrote before.</p>
+            <div className="ml-auto flex gap-2">
+              <Button size="sm" variant="ghost" isDisabled={!dirty || change.isPending} onPress={discard}>Discard</Button>
+              <Button size="sm" type="submit" isDisabled={!dirty || Boolean(problem)} isPending={change.isPending}>{change.isPending ? "Saving" : "Save"}</Button>
+            </div>
+          </div>
+        </Card.Content>
+      </form>
+    </Card>
+  );
+}

package/components/profile/work-agent-soul.tsx

@@ -0,0 +1,76 @@
+import { useState, type FormEvent } from "react";
+import { Alert, Button, Card, FieldError, Label, Skeleton, TextArea, TextField, Tooltip } from "@heroui/react";
+import { Info } from "lucide-react";
+import { useMyWorkAgent } from "../../lib/agent-appearance-service";
+import { MAX_SOUL, soulErrorMessage, useChangeWorkAgentSoul, useWorkAgentSoul } from "../../lib/agent-soul-service";
+
+// Profile › Soul: the persona and working style of the person's own Work Agent.
+// When it applies lives in the tooltip beside the title. A Work Agent that
+// cannot be loaded is reported once, by Your Work Agent.
+export function WorkAgentSoul() {
+  const agent = useMyWorkAgent();
+  const soul = useWorkAgentSoul(agent.data?.agentId);
+  if (agent.isError) return null;
+  return (
+    <section className="mk-section" aria-labelledby="pf-soul">
+      <div className="flex items-center gap-2">
+        <h3 id="pf-soul" className="mk-section-title">Soul</h3>
+        <Tooltip delay={200}>
+          <Tooltip.Trigger aria-label="About Soul" className="rounded-full text-muted"><Info size={15} aria-hidden="true" /></Tooltip.Trigger>
+          <Tooltip.Content>Every Work of your Work Agent takes it up at its next start. Running work is not interrupted, and platform rules and the agreements a Work follows still come first.</Tooltip.Content>
+        </Tooltip>
+      </div>
+      {soul.data !== undefined && agent.data ? <SoulEditor key={`${agent.data.agentId}:${soul.data}`} agentId={agent.data.agentId} saved={soul.data} />
+        : soul.isError ? (
+          <Alert status="danger">
+            <Alert.Indicator />
+            <Alert.Content><Alert.Title>Your Work Agent's Soul could not be loaded.</Alert.Title></Alert.Content>
+            <Button size="sm" variant="secondary" isPending={soul.isFetching} onPress={() => void soul.refetch()}>Retry</Button>
+          </Alert>
+        ) : (
+          <Card className="mk-group" aria-busy="true">
+            <Card.Content className="grid gap-3 p-5">
+              <p className="sr-only" role="status">Loading your Work Agent's Soul…</p>
+              <Skeleton className="h-24 rounded-lg" />
+            </Card.Content>
+          </Card>
+        )}
+    </section>
+  );
+}
+
+function SoulEditor({ agentId, saved }: { agentId: string; saved: string }) {
+  const change = useChangeWorkAgentSoul();
+  const [draft, setDraft] = useState(saved);
+  const soul = draft.trim();
+  const problem = Array.from(soul).length > MAX_SOUL ? `Use at most ${MAX_SOUL} characters.` : "";
+  const dirty = soul !== saved;
+  const save = (event: FormEvent) => {
+    event.preventDefault();
+    if (!dirty || problem || change.isPending) return;
+    change.mutate({ agentId, soul });
+  };
+  return (
+    <Card className="mk-group">
+      <form onSubmit={save} aria-label="Soul">
+        <Card.Content className="grid gap-4 p-5">
+          <TextField value={draft} onChange={setDraft} isInvalid={Boolean(problem)} isDisabled={change.isPending}>
+            <Label className="sr-only">Soul</Label>
+            <TextArea rows={5} placeholder="How your Work Agent should talk and work" />
+            <FieldError>{problem}</FieldError>
+          </TextField>
+          {change.isError && (
+            <Alert status="danger">
+              <Alert.Indicator />
+              <Alert.Content><Alert.Title>{soulErrorMessage(change.error)}</Alert.Title></Alert.Content>
+            </Alert>
+          )}
+          <div className="flex justify-end gap-2">
+            <Button size="sm" variant="ghost" isDisabled={!dirty || change.isPending} onPress={() => { change.reset(); setDraft(saved); }}>Discard</Button>
+            <Button size="sm" type="submit" isDisabled={!dirty || Boolean(problem)} isPending={change.isPending}>{change.isPending ? "Saving" : "Save"}</Button>
+          </div>
+        </Card.Content>
+      </form>
+    </Card>
+  );
+}

package/components/rail/rail-section.tsx

@@ -0,0 +1,20 @@
+import { useId, useState, type ReactNode } from "react";
+import { Button } from "@heroui/react";
+import { ChevronRight } from "lucide-react";
+import "./rail.css";
+
+// One collapsible section of a context rail: a heading that toggles it, an
+// optional summary that stays readable while it is collapsed, and an optional
+// action beside the heading.
+export function RailSection({ title, summary, children, action, defaultOpen = true, open: controlledOpen, onOpenChange, className = "" }: { title: string; summary?: string; children: ReactNode; action?: ReactNode; defaultOpen?: boolean; open?: boolean; onOpenChange?: (open: boolean) => void; className?: string }) {
+  const [localOpen, setLocalOpen] = useState(defaultOpen);
+  const open = controlledOpen ?? localOpen;
+  const setOpen = onOpenChange ?? setLocalOpen;
+  const contentId = useId();
+  return <section className={`cr-section ${className}`} aria-label={title}>
+    <div className="cr-heading"><h3><Button variant="ghost" className="cr-section-trigger" aria-label={title} aria-describedby={summary ? `${contentId}-summary` : undefined} aria-expanded={open} aria-controls={contentId} onPress={() => setOpen(!open)}>
+      <span>{title}</span>{summary && <span id={`${contentId}-summary`} className="cr-summary">{summary}</span>}<ChevronRight size={14} className="cr-expand" aria-hidden="true" />
+    </Button></h3>{action}</div>
+    <div id={contentId} hidden={!open}>{children}</div>
+  </section>;
+}