@talgent/workbench-ui 0.0.0 → 0.1.2

package/components/work-start/work-start-tray.tsx

@@ -0,0 +1,128 @@
+import { useState, type ReactNode } from "react";
+import { Button, Checkbox, Description, Label, ListBox, Popover, SearchField, Switch } from "@heroui/react";
+import type { WorkStartRepository } from "@talgent/workbench-contracts/agent/public/v1/work_start_options_pb";
+import { AlertTriangle, Bot, Cloud, GitBranch, Server, Shield } from "lucide-react";
+import type { UsableComputer } from "../../lib/computer-service";
+import { permissionModeOption } from "../../lib/permission-modes";
+import type { WorkStartInput } from "../../lib/start-work-request";
+import { providerName, useConnectProvider, useProviderConnection } from "../../lib/marketplace-connections";
+import type { Capability } from "../../lib/work-start-loadout";
+import { PermissionModeList } from "../composer/permission-mode-list";
+import { PopoverFootnote } from "../composer/prompt-bar-controls";
+
+/** A tray chip and its card. Every card shares one surface and row anatomy. */
+export function TrayPopover({ label, value, icon, disabled, attention, open, onOpenChange, wide, children }: { label: string; value: string; icon: ReactNode; disabled: boolean; attention?: boolean; open: boolean; onOpenChange: (open: boolean) => void; wide?: boolean; children: ReactNode }) {
+  return <Popover isOpen={open} onOpenChange={onOpenChange}>
+    <Button size="sm" variant="ghost" className="wpb-config-trigger" isDisabled={disabled} aria-label={`${label}: ${value}`}>{icon}<span>{value}</span>{attention && <AlertTriangle size={13} className="text-warning" aria-label="Needs attention" />}</Button>
+    <Popover.Content placement="bottom start" className={`wpb-popover ${wide ? "wpb-popover-wide" : "wpb-popover-tray"}`}><Popover.Dialog aria-label={`${label} for this Work`}>{children}</Popover.Dialog></Popover.Content>
+  </Popover>;
+}
+
+export const ScopeNote = () => <PopoverFootnote>Applies to this Work only</PopoverFootnote>;
+
+/** A check row: the control, the entry and its state, and an optional action. */
+export function CheckRow({ label, checked, disabled, struck, title, secondary, warn, trailing, onChange }: { label: string; checked: boolean; disabled?: boolean; struck?: boolean; title: string; secondary?: string; warn?: boolean; trailing?: ReactNode; onChange: () => void }) {
+  return <div className="wst-check-row" data-struck={struck || undefined}>
+    <Checkbox aria-label={label} isSelected={checked} isDisabled={disabled} onChange={onChange} className="wst-check">
+      <Checkbox.Content><Checkbox.Control><Checkbox.Indicator /></Checkbox.Control>
+        <span className="wst-check-copy"><span className="wst-check-title">{title}</span>{secondary && <span className={warn ? "text-warning" : "wpb-muted"}>{secondary}</span>}</span>
+      </Checkbox.Content>
+    </Checkbox>
+    {trailing}
+  </div>;
+}
+
+export function Search({ label, value, onChange }: { label: string; value: string; onChange: (value: string) => void }) {
+  return <SearchField className="wpb-search" aria-label={label} value={value} onChange={onChange} onKeyDown={event => { if (event.key === "Enter") event.preventDefault(); }}>
+    <SearchField.Group><SearchField.SearchIcon /><SearchField.Input autoFocus placeholder={label} /><SearchField.ClearButton aria-label="Clear search" /></SearchField.Group>
+  </SearchField>;
+}
+
+// Where the Work runs. With a single choice, the one Cloud, the picker only
+// states it; otherwise it lists every Cloud, then the person's Managed
+// Computers. An offline Managed Computer refuses a start, so it can't be picked.
+// With no selection, a remembered choice that is gone, it lists them to choose
+// again.
+export function ComputerPicker({ computers, selected, disabled, open, onOpenChange, onChange }: { computers?: UsableComputer[]; selected?: UsableComputer; disabled: boolean; open: boolean; onOpenChange: (open: boolean) => void; onChange?: (id: string) => void }) {
+  if (!computers || !onChange || (computers.length < 2 && selected)) return <TrayPopover label="Computer" value="Cloud" icon={<Cloud size={16} />} disabled={disabled} open={open} onOpenChange={onOpenChange}>
+    <ListBox aria-label="Computer" selectionMode="single" disallowEmptySelection selectedKeys={["cloud"]}>
+      <ListBox.Item id="cloud" textValue="Cloud" className="wpb-choice"><Cloud size={16} /><span className="wpb-choice-copy"><Label>Cloud</Label><span className="wpb-muted">Managed by Talgent</span></span><ListBox.ItemIndicator /></ListBox.Item>
+    </ListBox>
+  </TrayPopover>;
+  const icon = (computer: UsableComputer) => computer.managed ? <Server size={16} /> : <Cloud size={16} />;
+  return <TrayPopover label="Computer" value={selected?.name ?? "Choose a Computer"} icon={selected ? icon(selected) : <Server size={16} />} attention={!selected?.reachable} disabled={disabled} open={open} onOpenChange={onOpenChange}>
+    <ListBox aria-label="Computer" selectionMode="single" disallowEmptySelection selectedKeys={selected ? [selected.id] : []} disabledKeys={computers.filter(computer => !computer.reachable).map(computer => computer.id)}
+      onSelectionChange={keys => { if (keys === "all" || !keys.size) return; onChange(String([...keys][0])); onOpenChange(false); }}>
+      {computers.map(computer => <ListBox.Item key={computer.id} id={computer.id} textValue={computer.reachable ? computer.name : `${computer.name}, offline`} className="wpb-choice">
+        {icon(computer)}<span className="wpb-choice-copy"><Label>{computer.name}</Label><span className="wpb-muted">{computer.managed ? "Managed Computer" : "Managed by Talgent"}</span></span>
+        {computer.reachable ? <ListBox.ItemIndicator /> : <span className="wst-offline">Offline</span>}
+      </ListBox.Item>)}
+    </ListBox>
+  </TrayPopover>;
+}
+
+// Repositories are what the assignee's GitHub authorization reaches now; the
+// assignee's recently used ones come first. No binding step exists.
+export function RepositoryPicker({ repositories, recent, unavailable, loading, selected, disabled, open, onOpenChange, onChange, onRetry, returnTo }: {
+  repositories: WorkStartRepository[]; recent: string[]; unavailable: boolean; loading: boolean; selected: string[]; disabled: boolean;
+  open: boolean; onOpenChange: (open: boolean) => void; onChange: (selected: string[]) => void; onRetry: () => void; returnTo: string;
+}) {
+  const [query, setQuery] = useState("");
+  const github = useProviderConnection("github");
+  const connect = useConnectProvider();
+  const status = github.data?.state?.status;
+  const byId = new Map(repositories.map(repository => [repository.id, repository]));
+  const value = selected.length === 0 ? "Repository" : selected.length === 1 ? byId.get(selected[0])?.repoName ?? "1 repository" : `${selected.length} repositories`;
+  const matches = repositories.filter(repository => repository.repoName.toLowerCase().includes(query.trim().toLowerCase()));
+  const recentRows = recent.map(id => byId.get(id)).filter((item): item is WorkStartRepository => Boolean(item));
+  const toggle = (id: string) => onChange(selected.includes(id) ? selected.filter(item => item !== id) : [...selected, id]);
+  const row = (repository: WorkStartRepository) => <CheckRow key={repository.id} label={repository.repoName} checked={selected.includes(repository.id)} title={repository.repoName} secondary={repository.defaultBranch} onChange={() => toggle(repository.id)} />;
+  const group = (title: string, items: WorkStartRepository[]) => items.length > 0 && <div className="wst-rows" role="group" aria-label={title}><p className="wst-group-title">{title}</p>{items.map(row)}</div>;
+  const needsConnection = status !== undefined && status !== "active";
+  return <TrayPopover label="Repositories" value={value} icon={<GitBranch size={16} />} disabled={disabled} open={open} onOpenChange={value => { onOpenChange(value); if (value) setQuery(""); }}>
+    {loading ? <p className="wpb-empty" role="status">Loading repositories…</p>
+      : needsConnection && !repositories.length ? <div className="wst-picker-empty">
+        <p>{status === "reconnect_required" ? "Your GitHub authorization expired. Reconnect to check out repositories." : "Connect GitHub to check out repositories in this Work. You can start without one."}</p>
+        <Button size="sm" variant="secondary" isPending={connect.isPending} onPress={() => connect.mutate({ provider: "github", returnTo })}>{status === "reconnect_required" ? "Reconnect GitHub" : `Connect ${providerName("github")}`}</Button>
+      </div>
+      : unavailable ? <p className="wpb-empty" role="alert">Repositories couldn’t be loaded. You can start without one. <Button size="sm" variant="ghost" onPress={onRetry}>Retry</Button></p>
+      : <>
+        <Search label="Search repositories" value={query} onChange={setQuery} />
+        <div className="wst-scroll">
+          {!repositories.length ? <p className="wpb-empty" role="status">GitHub doesn’t allow Talgent into any repository yet.</p>
+            : query ? matches.length ? <div className="wst-rows">{matches.map(row)}</div> : <p className="wpb-empty" role="status">No repositories match.</p>
+            : <>{group("Recent", recentRows)}{group(recentRows.length ? "All repositories" : "Repositories", repositories.filter(repository => !recent.includes(repository.id)))}</>}
+        </div>
+        <ScopeNote />
+      </>}
+  </TrayPopover>;
+}
+
+// One Startup Agent from the Plugins included in this Work.
+export function AgentPicker({ agents, value, disabled, open, onOpenChange, onChange }: { agents: Capability[]; value: string; disabled: boolean; open: boolean; onOpenChange: (open: boolean) => void; onChange: (agent: string) => void }) {
+  return <TrayPopover label="Startup Agent" value={value ? value.split(":").at(-1)! : "Default Agent"} icon={<Bot size={16} />} disabled={disabled} open={open} onOpenChange={onOpenChange}>
+    <ListBox aria-label="Startup Agent" selectionMode="single" selectedKeys={[value || "default"]} onSelectionChange={keys => { if (keys === "all" || !keys.size) return; const next = String([...keys][0]); onChange(next === "default" ? "" : next); onOpenChange(false); }}>
+      <ListBox.Item id="default" textValue="Default Agent" className="wpb-choice"><Bot size={16} /><span className="wpb-choice-copy"><Label>Default Agent</Label><span className="wpb-muted">Talgent</span></span><ListBox.ItemIndicator /></ListBox.Item>
+      {agents.map(agent => <ListBox.Item key={agent.name} id={agent.name} textValue={agent.name} className="wpb-choice"><Bot size={16} /><span className="wpb-choice-copy"><Label title={agent.description}>{agent.name.split(":").at(-1)}</Label><span className="wpb-muted">{agent.plugin}</span></span><ListBox.ItemIndicator /></ListBox.Item>)}
+    </ListBox>
+  </TrayPopover>;
+}
+
+type Harness = NonNullable<WorkStartInput["harness"]>;
+
+// How the Harness runs on a Managed Computer: its permission mode, and whether
+// it runs in Claude Code's sandbox. A Cloud has neither, so it is never offered.
+// A machine that reports no sandbox can't be asked for one.
+export function HarnessPicker({ value, sandboxAvailable, disabled, open, onOpenChange, onChange }: { value: Harness; sandboxAvailable: boolean; disabled: boolean; open: boolean; onOpenChange: (open: boolean) => void; onChange: (value: Harness) => void }) {
+  const mode = permissionModeOption(value.permissionMode);
+  return <TrayPopover label="Permissions" value={`${mode?.short ?? "Permissions"}${value.sandbox ? " · Sandbox" : ""}`} icon={<Shield size={16} />} disabled={disabled} open={open} onOpenChange={onOpenChange}>
+    <PermissionModeList value={value.permissionMode} onChange={permissionMode => onChange({ ...value, permissionMode })} />
+    <div className="wst-switch-row">
+      <Switch size="sm" isSelected={value.sandbox} isDisabled={!sandboxAvailable} onChange={sandbox => onChange({ ...value, sandbox })}>
+        <Switch.Content>Run in Claude Code’s sandbox<Switch.Control><Switch.Thumb /></Switch.Control></Switch.Content>
+        {!sandboxAvailable && <Description className="wst-switch-note">This Computer can’t provide it</Description>}
+      </Switch>
+    </div>
+    <ScopeNote />
+  </TrayPopover>;
+}

