@talgent/workbench-ui 0.0.0 → 0.2.0

package/lib/client.ts

@@ -0,0 +1,20 @@
+import { createClient } from "@connectrpc/connect";
+import { AgentWorkService } from "@talgent/workbench-contracts/agent/public/v1/work_pb";
+import { PersonalWorkService } from "@talgent/workbench-contracts/agent/public/v1/personal_work_pb";
+import { WorkFileService } from "@talgent/workbench-contracts/agent/public/v1/work_file_pb";
+import { StreamGatewayService } from "@talgent/workbench-contracts/streamgateway/public/v1/streamgateway_pb";
+import { TraceQueryService } from "@talgent/workbench-contracts/trace/public/v1/trace_pb";
+import { MarketplaceService } from "@talgent/workbench-contracts/marketplace/public/v1/marketplace_pb";
+import { SessionService } from "@talgent/workbench-contracts/account/public/v1/session_pb";
+import { ComputerService } from "@talgent/workbench-contracts/computer/public/v1/computer_pb";
+import { transport, streamTransport, traceTransport } from "./transport";
+
+// The Agent Workbench core's clients.
+export const agentWorkClient = createClient(AgentWorkService, transport);
+export const personalWorkClient = createClient(PersonalWorkService, transport);
+export const workFileClient = createClient(WorkFileService, transport);
+export const streamClient = createClient(StreamGatewayService, streamTransport);
+export const traceClient = createClient(TraceQueryService, traceTransport);
+export const marketplaceClient = createClient(MarketplaceService, transport);
+export const sessionClient = createClient(SessionService, transport);
+export const computerClient = createClient(ComputerService, transport);

package/lib/computer-release.ts

@@ -0,0 +1,30 @@
+import { useQuery } from "@tanstack/react-query";
+
+// The platform release this deployment runs, as Computer's machine service
+// answers it (GET /computer/v1/release): Talgent Computer is published to npm at that
+// version. Empty when the deployment is no release.
+
+const release = /^\d+\.\d+\.\d+$/;
+
+export async function fetchComputerRelease(): Promise<string> {
+  const response = await fetch("/computer/v1/release", { headers: { Accept: "application/json" } });
+  if (!response.ok) throw new Error(`the release answered ${response.status}`);
+  const body: unknown = await response.json();
+  const version = typeof body === "object" && body !== null && "version" in body ? body.version : undefined;
+  return typeof version === "string" && release.test(version) ? version : "";
+}
+
+export function useComputerRelease() {
+  return useQuery({ queryKey: ["computer-release"], queryFn: fetchComputerRelease, staleTime: 5 * 60_000 });
+}
+
+/** The commands that install Talgent Computer on a machine of any platform,
+ * at the release this deployment runs, register it with this entry and keep
+ * it running as the person's background service. */
+export function installCommands(origin: string, version: string): string[] {
+  return [
+    `npm install -g @talgent/computer${version === "" ? "" : `@${version}`}`,
+    `talgent-computer register --server ${origin}`,
+    "talgent-computer service install",
+  ];
+}

package/lib/computer-service.ts

