@loopbacktools/app 0.0.0-stage → 0.4.1

package/src/app.tsx

@@ -0,0 +1,335 @@
+import {
+	Button,
+	ClipboardText,
+	Empty,
+	type LinkComponentProps,
+	LinkButton,
+	LinkProvider,
+	Loader,
+	Text,
+} from "@cloudflare/kumo";
+import { useAtomValue } from "@effect/atom-react";
+import { Inbox, InboxProvider } from "@loopbacktools/inbox";
+import type { LoopbackApi } from "@loopbacktools/sdk";
+import { Plus, Tray } from "@phosphor-icons/react";
+import { AsyncResult, Atom } from "effect/reactivity";
+import {
+	type ComponentType,
+	createContext,
+	forwardRef,
+	type ReactNode,
+	use,
+	useCallback,
+	useEffect,
+} from "react";
+import {
+	BrowserRouter,
+	Link,
+	Navigate,
+	Route,
+	Routes,
+	useLocation,
+	useNavigate,
+	useParams,
+	useSearchParams,
+} from "react-router";
+import { Header } from "./header.tsx";
+import { loadPage } from "./location.ts";
+import { Page, Section } from "./page.tsx";
+import { askInOldLink, safeNext, workspacePath } from "./paths.ts";
+import type { LoopbackAppOptions, SignedIn as Signed } from "./ports.ts";
+
+function Waiting() {
+	return (
+		<main className="flex h-full items-center justify-center">
+			<Loader />
+		</main>
+	);
+}
+
+/** Kumo's links, followed by the app's router rather than by loading the page again. */
+const RouterLink = forwardRef<HTMLAnchorElement, LinkComponentProps>(
+	({ href, to, ...rest }, ref) => <Link ref={ref} to={href ?? to ?? ""} {...rest} />,
+);
+
+const SignedInContext = createContext<Signed | null>(null);
+
+/** Who is signed in, for a page behind `SignedIn`. */
+const useSignedInHere = (): Signed => {
+	const signedIn = use(SignedInContext);
+	if (signedIn === null) throw new Error("Only a page for someone signed in knows who they are.");
+	return signedIn;
+};
+
+/** A workspace that isn't the person's: they may have been removed, or the link is wrong. */
+function NotTheirs() {
+	return (
+		<main className="flex h-full items-center justify-center p-4">
+			<Empty
+				icon={<Tray size={32} />}
+				title="Not one of your workspaces"
+				description="You may have been removed from it, or the link is wrong."
+				contents={
+					<LinkButton href="/" variant="secondary">
+						Go to your inbox
+					</LinkButton>
+				}
+			/>
+		</main>
+	);
+}
+
+/** How agents sign in to a client's deployment, as its server says. */
+const agentSignInAtom = Atom.family((client: LoopbackApi) => Atom.make(client.agentSignIn));
+
+/** How to connect an agent to a workspace, as the server says its agents sign in. */
+function Connect({
+	workspace,
+	client,
+}: {
+	readonly workspace: string;
+	readonly client: LoopbackApi;
+}) {
+	const signIn = useAtomValue(agentSignInAtom(client));
+	if (AsyncResult.isInitial(signIn)) return <Waiting />;
+	const mcp = `${window.location.origin}/mcp`;
+	const oauth = AsyncResult.isSuccess(signIn) && signIn.value === "oauth";
+	return (
+		<Page
+			back={{ to: workspacePath(workspace), label: "Back to the inbox" }}
+			title="Connect an agent"
+			description={
+				oauth
+					? "Agents connect to Loopback over MCP and sign in as you. When one connects, you pick the workspace it asks in."
+					: "Agents connect to Loopback over MCP, sending this deployment's token."
+			}
+		>
+			<Section title="Claude Code">
+				<ClipboardText
+					text={
+						oauth
+							? `claude mcp add --transport http loopback ${mcp}`
+							: `claude mcp add --transport http loopback ${mcp} --header "Authorization: Bearer $LOOPBACK_TOKEN"`
+					}
+				/>
+				<Text variant="secondary" size="sm">
+					{oauth
+						? "Then run /mcp in Claude Code and sign in when it asks."
+						: "With the token in LOOPBACK_TOKEN, in the shell you run it from."}
+				</Text>
+			</Section>
+			<Section title="Any other MCP client">
+				<ClipboardText text={mcp} />
+				<Text variant="secondary" size="sm">
+					{oauth
+						? "Add it as a remote server over streamable HTTP. It signs in with OAuth."
+						: "Add it as a remote server over streamable HTTP, with the header Authorization: Bearer and the token."}
+				</Text>
+			</Section>
+		</Page>
+	);
+}
+
+const noPreference = (): string | undefined => undefined;
+
+/**
+ * The Loopback app, for a deployment to render: its inbox, a page on connecting agents, and the
+ * deployment's own pages, routed by path. Render it inside a `RegistryProvider`, as the inbox needs.
+ * The deployment's hooks are bound here, once: the app's pages call the same ones on every render.
+ */
+export const createLoopbackApp = (options: LoopbackAppOptions): ComponentType => {
+	const { SignIn, continueAt } = options.session;
+	const useSignedIn = options.session.useSignedIn;
+	const useList = options.workspaces.useList;
+	const usePreferred = options.workspaces.usePreferred ?? noPreference;
+	const useClient = options.workspaces.useClient;
+	const { create } = options.workspaces;
+	const { pages = [], workspaceMenu, accountMenu = [], Banner } = options.extensions ?? {};
+
+	/** A page for someone signed in; anyone else is sent to sign in, and brought back after. */
+	function SignedIn({ children }: { readonly children: ReactNode }) {
+		const signedIn = useSignedIn();
+		const location = useLocation();
+		if (signedIn === undefined) return <Waiting />;
+		if (signedIn === null) {
+			const next = `${location.pathname}${location.search}${location.hash}`;
+			return <Navigate to={`/sign-in?next=${encodeURIComponent(next)}`} replace />;
+		}
+		return <SignedInContext value={signedIn}>{children}</SignedInContext>;
+	}
+
+	/**
+	 * The deployment's sign-in page, until the person is signed in; then where they were going: a
+	 * page of the server's the deployment names, loaded in full, or else `next`.
+	 */
+	function SignInPage() {
+		const signedIn = useSignedIn();
+		const [search] = useSearchParams();
+		const next = safeNext(search.get("next"));
+		const onward = signedIn == null ? undefined : continueAt?.(search);
+		useEffect(() => {
+			if (onward !== undefined) loadPage(onward);
+		}, [onward]);
+		if (signedIn === undefined || onward !== undefined) return <Waiting />;
+		if (signedIn !== null) return <Navigate to={next} replace />;
+		return <SignIn next={next} />;
+	}
+
+	/**
+	 * The app's front door: the workspace the person prefers, or their first, and the ask an old link
+	 * names in it. Someone in no workspace is offered a new one, where the deployment makes them.
+	 */
+	function Home() {
+		const navigate = useNavigate();
+		const location = useLocation();
+		const list = useList();
+		const preferred = usePreferred();
+		if (list === undefined) return <Waiting />;
+		const workspace = list.find((candidate) => candidate.id === preferred)?.id ?? list[0]?.id;
+		if (workspace !== undefined) {
+			return <Navigate to={workspacePath(workspace, askInOldLink(location.hash))} replace />;
+		}
+		return (
+			<main className="flex h-full items-center justify-center p-4">
+				<Empty
+					icon={<Tray size={32} />}
+					title="You're not in a workspace"
+					description={
+						create === undefined
+							? "Ask someone to invite you to theirs."
+							: "Make one to connect your agents to, or ask someone to invite you to theirs."
+					}
+					contents={
+						create === undefined ? undefined : (
+							<Button
+								variant="primary"
+								icon={<Plus />}
+								onClick={() =>
+									void create().then(async (id) => {
+										if (id !== undefined) await navigate(workspacePath(id));
+									})
+								}
+							>
+								New workspace
+							</Button>
+						)
+					}
+				/>
+			</main>
+		);
+	}
+
+	/**
+	 * One workspace's inbox, live, through the client the deployment gives for it. Another workspace
+	 * is another client, so switching reconnects to that one.
+	 */
+	function WorkspaceInbox({
+		workspace,
+		list,
+	}: {
+		readonly workspace: string;
+		readonly list: readonly { readonly id: string; readonly name: string }[];
+	}) {
+		const signedIn = useSignedInHere();
+		const client = useClient(workspace);
+		const { askId } = useParams();
+		const navigate = useNavigate();
+		const onSelect = useCallback(
+			(id: string | null) => void navigate(workspacePath(workspace, id ?? undefined)),
+			[navigate, workspace],
+		);
+		const hrefFor = useCallback((id: string) => workspacePath(workspace, id), [workspace]);
+		return (
+			<InboxProvider client={client}>
+				<div className="flex h-full flex-col">
+					<Header
+						workspace={workspace}
+						signedIn={signedIn}
+						workspaces={list}
+						workspaceItems={workspaceMenu?.(workspace) ?? []}
+						accountItems={accountMenu}
+						create={create}
+					/>
+					{Banner === undefined ? null : <Banner workspace={workspace} />}
+					<Inbox selectedId={askId ?? null} onSelect={onSelect} hrefFor={hrefFor} />
+				</div>
+			</InboxProvider>
+		);
+	}
+
+	function ConnectPage({ workspace }: { readonly workspace: string }) {
+		return <Connect workspace={workspace} client={useClient(workspace)} />;
+	}
+
+	/** A page of one of the person's workspaces, or a page saying it isn't one of theirs. */
+	function Theirs({ page }: { readonly page: "inbox" | "connect" }) {
+		const { workspace = "" } = useParams();
+		const list = useList();
+		if (list === undefined) return <Waiting />;
+		if (!list.some((candidate) => candidate.id === workspace)) return <NotTheirs />;
+		return page === "inbox" ? (
+			<WorkspaceInbox workspace={workspace} list={list} />
+		) : (
+			<ConnectPage workspace={workspace} />
+		);
+	}
+
+	return function LoopbackApp() {
+		return (
+			<BrowserRouter>
+				<LinkProvider component={RouterLink}>
+					<Routes>
+						<Route path="/sign-in" element={<SignInPage />} />
+						<Route
+							path="/w/:workspace"
+							element={
+								<SignedIn>
+									<Theirs page="inbox" />
+								</SignedIn>
+							}
+						/>
+						<Route
+							path="/w/:workspace/asks/:askId"
+							element={
+								<SignedIn>
+									<Theirs page="inbox" />
+								</SignedIn>
+							}
+						/>
+						<Route
+							path="/w/:workspace/connect"
+							element={
+								<SignedIn>
+									<Theirs page="connect" />
+								</SignedIn>
+							}
+						/>
+						{pages.map(({ path, Page: Shown, signedIn }) => (
+							<Route
+								key={path}
+								path={path}
+								element={
+									signedIn ? (
+										<SignedIn>
+											<Shown />
+										</SignedIn>
+									) : (
+										<Shown />
+									)
+								}
+							/>
+						))}
+						<Route
+							path="*"
+							element={
+								<SignedIn>
+									<Home />
+								</SignedIn>
+							}
+						/>
+					</Routes>
+				</LinkProvider>
+			</BrowserRouter>
+		);
+	};
+};