package/hooks/use-debounced.ts

@@ -0,0 +1,11 @@
+import { useEffect, useState } from "react";
+
+/** The value once it has stayed unchanged for `delayMs`, such as typed search text. */
+export function useDebounced<T>(value: T, delayMs: number): T {
+  const [settled, setSettled] = useState(value);
+  useEffect(() => {
+    const timer = setTimeout(() => setSettled(value), delayMs);
+    return () => clearTimeout(timer);
+  }, [value, delayMs]);
+  return settled;
+}

package/hooks/use-work-conversation.ts

@@ -0,0 +1,125 @@
+import { useCallback, useEffect, useMemo, useState, useSyncExternalStore } from "react";
+import { useInfiniteQuery, useQuery } from "@tanstack/react-query";
+import type { MessageHistoryCursor, WorkStateFrame } from "@talgent/workbench-contracts/streamgateway/public/v1/streamgateway_pb";
+import { ContentBlockType, UnifiedMessageKind, type UnifiedMessage } from "@talgent/workbench-contracts/dispatcher/public/v1/unified_message_pb";
+import { useWorkStreamSource } from "../lib/work-stream-source";
+import { WorkConversation } from "../lib/work-conversation";
+import { compareMessageCursor, useWorkStream } from "./use-work-stream";
+import { notifyWorkNotice } from "../lib/work-notices";
+
+interface TurnAnchor { id: string; turnId: string; title: string; timestamp: NonNullable<UnifiedMessage["timestamp"]> }
+function turnAnchor(message: UnifiedMessage): TurnAnchor[] {
+  if (message.kind !== UnifiedMessageKind.USER || message.agent !== "" || !message.turnId || !message.timestamp || message.payload.case !== "message") return [];
+  const title = message.payload.value.content.filter(block => block.type === ContentBlockType.TEXT).map(block => block.text.slice(0, 160)).join("\n\n").slice(0, 160) || "Image attachment";
+  return [{ id: message.id, turnId: message.turnId, timestamp: message.timestamp, title }];
+}
+const cursorFor = (anchor: { id: string; timestamp: TurnAnchor["timestamp"] }): MessageHistoryCursor => ({ $typeName: "talgent.streamgateway.public.v1.MessageHistoryCursor", id: anchor.id, timestamp: anchor.timestamp });
+
+export function useWorkConversation(workId: string | undefined, onWorkState?: (state: WorkStateFrame) => void, onReconnect?: () => void, onActivity?: () => void, onAccessWithdrawn?: () => void) {
+  const streamClient = useWorkStreamSource();
+  const [navigation, setNavigation] = useState<{ workId?: string; generation: number; before?: MessageHistoryCursor; from?: MessageHistoryCursor }>({ workId, generation: 0 });
+  const generation = navigation.workId === workId ? navigation.generation : 0;
+  const before = navigation.workId === workId ? navigation.before : undefined;
+  const from = navigation.workId === workId ? navigation.from : undefined;
+  const browsingHistory = Boolean(before || from);
+  const [liveAnchors, setLiveAnchors] = useState<{ workId?: string; users: TurnAnchor[] }>({ workId, users: [] });
+  // Index only user messages, independently of the bounded transcript window.
+  // Retain titles/cursors, never image bodies or the original query response.
+  const index = useInfiniteQuery({
+    queryKey: ["work-turn-index", workId], enabled: Boolean(workId),
+    initialPageParam: undefined as MessageHistoryCursor | undefined,
+    queryFn: async ({ pageParam, signal }) => {
+      const page = await streamClient.listMessagesBySession({ agentWorkId: workId!, agent: "", kinds: [UnifiedMessageKind.USER], limit: 100, before: pageParam }, { signal });
+      return { users: page.messages.flatMap(turnAnchor), next: page.hasMore ? page.nextBefore : undefined };
+    },
+    getNextPageParam: page => page.next,
+    maxPages: 5, retry: false, gcTime: 0, staleTime: Infinity, refetchOnWindowFocus: false, refetchOnReconnect: false,
+  });
+  const liveTail = useMemo(() => new WorkConversation(workId ?? "", 100, 2 * 1024 * 1024), [workId]);
+  // Returning to latest deliberately replaces the retained history window.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  const conversation = useMemo(() => new WorkConversation(workId ?? ""), [workId, generation]);
+  // Replay bursts update the bounded window immediately, but notify React at
+  // most once per frame instead of rendering the transcript for each item.
+  const subscribe = useCallback((listener: () => void) => {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const unsubscribe = conversation.subscribe(() => {
+      timer ??= setTimeout(() => { timer = undefined; listener(); }, 16);
+    });
+    return () => { clearTimeout(timer); unsubscribe(); };
+  }, [conversation]);
+  const snapshot = useSyncExternalStore(subscribe, conversation.getSnapshot);
+  const [arrival, setArrival] = useState<WorkConversation | null>(null);
+  const history = useQuery({
+    queryKey: ["work-conversation", workId, generation, before?.timestamp?.seconds.toString(), before?.timestamp?.nanos, before?.id, from?.timestamp?.seconds.toString(), from?.timestamp?.nanos, from?.id],
+    enabled: Boolean(workId),
+    queryFn: async ({ signal }) => {
+      const page = await streamClient.listMessagesBySession({ agentWorkId: workId!, agent: "", includeUnattributedErrors: true, limit: 100, before, from }, { signal });
+      // Apply the same byte ceiling before retaining the query response too.
+      const window = new WorkConversation(workId!, 100);
+      window.add(page.messages, from ? "older" : "history");
+      const retained = window.getSnapshot();
+      return { ...page, messages: retained.turns.flatMap(turn => turn.messages), hasMore: page.hasMore || retained.olderEvicted };
+    },
+    retry: false, gcTime: 0, staleTime: Infinity, refetchOnWindowFocus: false, refetchOnReconnect: false,
+  });
+  useEffect(() => {
+    // Live delivery can precede visibility in stored history. Reuse the bounded
+    // tail on a window reset rather than losing those messages during that gap.
+    if (from) return;
+    conversation.add(liveTail.getSnapshot().turns.flatMap(turn => turn.messages), "replay");
+  // A forward cursor changes within the same window; seed only on reset.
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [conversation, liveTail]);
+  useEffect(() => {
+    if (history.data) conversation.add(history.data.messages, before ? "older" : "history");
+  }, [conversation, history.data, before]);
+  const navigationTurns = useMemo(() => {
+    const users = [...(index.data?.pages.flatMap(page => page.users) ?? []), ...(liveAnchors.workId === workId ? liveAnchors.users : []), ...snapshot.turns.flatMap(turn => turn.messages.flatMap(turnAnchor))];
+    users.sort((a, b) => compareMessageCursor(a.timestamp, a.id, b.timestamp, b.id));
+    const turns = new Map<string, TurnAnchor>();
+    for (const user of users) if (!turns.has(user.turnId)) turns.set(user.turnId, user);
+    return [...turns.values()];
+  }, [index.data, liveAnchors, workId, snapshot.turns]);
+  useWorkStream({
+    workId, includeUnattributedErrors: true, onWorkState, onAccessWithdrawn,
+    onDiagnostic: diagnostic => { if (workId) notifyWorkNotice(workId, diagnostic); },
+    onMessage: (message, replay) => {
+      if (!replay && [UnifiedMessageKind.USER, UnifiedMessageKind.RESULT, UnifiedMessageKind.PERMISSION, UnifiedMessageKind.INTERACTION, UnifiedMessageKind.ERROR].includes(message.kind)) onActivity?.();
+      const anchors = turnAnchor(message);
+      if (anchors.length) setLiveAnchors(current => ({ workId, users: [...(current.workId === workId ? current.users.filter(user => user.id !== message.id) : []), ...anchors].slice(-100) }));
+      liveTail.add([message], replay ? "replay" : "live");
+      // While reading older pages, keep the reading window intact. Returning to
+      // latest combines authoritative history with the bounded recent tail.
+      if (browsingHistory && !conversation.has(message.id)) {
+        if (!replay && message.kind === UnifiedMessageKind.USER) setNavigation({ workId, generation });
+        else { setArrival(conversation); return; }
+      }
+      conversation.add([message], replay ? "replay" : "live");
+    },
+    onReconnect: () => { if (!browsingHistory) void history.refetch(); void index.refetch(); onReconnect?.(); },
+  });
+  const hasMore = Boolean(from || history.data?.hasMore || snapshot.olderEvicted);
+  return {
+    ...snapshot,
+    loading: history.isFetching, error: history.isError, hasMore,
+    navigationTurns, indexLoading: index.isFetching, indexError: index.isError, hasOlderTurns: Boolean(index.hasNextPage),
+    loadOlderTurns: () => { if (!index.isFetching) void index.fetchNextPage(); },
+    retryIndex: () => { void index.refetch(); },
+    browsingHistory, hasNewer: arrival === conversation,
+    retry: () => { void history.refetch(); },
+    loadOlder: () => {
+      const oldest = conversation.getOldest();
+      if (!workId || history.isFetching || !hasMore || !oldest?.timestamp) return;
+      setNavigation({ workId, generation, before: { $typeName: "talgent.streamgateway.public.v1.MessageHistoryCursor", timestamp: oldest.timestamp, id: oldest.id } });
+    },
+    hasLaterMessages: browsingHistory && (Boolean(before) || Boolean(history.data?.hasMore)),
+    loadNewer: () => {
+      const newest = conversation.getNewest();
+      if (!workId || history.isFetching || !newest?.timestamp) return;
+      setNavigation({ workId, generation, from: cursorFor({ id: newest.id, timestamp: newest.timestamp }) });
+    },
+    showTurn: (anchor: TurnAnchor) => setNavigation({ workId, generation: generation + 1, from: cursorFor(anchor) }),
+    showLatest: () => setNavigation({ workId, generation: generation + 1 }),
+  };
+}

package/hooks/use-work-lifecycle-controls.ts

@@ -0,0 +1,40 @@
+import { useRef, useState } from "react";
+import type { WorkInfo } from "@talgent/workbench-contracts/agent/public/v1/work_pb";
+import { agentWorkClient } from "../lib/client";
+import { isStaleWorkControl, workControlErrorMessage } from "../lib/work-projection";
+
+// Every control names the Work version the user saw, except resuming with
+// the owner's own message. onSettled refreshes the authority, so a rejected
+// stale control is followed by the current state and the user confirms again
+// against it. Any other refusal describes the version it was raised against,
+// so it is withdrawn once the Work moves on; a refused resume after a message
+// stays until the next action, since that message already moved the Work on.
+export function useWorkLifecycleControls(workId: string | null | undefined, onWorkChange: (work?: WorkInfo) => void, onSettled: () => void, expectedVersion?: bigint) {
+  const inFlight = useRef(false);
+  const [pending, setPending] = useState(false);
+  const [failure, setFailure] = useState<{ message: string; version?: bigint }>();
+  const [archiveOpen, setArchiveOpen] = useState(false);
+  const run = async (action: () => Promise<void>, versioned = true) => {
+    if (!workId || inFlight.current) return;
+    inFlight.current = true; setPending(true); setFailure(undefined);
+    try { await action(); }
+    catch (cause) {
+      const stale = isStaleWorkControl(cause);
+      setFailure({ message: workControlErrorMessage(cause), version: stale || !versioned ? undefined : expectedVersion });
+      // The confirmation was given for a state that no longer holds.
+      if (stale) setArchiveOpen(false);
+    }
+    finally { inFlight.current = false; setPending(false); onSettled(); }
+  };
+  const error = failure && (failure.version === undefined || failure.version === expectedVersion) ? failure.message : "";
+  const request = () => ({ workId: workId!, expectedVersion });
+  const stop = () => run(async () => onWorkChange((await agentWorkClient.stopWork(request())).work));
+  const resume = () => run(async () => onWorkChange((await agentWorkClient.resumeWork(request())).work));
+  // Resuming after accepted input is the caller's decision. The
+  // owner's message itself moved the Work on, so the resume that continues it
+  // names no version; the Work's state still decides.
+  const continueWithInput = () => run(async () => onWorkChange((await agentWorkClient.resumeWork({ workId: workId! })).work), false);
+  const restart = () => run(async () => onWorkChange((await agentWorkClient.restartWork(request())).work));
+  const archive = () => run(async () => { onWorkChange((await agentWorkClient.archiveWork(request())).work); setArchiveOpen(false); });
+  return { pending, error, archiveOpen, setArchiveOpen, run, stop, resume, continueWithInput, restart, archive };
+}

package/hooks/use-work-stream.ts

@@ -0,0 +1,91 @@
+import { useEffect, useRef } from "react";
+import type { Timestamp } from "@bufbuild/protobuf/wkt";
+import { UnifiedMessageKind, type UnifiedMessage } from "@talgent/workbench-contracts/dispatcher/public/v1/unified_message_pb";
+import type { StreamDiagnosticFrame, WorkStateFrame, WatchStreamResponse } from "@talgent/workbench-contracts/streamgateway/public/v1/streamgateway_pb";
+import { useWorkStreamSource } from "../lib/work-stream-source";
+
+interface WorkStreamOptions {
+  workId?: string;
+  kinds?: UnifiedMessageKind[];
+  includeUnattributedErrors?: boolean;
+  onMessage: (message: UnifiedMessage, replay: boolean) => void;
+  onWorkState?: (state: WorkStateFrame) => void;
+  /** A live notice that is not part of the message stream and is never replayed. */
+  onDiagnostic?: (diagnostic: StreamDiagnosticFrame) => void;
+  onReconnect?: () => void;
+  /** The reader's access ended; the stream stops and does not reconnect. */
+  onAccessWithdrawn?: () => void;
+}
+
+// Use the slim product contract directly. Connection diagnostics are connection
+// state, never fabricated Harness errors or transcript messages.
+export function useWorkStream(options: WorkStreamOptions) {
+  const callbacks = useRef(options);
+  useEffect(() => { callbacks.current = options; });
+  const { workId, kinds, includeUnattributedErrors = false } = options;
+  const source = useWorkStreamSource();
+  const kindsKey = kinds?.join(",") ?? "";
+
+  useEffect(() => {
+    if (!workId) return;
+    const abort = new AbortController();
+    const filters = kindsKey ? kindsKey.split(",").map(Number) as UnifiedMessageKind[] : [];
+    let cursor: { timestamp?: Timestamp; id: string } = { id: "" };
+    let attempt = 0;
+    let reconnecting = false;
+    void (async () => {
+      while (!abort.signal.aborted) {
+        if (reconnecting) callbacks.current.onReconnect?.();
+        try {
+          const events: AsyncIterable<WatchStreamResponse> = source.watchStream({
+            agentWorkId: workId, agent: "", kinds: filters, includeUnattributedErrors,
+            afterTimestamp: cursor.timestamp, afterId: cursor.id,
+          }, { signal: abort.signal });
+          for await (const event of events) {
+            if (abort.signal.aborted) break;
+            attempt = 0;
+            if (event.payload.case === "message") {
+              const message: UnifiedMessage = event.payload.value;
+              const unknownError = includeUnattributedErrors && message.agent === undefined && message.kind === UnifiedMessageKind.ERROR;
+              if (message.agentWorkId !== workId || (message.agent !== "" && !unknownError) || (filters.length && !filters.includes(message.kind))) continue;
+              callbacks.current.onMessage(message, event.replay);
+              if (message.timestamp && (!cursor.timestamp || compareMessageCursor(message.timestamp, message.id, cursor.timestamp, cursor.id) > 0)) {
+                cursor = { timestamp: message.timestamp, id: message.id };
+              }
+            } else if (event.payload.case === "workState" && event.payload.value.agentWorkId === workId) {
+              callbacks.current.onWorkState?.(event.payload.value);
+            } else if (event.payload.case === "diagnostic" && event.payload.value.agentWorkId === workId) {
+              callbacks.current.onDiagnostic?.(event.payload.value);
+            } else if (event.payload.case === "accessWithdrawn" && event.payload.value.agentWorkId === workId) {
+              // Withdrawal is not a connection error: never reconnect.
+              callbacks.current.onAccessWithdrawn?.();
+              return;
+            }
+          }
+        } catch {
+          // Reconnect below from the last received cursor without a UI warning.
+        }
+        if (abort.signal.aborted) break;
+        reconnecting = true;
+        await reconnectDelay(Math.min(5000, 250 * 2 ** attempt++), abort.signal);
+      }
+    })();
+    return () => abort.abort();
+  }, [workId, kindsKey, includeUnattributedErrors, source]);
+
+}
+
+export function compareMessageCursor(a: Timestamp, aID: string, b: Timestamp, bID: string) {
+  if (a.seconds !== b.seconds) return a.seconds < b.seconds ? -1 : 1;
+  if (a.nanos !== b.nanos) return a.nanos < b.nanos ? -1 : 1;
+  return aID < bID ? -1 : aID > bID ? 1 : 0;
+}
+
+function reconnectDelay(ms: number, signal: AbortSignal) {
+  return new Promise<void>(resolve => {
+    const done = () => { window.clearTimeout(timer); signal.removeEventListener("abort", done); resolve(); };
+    const timer = window.setTimeout(done, ms);
+    signal.addEventListener("abort", done, { once: true });
+    if (signal.aborted) done();
+  });
+}

package/lib/account-service.ts

@@ -0,0 +1,77 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import { useMutation, useQueryClient, useQuery } from "@tanstack/react-query";
+import { useNavigate } from "react-router-dom";
+import { sessionClient } from "./client";
+import { dismiss, notify } from "./notifications";
+import { signOut } from "./session";
+import { safeAvatarUrl, safeDisplayName, safeEmail } from "./user-display";
+
+export const currentUserQueryKey = ["account", "current-user"] as const;
+
+export type CurrentUser = {
+  id: string;
+  userId: string;
+  username: string;
+  displayName: string;
+  primaryEmail: string;
+  avatarUrl: string;
+  firstName?: string;
+  lastName?: string;
+  nickName?: string;
+  preferredLanguage?: string;
+  gender?: string;
+};
+
+type CurrentUserView = {
+  user?: CurrentUser;
+};
+
+// Account ids are canonical lowercase UUIDs, the only subject the gateway admits.
+function isAccountId(value: string | undefined): value is string {
+  return /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/.test(value?.trim() ?? "");
+}
+
+export function useCurrentUser() {
+  return useQuery<CurrentUserView>({
+    queryKey: currentUserQueryKey,
+    queryFn: async () => {
+      const response = await sessionClient.getCurrentSession({});
+      const session = response.session;
+      if (!isAccountId(session?.userId)) {
+        throw new ConnectError("unauthenticated", Code.Unauthenticated);
+      }
+      const username = safeDisplayName(session.username, session.userId, "");
+      const primaryEmail = safeEmail(session.primaryEmail);
+      const displayName = safeDisplayName(session.displayName, session.userId, session.primaryEmail || "Profile");
+      return {
+        user: {
+          id: session.userId,
+          userId: session.userId,
+          username,
+          displayName,
+          primaryEmail,
+          avatarUrl: safeAvatarUrl(session.avatarUrl),
+        },
+      };
+    },
+    retry: false,
+    refetchOnWindowFocus: "always",
+    staleTime: 60_000,
+  });
+}
+
+// Ends this device's Login Session, forgets everything loaded for it and
+// returns to the sign-in page.
+export function useLogout() {
+  const queryClient = useQueryClient();
+  const navigate = useNavigate();
+  return useMutation({
+    mutationFn: signOut,
+    onError: () => notify("sign-out", "danger", "You’re still signed in", "Signing out didn’t reach Talgent. Check your connection and try again."),
+    onSuccess: () => {
+      dismiss("sign-out");
+      navigate("/login", { replace: true });
+      queryClient.clear();
+    },
+  });
+}

package/lib/agent-appearance-service.ts

@@ -0,0 +1,59 @@
+import { ConnectError, Code } from "@connectrpc/connect";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCurrentUser } from "./account-service";
+import { agentWorkClient } from "./client";
+import { notify } from "./notifications";
+import { agentIconOf, type AgentIconValue } from "./agent-icon";
+
+// The signed-in person's Work Agent: its name and icon are theirs to set.
+// Before it exists, agentId is empty and the appearance is the one it would
+// start with.
+export interface MyWorkAgent { agentId: string; name: string; icon: AgentIconValue }
+
+/** The meta of a query whose data shows the person's Work Agent, such as a
+ * thread naming its replies' author: saving the Agent's appearance refreshes it. */
+export const showsWorkAgent = { showsWorkAgent: true };
+
+const myWorkAgentKey = (userId: string | undefined) => ["my-work-agent", userId];
+
+export function useMyWorkAgent() {
+  const userId = useCurrentUser().data?.user?.id;
+  return useQuery({
+    queryKey: myWorkAgentKey(userId),
+    queryFn: async (): Promise<MyWorkAgent> => {
+      const agent = await agentWorkClient.getMyWorkAgent({});
+      return { agentId: agent.agentId, name: agent.appearance?.name ?? "", icon: agentIconOf(agent.appearance?.icon) };
+    },
+    enabled: Boolean(userId),
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function useChangeMyWorkAgentAppearance() {
+  const queryClient = useQueryClient();
+  const userId = useCurrentUser().data?.user?.id;
+  return useMutation({
+    mutationFn: async (input: MyWorkAgent): Promise<MyWorkAgent> => {
+      // Saving is the first use: Agent establishes the Work Agent if it has none yet.
+      const agentId = input.agentId || (await agentWorkClient.ensureMyWorkAgent({})).agentId;
+      const response = await agentWorkClient.changeWorkAgentAppearance({ agentId, name: input.name, icon: input.icon });
+      return { agentId, name: response.appearance?.name ?? input.name, icon: agentIconOf(response.appearance?.icon ?? input.icon) };
+    },
+    onSuccess: agent => {
+      // Saving remounts the editor with the saved appearance, so the notice
+      // belongs to the mutation rather than the form.
+      notify("work-agent-appearance", "success", "Work Agent saved");
+      queryClient.setQueryData(myWorkAgentKey(userId), agent);
+      // Every place the Agent appears reads its current appearance.
+      void queryClient.invalidateQueries({ predicate: query => query.meta?.showsWorkAgent === true });
+    },
+  });
+}
+
+export function agentAppearanceErrorMessage(error: unknown) {
+  const code = error instanceof ConnectError ? error.code : undefined;
+  if (code === Code.InvalidArgument) return "Use a name of 1–40 characters and one of the listed icons and colors.";
+  if (code === Code.PermissionDenied) return "Only the person a Work Agent represents can change it.";
+  return "Your Work Agent could not be saved. Try again.";
+}

package/lib/agent-icon.ts

@@ -0,0 +1,26 @@
+import { Atom, Bird, Bot, Brain, Cat, Compass, Flame, Leaf, Rocket, Sparkles, Star, Wand2, type LucideIcon } from "lucide-react";
+
+// A Work Agent's icon: one preset glyph on one preset color. Agent owns the
+// preset ids; anything it does not know reads as the default green robot.
+export const agentGlyphs: ReadonlyArray<{ id: string; label: string; Icon: LucideIcon }> = [
+  { id: "bot", label: "Bot", Icon: Bot }, { id: "sparkles", label: "Sparkles", Icon: Sparkles },
+  { id: "brain", label: "Brain", Icon: Brain }, { id: "rocket", label: "Rocket", Icon: Rocket },
+  { id: "wand", label: "Wand", Icon: Wand2 }, { id: "cat", label: "Cat", Icon: Cat },
+  { id: "bird", label: "Bird", Icon: Bird }, { id: "leaf", label: "Leaf", Icon: Leaf },
+  { id: "flame", label: "Flame", Icon: Flame }, { id: "star", label: "Star", Icon: Star },
+  { id: "compass", label: "Compass", Icon: Compass }, { id: "atom", label: "Atom", Icon: Atom },
+];
+
+// The label palette, as explicit inks: Tailwind v4 emits only the
+// color variables a stylesheet uses.
+export const agentColors = { slate: "#475569", blue: "#2563eb", violet: "#7c3aed", green: "#16a34a", amber: "#d97706", rose: "#e11d48" } as const;
+export type AgentColor = keyof typeof agentColors;
+
+export interface AgentIconValue { glyph: string; color: string }
+export const defaultAgentIcon: AgentIconValue = { glyph: "bot", color: "green" };
+
+export function agentIconOf(icon: Partial<AgentIconValue> | undefined): { glyph: string; color: AgentColor } {
+  const glyph = agentGlyphs.some(item => item.id === icon?.glyph) ? icon!.glyph! : defaultAgentIcon.glyph;
+  const color = (icon?.color && icon.color in agentColors ? icon.color : defaultAgentIcon.color) as AgentColor;
+  return { glyph, color };
+}

package/lib/agent-soul-service.ts

@@ -0,0 +1,48 @@
+import { ConnectError, Code } from "@connectrpc/connect";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useCurrentUser } from "./account-service";
+import { agentWorkClient } from "./client";
+import { notify } from "./notifications";
+
+// The Soul of the signed-in person's Work Agent: the persona and working style
+// every one of its Works takes up at its next start. Only its Owner reads it.
+export const MAX_SOUL = 8000;
+
+const soulKey = (userId: string | undefined, agentId: string) => ["agent-soul", userId, agentId];
+
+/** Reads the Soul; a Work Agent that does not exist yet has none. */
+export function useWorkAgentSoul(agentId: string | undefined) {
+  const userId = useCurrentUser().data?.user?.id;
+  return useQuery({
+    queryKey: soulKey(userId, agentId ?? ""),
+    queryFn: async () => agentId ? (await agentWorkClient.getAgentSoul({ agentId })).soul : "",
+    enabled: Boolean(userId) && agentId !== undefined,
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function useChangeWorkAgentSoul() {
+  const queryClient = useQueryClient();
+  const userId = useCurrentUser().data?.user?.id;
+  return useMutation({
+    mutationFn: async ({ agentId, soul }: { agentId: string; soul: string }) => {
+      // Saving is the first use: Agent establishes the Work Agent if it has none yet.
+      const id = agentId || (await agentWorkClient.ensureMyWorkAgent({})).agentId;
+      const response = await agentWorkClient.changeAgentSoul({ agentId: id, soul });
+      return { agentId: id, soul: response.soul };
+    },
+    onSuccess: ({ agentId, soul }, input) => {
+      notify("work-agent-soul", "success", "Soul saved", "Your Works take it up at their next start.");
+      queryClient.setQueryData(soulKey(userId, agentId), soul);
+      if (!input.agentId) void queryClient.invalidateQueries({ queryKey: ["my-work-agent", userId] });
+    },
+  });
+}
+
+export function soulErrorMessage(error: unknown) {
+  const code = error instanceof ConnectError ? error.code : undefined;
+  if (code === Code.InvalidArgument) return `Use at most ${MAX_SOUL} characters.`;
+  if (code === Code.PermissionDenied) return "Only your Work Agent's Owner can change its Soul.";
+  return "The Soul could not be saved. Try again.";
+}

package/lib/agent-work-service.ts

@@ -0,0 +1,23 @@
+import { useQuery } from "@tanstack/react-query";
+import { agentWorkClient } from "./client";
+
+// A Work as Agent shows it to its owner (AgentWorkService.GetWork). Every
+// reader of one Work shares this cache entry, which holds Agent's response.
+export const agentWorkQueryKey = (workId: string | null | undefined) => ["agent-work", workId] as const;
+
+/** Polls a Work's state while it starts or runs; a closed Work no longer changes. */
+export function workPollInterval(data: { work?: { state: string } } | undefined) {
+  return data?.work?.state === "closed" ? false : 5000;
+}
+
+/** The owner's view of the Work; Agent refuses anyone else. */
+export function useAgentWork(workId: string | null | undefined, enabled = true) {
+  return useQuery({
+    queryKey: agentWorkQueryKey(workId),
+    queryFn: ({ signal }) => agentWorkClient.getWork({ workId: workId! }, { signal }),
+    enabled: Boolean(workId) && enabled,
+    refetchInterval: query => workPollInterval(query.state.data),
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+}