@@ -0,0 +1,241 @@
+import { Code, ConnectError } from "@connectrpc/connect";
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { AdmissionPolicy as AdmissionPolicyMessage, UsableComputerKind, type ManagedComputer as ManagedComputerMessage } from "@talgent/workbench-contracts/computer/public/v1/computer_pb";
+import { useCurrentUser } from "./account-service";
+import { computerClient } from "./client";
+import { timeAgo } from "./relative-time";
+
+// The person's own Managed Computers (Computer's ComputerService): the
+// machines they registered, whether the platform reaches each now, naming
+// them, and approving a machine's registration. A Cloud never appears here.
+
+export type Presence = { kind: "online" } | { kind: "offline"; since: Date | null } | { kind: "never" };
+
+/** What a full Computer answers a run: reject it, or queue it. */
+export type AdmissionPolicy = "reject" | "queue";
+
+export type ManagedComputer = {
+  id: string;
+  name: string;
+  presence: Presence;
+  talgentComputerVersion: string;
+  claudeCodeVersion: string;
+  /** How many Works it runs at once. */
+  capacity: number;
+  policy: AdmissionPolicy;
+  /** How many Works it runs now, and how many wait in its line. */
+  running: number;
+  waiting: number;
+};
+
+function presenceOf(presence: ManagedComputerMessage["presence"]): Presence {
+  if (presence?.reachable) return { kind: "online" };
+  if (!presence || presence.neverConnected) return { kind: "never" };
+  const since = Number(presence.unreachableSinceUnixMs);
+  return { kind: "offline", since: since > 0 ? new Date(since) : null };
+}
+
+export function managedComputer(computer: ManagedComputerMessage): ManagedComputer {
+  return {
+    id: computer.id,
+    name: computer.name,
+    presence: presenceOf(computer.presence),
+    talgentComputerVersion: computer.talgentComputerVersion,
+    claudeCodeVersion: computer.claudeCodeVersion,
+    capacity: Number(computer.capacity),
+    policy: computer.admissionPolicy === AdmissionPolicyMessage.QUEUE ? "queue" : "reject",
+    running: Number(computer.running),
+    waiting: Number(computer.waiting),
+  };
+}
+
+/** How a Computer's room reads in the list ("1 of 2 running · 1 waiting"). */
+export function roomLabel(computer: Pick<ManagedComputer, "capacity" | "running" | "waiting">): string {
+  const running = `${computer.running} of ${computer.capacity} running`;
+  return computer.waiting > 0 ? `${running} · ${computer.waiting} waiting` : running;
+}
+
+export const maxCapacity = 32;
+
+/** Why a Capacity can't be saved, or "" when it can. */
+export function capacityProblem(capacity: number, running: number): string {
+  if (!Number.isInteger(capacity) || capacity < 1 || capacity > maxCapacity) return `Choose 1 to ${maxCapacity} Works.`;
+  if (capacity < running) return `It runs ${running} Works now. Choose at least ${running}.`;
+  return "";
+}
+
+/** How a Computer's Presence reads in the list. */
+export function presenceLabel(presence: Presence, now = Date.now()): string {
+  switch (presence.kind) {
+    case "online": return "Online";
+    case "never": return "Never connected";
+    case "offline": return presence.since ? `Offline since ${timeAgo(presence.since, now)}` : "Offline";
+  }
+}
+
+export const maxComputerName = 64;
+
+/** Why a name can't be saved, or "" when it can. The server trims too. */
+export function computerNameProblem(name: string): string {
+  const trimmed = name.trim();
+  if (!trimmed) return "Enter a name.";
+  if (Array.from(trimmed).length > maxComputerName) return `Use at most ${maxComputerName} characters.`;
+  return "";
+}
+
+export const computersKey = ["computers"] as const;
+
+/** The person's Managed Computers, newest first, polled so Presence moves
+ * without a reload. */
+export function useComputers() {
+  const userId = useCurrentUser().data?.user?.id;
+  return useQuery({
+    queryKey: [...computersKey, userId ?? ""],
+    queryFn: async ({ signal }) => (await computerClient.listComputers({}, { signal })).computers.map(managedComputer),
+    enabled: Boolean(userId),
+    retry: false,
+    refetchInterval: 10_000,
+    refetchOnWindowFocus: false,
+  });
+}
+
+/** A Computer a person may start a Personal Work on: a Cloud, or one of
+ * their Managed Computers, which takes a start only while reachable. sandbox
+ * is whether a Managed Computer's machine reports it can provide Claude
+ * Code's sandbox. */
+export type UsableComputer = { id: string; name: string; managed: boolean; reachable: boolean; sandbox: boolean };
+
+/** Every Cloud, then the person's Managed Computers; the first is the default.
+ * Polled so a Managed Computer going offline shows before a start is refused. */
+export function useUsableComputers(enabled = true) {
+  const userId = useCurrentUser().data?.user?.id;
+  return useQuery({
+    queryKey: ["usable-computers", userId ?? ""],
+    queryFn: async ({ signal }): Promise<UsableComputer[]> => (await computerClient.listUsableComputers({}, { signal })).computers.map(computer => ({
+      id: computer.id,
+      name: computer.name,
+      managed: computer.kind === UsableComputerKind.MANAGED,
+      reachable: computer.kind !== UsableComputerKind.MANAGED || computer.reachable,
+      sandbox: computer.kind === UsableComputerKind.MANAGED && computer.claudeCodeSandbox,
+    })),
+    enabled: enabled && Boolean(userId),
+    retry: false,
+    refetchInterval: 10_000,
+    refetchOnWindowFocus: false,
+  });
+}
+
+/** The Computer a Work runs on, as its reader sees it: named when it is one
+ * the reader may use; another person's Managed Computer is shown only as
+ * managed. Absent until the Work names its Computer. */
+export type WorkComputer = { name?: string; managed: boolean };
+
+export function useWorkComputer(computerId: string | undefined, managed: boolean): WorkComputer | undefined {
+  const usable = useUsableComputers(Boolean(computerId));
+  if (!computerId) return undefined;
+  const known = usable.data?.find(computer => computer.id === computerId);
+  return known ? { name: known.name, managed: known.managed } : { managed };
+}
+
+export function useRenameComputer(computerId: string) {
+  const client = useQueryClient();
+  return useMutation({
+    mutationFn: async (name: string) => managedComputer((await computerClient.renameComputer({ computerId, name: name.trim() })).computer!),
+    onSuccess: () => { void client.invalidateQueries({ queryKey: computersKey }); },
+  });
+}
+
+export function useSetRoomRules(computerId: string) {
+  const client = useQueryClient();
+  return useMutation({
+    mutationFn: async ({ capacity, policy }: { capacity: number; policy: AdmissionPolicy }) => managedComputer((await computerClient.setRoomRules({
+      computerId, capacity: BigInt(capacity), admissionPolicy: policy === "queue" ? AdmissionPolicyMessage.QUEUE : AdmissionPolicyMessage.REJECT,
+    })).computer!),
+    onSuccess: () => { void client.invalidateQueries({ queryKey: computersKey }); },
+  });
+}
+
+/** Removes one of the person's Managed Computers for good. The lists of
+ * Computers, and of those a Work may start on, no longer show it, nor one
+ * that no longer exists. */
+export function useRemoveComputer(computerId: string) {
+  const client = useQueryClient();
+  const refresh = () => {
+    void client.invalidateQueries({ queryKey: computersKey });
+    void client.invalidateQueries({ queryKey: ["usable-computers"] });
+  };
+  return useMutation({
+    mutationFn: async () => { await computerClient.removeComputer({ computerId }); },
+    onSuccess: refresh,
+    onError: (error) => { if (ConnectError.from(error).code === Code.NotFound) refresh(); },
+  });
+}
+
+/** Why a Computer wasn't removed, as the person acts on it. */
+export function removeComputerErrorMessage(error: unknown): string {
+  if (ConnectError.from(error).code === Code.NotFound) return "This computer no longer exists.";
+  return "The computer couldn’t be removed. Try again.";
+}
+
+/** Why room rules weren't saved, as the person acts on it. */
+export function roomRulesErrorMessage(error: unknown): string {
+  const code = ConnectError.from(error).code;
+  if (code === Code.FailedPrecondition) return "It runs more Works now than that Capacity. Choose a higher Capacity or try again once some end.";
+  if (code === Code.NotFound) return "This computer no longer exists.";
+  return "The settings couldn’t be saved. Try again.";
+}
+
+/** A user code as Talgent Computer shows it ("ABCD-EFGH"), from what the
+ * person typed or the link carried. */
+export function normalizeUserCode(value: string | null | undefined): string {
+  const compact = (value ?? "").replace(/[^0-9a-z]/gi, "").toUpperCase();
+  return compact.length > 4 ? `${compact.slice(0, 4)}-${compact.slice(4)}` : compact;
+}
+
+export type RegistrationRefusal = "invalid" | "taken" | "failed";
+
+/** Why reading or approving a registration failed, as the person acts on it. */
+export function registrationRefusal(error: unknown): RegistrationRefusal {
+  const code = ConnectError.from(error).code;
+  if (code === Code.NotFound) return "invalid";
+  if (code === Code.FailedPrecondition) return "taken";
+  return "failed";
+}
+
+export const registrationRefusalText: Record<RegistrationRefusal, string> = {
+  invalid: "This code is invalid or expired",
+  taken: "Another person already approved this code",
+  failed: "This code couldn’t be checked",
+};
+
+export type Registration = { machineName: string; expiresAt: Date | null; approved: boolean };
+
+export function useRegistration(userCode: string) {
+  return useQuery({
+    queryKey: ["computer-registration", userCode],
+    queryFn: async ({ signal }): Promise<Registration> => {
+      const response = await computerClient.getRegistration({ userCode }, { signal });
+      const expires = Number(response.expiresAtUnixMs);
+      return { machineName: response.machineName, expiresAt: expires > 0 ? new Date(expires) : null, approved: response.approved };
+    },
+    enabled: userCode.length > 0,
+    retry: false,
+    refetchOnWindowFocus: false,
+  });
+}
+
+export function useApproveRegistration() {
+  const client = useQueryClient();
+  return useMutation({
+    mutationFn: async (userCode: string) => { await computerClient.approveRegistration({ userCode }); },
+    onSuccess: () => { void client.invalidateQueries({ queryKey: computersKey }); },
+  });
+}
+
+/** How long a pending registration has left ("Expires in 9m"). */
+export function expiryLabel(expiresAt: Date | null, now = Date.now()): string {
+  if (!expiresAt) return "";
+  const minutes = Math.ceil((expiresAt.getTime() - now) / 60_000);
+  if (minutes <= 0) return "Expired";
+  return minutes < 60 ? `Expires in ${minutes}m` : `Expires in ${Math.floor(minutes / 60)}h`;
+}