package/src/header.tsx

@@ -0,0 +1,196 @@
+import { Button, DropdownMenu, LinkButton, Text } from "@cloudflare/kumo";
+import { useAttention, useInbox, useNotifications } from "@loopbacktools/inbox";
+import { Bell, BellSlash, CaretDown, Check, Plugs, Plus, SignOut } from "@phosphor-icons/react";
+import { useCallback } from "react";
+import { Link, useNavigate } from "react-router";
+import { connectPath, workspacePath } from "./paths.ts";
+import type { MenuItem, SignedIn, WorkspaceSummary } from "./ports.ts";
+
+const CONNECTION = {
+	connecting: { label: "Connecting", tone: "bg-kumo-line" },
+	live: { label: "Live", tone: "bg-kumo-success" },
+	reconnecting: { label: "Reconnecting", tone: "bg-kumo-warning" },
+} as const;
+
+/** Goes where a menu item goes, or does what it does. */
+const useChoose = () => {
+	const navigate = useNavigate();
+	return (item: MenuItem) => {
+		if (item.to !== undefined) void navigate(item.to);
+		void item.onSelect?.();
+	};
+};
+
+/**
+ * The workspace open, and the way to the others: only where there is more than one, or a way to make
+ * one, or the deployment has items of its own for it.
+ */
+function WorkspaceMenu({
+	workspace,
+	list,
+	items,
+	create,
+}: {
+	readonly workspace: string;
+	readonly list: readonly WorkspaceSummary[];
+	readonly items: readonly MenuItem[];
+	readonly create: (() => Promise<string | undefined>) | undefined;
+}) {
+	const navigate = useNavigate();
+	const choose = useChoose();
+	if (list.length < 2 && create === undefined && items.length === 0) return null;
+	const current = list.find((candidate) => candidate.id === workspace);
+	const make = async () => {
+		const id = await create?.();
+		if (id !== undefined) await navigate(workspacePath(id));
+	};
+	return (
+		<DropdownMenu>
+			<DropdownMenu.Trigger>
+				<Button variant="ghost" size="sm" icon={<CaretDown />}>
+					{current?.name ?? "Workspace"}
+				</Button>
+			</DropdownMenu.Trigger>
+			<DropdownMenu.Content>
+				{list.map((candidate) => (
+					<DropdownMenu.Item
+						key={candidate.id}
+						icon={candidate.id === workspace ? Check : undefined}
+						onClick={() => void navigate(workspacePath(candidate.id))}
+					>
+						{candidate.name}
+					</DropdownMenu.Item>
+				))}
+				{items.length > 0 || create !== undefined ? <DropdownMenu.Separator /> : null}
+				{items.map((item) => (
+					<DropdownMenu.Item key={item.label} icon={item.icon} onClick={() => choose(item)}>
+						{item.label}
+					</DropdownMenu.Item>
+				))}
+				{create === undefined ? null : (
+					<DropdownMenu.Item icon={Plus} onClick={() => void make()}>
+						New workspace
+					</DropdownMenu.Item>
+				)}
+			</DropdownMenu.Content>
+		</DropdownMenu>
+	);
+}
+
+/**
+ * The person signed in: a menu of the deployment's items and signing out. With no items and no name
+ * to show, signing out is a button of its own, and with nothing to sign out of either, there is none.
+ */
+function AccountMenu({
+	signedIn,
+	items,
+}: {
+	readonly signedIn: SignedIn;
+	readonly items: readonly MenuItem[];
+}) {
+	const navigate = useNavigate();
+	const choose = useChoose();
+	const { name, signOut } = signedIn;
+	const leave =
+		signOut === undefined
+			? undefined
+			: async () => {
+					await signOut();
+					await navigate("/");
+				};
+	if (items.length === 0 && name === undefined) {
+		return leave === undefined ? null : (
+			<Button variant="ghost" size="sm" onClick={() => void leave()}>
+				Sign out
+			</Button>
+		);
+	}
+	return (
+		<DropdownMenu>
+			<DropdownMenu.Trigger>
+				<Button variant="ghost" size="sm">
+					{name ?? "Account"}
+				</Button>
+			</DropdownMenu.Trigger>
+			<DropdownMenu.Content>
+				{items.map((item) => (
+					<DropdownMenu.Item key={item.label} icon={item.icon} onClick={() => choose(item)}>
+						{item.label}
+					</DropdownMenu.Item>
+				))}
+				{leave === undefined ? null : (
+					<>
+						{items.length > 0 ? <DropdownMenu.Separator /> : null}
+						<DropdownMenu.Item icon={SignOut} onClick={() => void leave()}>
+							Sign out
+						</DropdownMenu.Item>
+					</>
+				)}
+			</DropdownMenu.Content>
+		</DropdownMenu>
+	);
+}
+
+/** The bar above a workspace's inbox. */
+export function Header({
+	workspace,
+	signedIn,
+	workspaces,
+	workspaceItems,
+	accountItems,
+	create,
+}: {
+	readonly workspace: string;
+	readonly signedIn: SignedIn;
+	/** Every workspace the person can open. */
+	readonly workspaces: readonly WorkspaceSummary[];
+	readonly workspaceItems: readonly MenuItem[];
+	readonly accountItems: readonly MenuItem[];
+	readonly create: (() => Promise<string | undefined>) | undefined;
+}) {
+	const navigate = useNavigate();
+	const inbox = useInbox();
+	const notifications = useNotifications();
+	const open = useCallback(
+		(askId: string) => void navigate(workspacePath(workspace, askId)),
+		[navigate, workspace],
+	);
+	useAttention(inbox, notifications.enabled, open);
+	const connection = CONNECTION[inbox.status];
+	return (
+		<header className="flex items-center gap-2 border-b border-kumo-line bg-kumo-base px-4 py-2">
+			<Link to={workspacePath(workspace)} className="flex items-center gap-2">
+				<img src="/favicon.svg" alt="" className="size-6" />
+				<Text bold>Loopback</Text>
+			</Link>
+			<WorkspaceMenu
+				workspace={workspace}
+				list={workspaces}
+				items={workspaceItems}
+				create={create}
+			/>
+			<span className="inline-flex items-center gap-1.5 text-xs text-kumo-subtle">
+				<span className={`size-2 rounded-full ${connection.tone}`} />
+				{connection.label}
+			</span>
+			<span className="ml-auto flex items-center gap-1">
+				<LinkButton href={connectPath(workspace)} variant="ghost" size="sm" icon={<Plugs />}>
+					Connect an agent
+				</LinkButton>
+				{notifications.supported ? (
+					<Button
+						variant="ghost"
+						size="sm"
+						shape="square"
+						aria-label={
+							notifications.enabled ? "Turn notifications off" : "Notify me when an agent asks"
+						}
+						icon={notifications.enabled ? <Bell /> : <BellSlash />}
+						onClick={() => void notifications.toggle()}
+					/>
+				) : null}
+				<AccountMenu signedIn={signedIn} items={accountItems} />
+			</span>
+		</header>
+	);
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+export { createLoopbackApp } from "./app.tsx";
+export { Page, Section } from "./page.tsx";
+export { connectPath, workspacePath } from "./paths.ts";
+export type {
+	ExtensionPage,
+	Extensions,
+	LoopbackAppOptions,
+	MenuItem,
+	Session,
+	SignedIn,
+	Workspaces,
+	WorkspaceSummary,
+} from "./ports.ts";
+export { followSystemTheme } from "./theme.ts";

package/src/location.ts

@@ -0,0 +1,2 @@
+/** Loads a page in full, as one of the server's own pages needs, rather than routing to it. */
+export const loadPage = (url: string): void => window.location.assign(url);

package/src/page.tsx

@@ -0,0 +1,62 @@
+import { Text } from "@cloudflare/kumo";
+import type { ReactNode } from "react";
+import { Link } from "react-router";
+
+/** A page of its own, off the inbox: a way back, a heading, and its sections. */
+export function Page({
+	back,
+	title,
+	description,
+	children,
+}: {
+	readonly back: { readonly to: string; readonly label: string };
+	readonly title: string;
+	readonly description?: string;
+	readonly children: ReactNode;
+}) {
+	return (
+		<main className="mx-auto flex max-w-2xl flex-col gap-6 px-4 py-10">
+			<Link to={back.to} className="text-sm text-kumo-subtle">
+				← {back.label}
+			</Link>
+			<div className="flex flex-col gap-2">
+				<Text variant="heading" as="h1">
+					{title}
+				</Text>
+				{description === undefined ? null : <Text variant="secondary">{description}</Text>}
+			</div>
+			{children}
+		</main>
+	);
+}
+
+/** One part of a page: a card with a heading. A dangerous one is bordered in red. */
+export function Section({
+	title,
+	description,
+	danger = false,
+	children,
+}: {
+	readonly title: string;
+	readonly description?: string | undefined;
+	readonly danger?: boolean;
+	readonly children: ReactNode;
+}) {
+	return (
+		<section
+			className={`flex flex-col gap-4 rounded-xl border bg-kumo-elevated p-5 ${
+				danger ? "border-kumo-danger" : "border-kumo-line"
+			}`}
+		>
+			<div className="flex flex-col gap-1">
+				<Text bold>{title}</Text>
+				{description === undefined ? null : (
+					<Text variant="secondary" size="sm">
+						{description}
+					</Text>
+				)}
+			</div>
+			{children}
+		</section>
+	);
+}

package/src/paths.ts

@@ -0,0 +1,21 @@
+/** Where a workspace's inbox, or one ask in it, is in the app. */
+export const workspacePath = (workspace: string, askId?: string): string =>
+	`/w/${encodeURIComponent(workspace)}${askId === undefined ? "" : `/asks/${encodeURIComponent(askId)}`}`;
+
+/** Where the page on connecting an agent to a workspace is. */
+export const connectPath = (workspace: string): string => `${workspacePath(workspace)}/connect`;
+
+/**
+ * Where to send someone once they have signed in: a path in this app, never another site, so a link
+ * to the sign-in page can't be made to send people elsewhere.
+ */
+export const safeNext = (next: string | null): string =>
+	next !== null && next.startsWith("/") && !next.startsWith("//") && !next.startsWith("/\\")
+		? next
+		: "/";
+
+/** The ask an old link names, from before links had paths: `/#/<id>`. */
+export const askInOldLink = (hash: string): string | undefined => {
+	const id = /^#\/(.+)$/.exec(hash)?.[1];
+	return id === undefined ? undefined : decodeURIComponent(id);
+};