package/lib/dashboard-report.ts

@@ -0,0 +1,38 @@
+import type { DashboardWindow } from "./dashboard";
+
+export interface DashboardReportPeriod {
+  start: Date;
+  end: Date;
+  stepSeconds: number;
+  bucketCount: number;
+}
+
+// Fixed elapsed UTC intervals shared by both perspectives and their queries.
+export function dashboardReportPeriod(range: DashboardWindow, now: Date): DashboardReportPeriod {
+  const stepSeconds = range === "24h" ? 7200 : range === "7d" ? 43200 : 172800;
+  const bucketCount = range === "24h" ? 12 : range === "7d" ? 14 : 15;
+  const alignment = range === "24h" ? 7200000 : 86400000;
+  const end = new Date((Math.floor(now.getTime() / alignment) + 1) * alignment);
+  return { start: new Date(end.getTime() - stepSeconds * bucketCount * 1000), end, stepSeconds, bucketCount };
+}
+
+export function previousReportPeriod(period: DashboardReportPeriod): DashboardReportPeriod {
+  return { ...period, start: new Date(period.start.getTime() - (period.end.getTime() - period.start.getTime())), end: period.start };
+}
+
+export function reportBucketLabels(period: DashboardReportPeriod, index: number) {
+  const start = new Date(period.start.getTime() + index * period.stepSeconds * 1000);
+  const end = new Date(start.getTime() + period.stepSeconds * 1000);
+  const date = start.toLocaleDateString("en-US", { month: "short", day: "numeric", timeZone: "UTC" });
+  const time = start.toISOString().slice(11, 16);
+  return {
+    label: period.stepSeconds === 7200 ? time : period.stepSeconds === 43200 ? `${date} · ${time}` : date,
+    interval: `${start.toISOString().slice(0,16).replace("T", " ")} – ${end.toISOString().slice(0,16).replace("T", " ")} UTC`,
+  };
+}
+
+export function compareMetric(current: number | null, previous: number | null) {
+  if (current === null || previous === null) return { direction: "unknown", percent: null } as const;
+  if (previous === 0 && current !== 0) return { direction: "new", percent: null } as const;
+  return { direction: current > previous ? "up" : current < previous ? "down" : "flat", percent: previous === 0 ? 0 : (current - previous) / previous * 100 } as const;
+}

package/lib/dashboard.ts

@@ -0,0 +1,21 @@
+export type DashboardWindow = "24h" | "7d" | "30d";
+export const dashboardWindows: DashboardWindow[] = ["24h", "7d", "30d"];
+
+export function parseDashboardWindow(value: string | null | undefined): DashboardWindow {
+  return value === "7d" || value === "30d" ? value : "24h";
+}
+
+export function formatDashboardNumber(value: number): string {
+  if (value < 1000) return `${Math.round(value)}`;
+  if (value < 1_000_000) return `${formatCompact(value / 1000, 1)}k`;
+  if (value < 1_000_000_000) return `${formatCompact(value / 1_000_000, 1)}M`;
+  return `${formatCompact(value / 1_000_000_000, 1)}B`;
+}
+
+export function formatDashboardTokens(value: number): string {
+  return `${formatDashboardNumber(value)} tok`;
+}
+
+function formatCompact(value: number, fractionDigits: number): string {
+  return value.toFixed(fractionDigits).replace(/\.0$/, "");
+}

package/lib/marketplace-catalog.ts

@@ -0,0 +1,138 @@
+import type { JsonObject } from "@bufbuild/protobuf";
+import { queryOptions, useMutation, useQueries, useQuery, useQueryClient } from "@tanstack/react-query";
+import type { Connector, InstalledPlugin, PluginSummary } from "@talgent/workbench-contracts/marketplace/public/v1/marketplace_pb";
+import { marketplaceClient } from "./client";
+import { useCurrentUser } from "./account-service";
+
+// Marketplace reads and personal changes. Catalog data is platform-wide; every
+// personal query is keyed by the signed-in user so another session never
+// reuses it. A personal change also refreshes Start Work defaults.
+export const marketplaceQueryKey = ["marketplace"] as const;
+const pageSize = 100;
+
+function usePersonalKey(...parts: string[]) {
+  const userId = useCurrentUser().data?.user?.id ?? "";
+  return { key: [...marketplaceQueryKey, ...parts, userId] as const, enabled: Boolean(userId) };
+}
+
+// The catalog has a few hundred Plugins; lists group and search all of them.
+// A list carries summaries; a Plugin's full release is read by its page.
+async function listAllPlugins(signal: AbortSignal) {
+  const plugins: PluginSummary[] = [];
+  for (let cursor = ""; ;) {
+    const page = await marketplaceClient.listPlugins({ cursor, pageSize }, { signal });
+    plugins.push(...page.plugins);
+    if (!page.nextCursor) return plugins;
+    cursor = page.nextCursor;
+  }
+}
+
+// `enabled: false` defers a read until a surface needs it, such as the account
+// menu, which loads what the person installed only once they reach for it.
+type ReadOptions = { enabled?: boolean };
+
+export function usePluginCatalog() {
+  return useQuery({ queryKey: [...marketplaceQueryKey, "plugins"], queryFn: ({ signal }) => listAllPlugins(signal), retry: false, staleTime: 60_000 });
+}
+
+function pluginQuery(slug: string) {
+  return queryOptions({ queryKey: [...marketplaceQueryKey, "plugin", slug], queryFn: async ({ signal }) => {
+    const response = await marketplaceClient.getPlugin({ slug }, { signal });
+    if (!response.plugin) throw new Error("The Plugin response is missing");
+    return response.plugin;
+  }, retry: false });
+}
+
+export function usePlugin(slug: string) {
+  return useQuery(pluginQuery(slug));
+}
+
+/** The releases of a few Plugins by slug, sharing each Plugin page's cache. */
+export function usePluginReleases(slugs: string[]) {
+  const results = useQueries({ queries: slugs.map(slug => pluginQuery(slug)) });
+  return new Map(results.flatMap((result, index) => result.data ? [[slugs[index], result.data] as const] : []));
+}
+
+export function useInstalledPlugins(options: ReadOptions = {}) {
+  const { key, enabled } = usePersonalKey("installed-plugins");
+  return useQuery({ queryKey: key, enabled: enabled && options.enabled !== false, retry: false, queryFn: async ({ signal }) => {
+    const installed = new Map<string, InstalledPlugin>();
+    for (let cursor = ""; ;) {
+      const page = await marketplaceClient.listInstalledPlugins({ cursor, pageSize }, { signal });
+      for (const plugin of page.plugins) installed.set(plugin.slug, plugin);
+      if (!page.nextCursor) return installed;
+      cursor = page.nextCursor;
+    }
+  } });
+}
+
+export function useConnectors() {
+  const { key, enabled } = usePersonalKey("connectors");
+  return useQuery({ queryKey: key, enabled, retry: false, queryFn: async ({ signal }) => (await marketplaceClient.listConnectors({}, { signal })).connectors });
+}
+
+export function useInstalledConnectors(options: ReadOptions = {}) {
+  const { key, enabled } = usePersonalKey("installed-connectors");
+  return useQuery({ queryKey: key, enabled: enabled && options.enabled !== false, retry: false, queryFn: async ({ signal }) => (await marketplaceClient.listInstalledConnectors({}, { signal })).connectors });
+}
+
+export function useConnector(name: string) {
+  const { key, enabled } = usePersonalKey("connector", name);
+  return useQuery({ queryKey: key, enabled, retry: false, queryFn: ({ signal }) => marketplaceClient.getConnector({ name }, { signal }) });
+}
+
+function useRefreshPersonal() {
+  const cache = useQueryClient();
+  return () => Promise.all([
+    cache.invalidateQueries({ queryKey: marketplaceQueryKey }),
+    cache.invalidateQueries({ queryKey: ["work-start-options"] }),
+  ]);
+}
+
+export function usePluginActions() {
+  const refresh = useRefreshPersonal();
+  const install = useMutation({ mutationFn: async ({ slug, configuration }: { slug: string; configuration: JsonObject }) => {
+    const response = await marketplaceClient.installPlugin({ slug, configuration });
+    if (response.plugin?.slug !== slug) throw new Error("The installation was not confirmed");
+    return response.plugin;
+  }, onSettled: refresh });
+  const setEnabled = useMutation({ mutationFn: async ({ installed, enabled }: { installed: InstalledPlugin; enabled: boolean }) => {
+    const request = { slug: installed.slug, version: installed.version };
+    await (enabled ? marketplaceClient.enablePlugin(request) : marketplaceClient.disablePlugin(request));
+  }, onSettled: refresh });
+  // Setting merges; settings the user cleared are deleted afterwards.
+  const configure = useMutation({ mutationFn: async ({ installed, values, cleared = [] }: { installed: InstalledPlugin; values: JsonObject; cleared?: string[] }) => {
+    let version = installed.version;
+    if (Object.keys(values).length || !cleared.length) version = (await marketplaceClient.setPluginConfiguration({ slug: installed.slug, version, values })).plugin?.version ?? version;
+    if (cleared.length) await marketplaceClient.deletePluginConfiguration({ slug: installed.slug, version, names: cleared });
+  }, onSettled: refresh });
+  const uninstall = useMutation({ mutationFn: (installed: InstalledPlugin) => marketplaceClient.uninstallPlugin({ slug: installed.slug, version: installed.version }), onSettled: refresh });
+  return { install, setEnabled, configure, uninstall };
+}
+
+export function useConnectorActions() {
+  const refresh = useRefreshPersonal();
+  const install = useMutation({ mutationFn: async (name: string) => {
+    const response = await marketplaceClient.installConnector({ name });
+    if (response.connector?.name !== name) throw new Error("The installation was not confirmed");
+    return response.connector;
+  }, onSettled: refresh });
+  const setEnabled = useMutation({ mutationFn: async ({ connector, enabled }: { connector: Connector; enabled: boolean }) => {
+    const request = { name: connector.name, version: connector.installationVersion };
+    await (enabled ? marketplaceClient.enableConnector(request) : marketplaceClient.disableConnector(request));
+  }, onSettled: refresh });
+  const uninstall = useMutation({ mutationFn: (connector: Connector) => marketplaceClient.uninstallConnector({ name: connector.name, version: connector.installationVersion }), onSettled: refresh });
+  return { install, setEnabled, uninstall };
+}
+
+// Status vocabulary shared by Plugins and Connectors.
+export type InstallStatus = "always_enabled" | "enabled" | "disabled" | "not_installed";
+export const installStatusLabel: Record<InstallStatus, string> = { always_enabled: "Always enabled", enabled: "Enabled", disabled: "Disabled", not_installed: "Not installed" };
+
+export function pluginStatus(required: boolean, installed?: InstalledPlugin): InstallStatus {
+  if (required) return "always_enabled";
+  if (!installed) return "not_installed";
+  return installed.enabled ? "enabled" : "disabled";
+}
+
+export const connectorStatus = (connector: Connector) => connector.status as InstallStatus;

package/lib/marketplace-connections.ts

@@ -0,0 +1,98 @@
+import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { marketplaceClient } from "./client";
+import { useCurrentUser } from "./account-service";
+import { marketplaceQueryKey } from "./marketplace-catalog";
+import { notify } from "./notifications";
+
+// Provider authorization is a round trip through the Provider. The GitHub App
+// registers /profile as its callback URL, so the redirect always returns there;
+// the page that started the connection is remembered and restored afterwards.
+// Removal condition: once the App's callback URL is the Provider page, pass
+// that page as the redirect and drop the remembered return path.
+export const providerCallbackPath = "/profile";
+const returnKey = "talgent.providerAuthorization.return";
+
+export const providerNames: Record<string, string> = { github: "GitHub" };
+export const providerName = (provider: string) => providerNames[provider] ?? provider;
+// Providers supported by the platform. Only GitHub exists today.
+export const supportedProviders = ["github"] as const;
+
+const callbackURI = () => `${window.location.origin}${providerCallbackPath}`;
+
+/** The connection's stored status only, without asking the Provider what it reaches. */
+export function useProviderConnection(provider: string) {
+  const userId = useCurrentUser().data?.user?.id ?? "";
+  return useQuery({ queryKey: [...marketplaceQueryKey, "provider-state", provider, userId], enabled: Boolean(userId), retry: false,
+    queryFn: ({ signal }) => marketplaceClient.getProviderConnectionState({ provider }, { signal }) });
+}
+
+const providerAccessKey = (provider: string, userId: string) => [...marketplaceQueryKey, "provider", provider, userId];
+
+/** The connection and its reach (accounts, permissions) as last seen; reading never asks the Provider. */
+export function useProviderAccess(provider: string) {
+  const userId = useCurrentUser().data?.user?.id ?? "";
+  return useQuery({ queryKey: providerAccessKey(provider, userId), enabled: Boolean(userId), retry: false,
+    queryFn: ({ signal }) => marketplaceClient.getProviderAccess({ provider }, { signal }) });
+}
+
+/** Asks the Provider now what the authorization reaches; the page then shows the result. */
+export function useRefreshProviderAccess(provider: string) {
+  const userId = useCurrentUser().data?.user?.id ?? "";
+  const cache = useQueryClient();
+  return useMutation({
+    mutationFn: async () => {
+      const response = await marketplaceClient.refreshProviderAccess({ provider });
+      if (!response.access) throw new Error("The refreshed access is missing");
+      return response.access;
+    },
+    onSuccess: access => {
+      cache.setQueryData(providerAccessKey(provider, userId), access);
+      return cache.invalidateQueries({ queryKey: ["work-start-repositories"] });
+    },
+    onError: () => notify(`provider:${provider}`, "danger", `${providerName(provider)} couldn’t be checked`, "Try again in a moment."),
+  });
+}
+
+// Starts connecting; the browser leaves for the Provider on success.
+export function useConnectProvider() {
+  return useMutation({
+    mutationFn: async ({ provider, returnTo }: { provider: string; returnTo: string }) => {
+      const response = await marketplaceClient.beginProviderAuthorization({ provider, redirectUri: callbackURI() });
+      if (!response.authorizationUrl) throw new Error("The authorization address is missing");
+      window.sessionStorage.setItem(returnKey, returnTo);
+      return response.authorizationUrl;
+    },
+    onSuccess: url => window.location.assign(url),
+    onError: (_, { provider }) => notify(`provider:${provider}`, "danger", `${providerName(provider)} couldn’t be opened`, "Try connecting again."),
+  });
+}
+
+// The page that started connecting, read once.
+export function takeProviderReturn(provider: string) {
+  const returnTo = window.sessionStorage.getItem(returnKey) || `/marketplace/providers/${provider}`;
+  window.sessionStorage.removeItem(returnKey);
+  return returnTo;
+}
+
+// Completes a returned authorization and reports where the user started.
+export async function completeProviderAuthorization(provider: string, code: string, state: string) {
+  const response = await marketplaceClient.completeProviderAuthorization({ provider, code, state, redirectUri: callbackURI() });
+  if (!response.authorization) throw new Error("The authorization is missing");
+  return { authorization: response.authorization, returnTo: takeProviderReturn(provider) };
+}
+
+// Disconnecting asks the Provider to revoke; success means it was confirmed.
+export function useDisconnectProvider() {
+  const cache = useQueryClient();
+  return useMutation({
+    mutationFn: async (authorizationId: string) => {
+      const response = await marketplaceClient.cancelPersonalAuthorization({ authorizationId });
+      if (response.authorization?.id !== authorizationId || response.authorization.status !== "revoked") throw new Error("Revocation was not confirmed");
+    },
+    onSettled: () => Promise.all([cache.invalidateQueries({ queryKey: marketplaceQueryKey }), cache.invalidateQueries({ queryKey: ["work-start-options"] }), cache.invalidateQueries({ queryKey: ["work-start-repositories"] })]),
+  });
+}
+
+// Display names for services whose catalog name is a lowercase identifier.
+const serviceNames: Record<string, string> = { github: "GitHub", talgent: "Talgent" };
+export const serviceLabel = (name: string) => serviceNames[name] ?? name.split(/[-_]/).map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");

package/lib/marketplace-plugins.ts

@@ -0,0 +1,53 @@
+import type { PluginRelease } from "@talgent/workbench-contracts/marketplace/public/v1/marketplace_pb";
+
+/** What presenting a Plugin needs; a full release and a catalog summary both carry it. */
+export type PresentablePlugin = Pick<PluginRelease, "slug" | "source" | "nativeEntry">;
+
+export function pluginDisplayName(slug: string): string {
+  return slug.split("-").map(word => word.charAt(0).toUpperCase() + word.slice(1)).join(" ");
+}
+
+function nativeObject(bytes: Uint8Array): Record<string, unknown> | undefined {
+  try {
+    const value: unknown = JSON.parse(new TextDecoder().decode(bytes));
+    return value !== null && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : undefined;
+  } catch { return undefined; }
+}
+
+const text = (value: unknown) => typeof value === "string" && value.trim() ? value.trim() : "";
+
+// Presentation comes from the release's native marketplace entry.
+export function pluginPresentation(plugin: PresentablePlugin) {
+  const entry = nativeObject(plugin.nativeEntry);
+  const author = entry?.author;
+  const keywords = Array.isArray(entry?.keywords) ? entry.keywords : Array.isArray(entry?.tags) ? entry.tags : [];
+  const homepage = text(entry?.homepage) || text(entry?.repository);
+  return {
+    name: text(entry?.displayName) || pluginDisplayName(plugin.slug),
+    category: text(entry?.category) ? pluginDisplayName(text(entry?.category)) : "Other",
+    author: text(author) || (author && typeof author === "object" ? text((author as Record<string, unknown>).name) : ""),
+    license: text(entry?.license),
+    homepage: /^https:\/\//.test(homepage) ? homepage : "",
+    keywords: keywords.filter((word): word is string => typeof word === "string" && Boolean(word.trim())),
+  };
+}
+
+// The core runtime Plugin is required by every person's Agent definition; it
+// is always enabled and cannot be installed or removed personally.
+export const platformPluginSlugs: readonly string[] = ["talgent-runtime"];
+export const isPlatformPlugin = (slug: string) => platformPluginSlugs.includes(slug);
+
+export function groupPluginsByCategory<T extends PresentablePlugin>(plugins: T[]) {
+  const groups = new Map<string, T[]>();
+  for (const plugin of plugins) {
+    const { category } = pluginPresentation(plugin);
+    const entries = groups.get(category) ?? [];
+    entries.push(plugin);
+    groups.set(category, entries);
+  }
+  return [...groups].sort(([left], [right]) => {
+    if (left === "Other") return 1;
+    if (right === "Other") return -1;
+    return left.localeCompare(right);
+  }).map(([category, entries]) => ({ category, plugins: entries }));
+}

package/lib/marketplace-routes.ts

@@ -0,0 +1,12 @@
+// Marketplace is pages only; depth lives in these paths and the topbar trail.
+const encode = encodeURIComponent;
+export const marketplacePaths = {
+  plugins: "/marketplace",
+  pluginCategory: (category: string) => `/marketplace/plugins/categories/${encode(category)}`,
+  plugin: (slug: string) => `/marketplace/plugins/${encode(slug)}`,
+  connectors: "/marketplace/connectors",
+  connectorCategory: (category: string) => `/marketplace/connectors/categories/${encode(category)}`,
+  connector: (name: string) => `/marketplace/connectors/${encode(name)}`,
+  providers: "/marketplace/providers",
+  provider: (id: string) => `/marketplace/providers/${encode(id)}`,
+};