Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
feat: improve onboarding UX with guided tour and step indicators
Gener8534a2b1d01e
diff --git a/pnpm-lock.yaml b/pnpm-lock.yamlindex f95a5ebec..d4f7fa1c9 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -185,6 +185,9 @@ importers:clsx:specifier: ^2.1.1version: 2.1.1+ driver.js:+ specifier: ^1.4.0+ version: 1.4.0embla-carousel-autoplay:specifier: ^8.6.0version: 8.6.0([email protected])@@ -3768,6 +3771,9 @@ packages:resolution: {integrity: sha512-nI4U3TottKAcAD9LLud4Cb7b2QztQMUEfHbvhTH09bqXTxnSie8WnjPALV/WMCrJZ6UV/qHJ6L03OqO3LcdYZw==}engines: {node: '>=12'}+ resolution: {integrity: sha512-Gm64jm6PmcU+si21sQhBrTAM1JvUrR0QhNmjkprNLxohOBzul9+pNHXgQaT9lW84gwg9GMLB3NZGuGolsz5uew==}+resolution: {integrity: sha512-kY0BSaTNYWnoDMVoyY8uxmyHjpJW1geOmBMdSSicKo9CIIWkSxMIj2rkeSR51b8KAPB7m+qysjuHme5nKP+E5Q==}peerDependencies:@@ -10871,6 +10877,8 @@ snapshots:+ [email protected]: {}+[email protected](@cloudflare/[email protected])(@opentelemetry/[email protected])([email protected])([email protected]):optionalDependencies:'@cloudflare/workers-types': 4.20260504.1@@ -11128,7 +11136,7 @@ snapshots:'@next/eslint-plugin-next': 16.2.4eslint: 9.39.4([email protected])eslint-import-resolver-node: 0.3.10- eslint-import-resolver-typescript: 3.10.1([email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected])))([email protected]([email protected]))+ eslint-import-resolver-typescript: 3.10.1([email protected])([email protected]([email protected]))eslint-plugin-import: 2.32.0(@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected])([email protected]([email protected]))eslint-plugin-jsx-a11y: 6.10.2([email protected]([email protected]))eslint-plugin-react: 7.37.5([email protected]([email protected]))@@ -11151,7 +11159,7 @@ snapshots:transitivePeerDependencies:- supports-color- [email protected]([email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected])))([email protected]([email protected])):dependencies:'@nolyfill/is-core-module': 1.0.39debug: 4.4.3@@ -11166,14 +11174,14 @@ snapshots:transitivePeerDependencies:- supports-color- [email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected])([email protected]([email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected])))([email protected]([email protected])))([email protected]([email protected])):+ [email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected])([email protected])([email protected]([email protected])):dependencies:debug: 3.2.7optionalDependencies:eslint: 9.39.4([email protected])eslint-import-resolver-node: 0.3.10- eslint-import-resolver-typescript: 3.10.1([email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected])))([email protected]([email protected]))+ eslint-import-resolver-typescript: 3.10.1([email protected])([email protected]([email protected]))transitivePeerDependencies:- supports-color@@ -11188,7 +11196,7 @@ snapshots:doctrine: 2.1.0eslint: 9.39.4([email protected])eslint-import-resolver-node: 0.3.10- eslint-module-utils: 2.12.1(@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected])([email protected]([email protected](@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected]([email protected])))([email protected]([email protected])))([email protected]([email protected]))+ eslint-module-utils: 2.12.1(@typescript-eslint/[email protected]([email protected]([email protected]))([email protected]))([email protected])([email protected])([email protected]([email protected]))hasown: 2.0.3is-core-module: 2.16.1is-glob: 4.0.3diff --git a/src/web/package.json b/src/web/package.jsonindex 7075e103f..4a5166581 100644--- a/src/web/package.json+++ b/src/web/package.json@@ -43,6 +43,7 @@"better-auth": "^1.6.9","class-variance-authority": "^0.7.1","clsx": "^2.1.1",+ "driver.js": "^1.4.0","embla-carousel-autoplay": "^8.6.0","embla-carousel-react": "^8.6.0","gsap": "^3.15.0",diff --git a/src/web/src/app/(app)/w/[slug]/agents/new/page.tsx b/src/web/src/app/(app)/w/[slug]/agents/new/page.tsxindex d04bbe0d2..f557dc009 100644--- a/src/web/src/app/(app)/w/[slug]/agents/new/page.tsx+++ b/src/web/src/app/(app)/w/[slug]/agents/new/page.tsx@@ -1,18 +1,20 @@"use client";-import { useState, useEffect } from "react";+import { useState, useEffect, useRef, useCallback } from "react";import { useRouter } from "next/navigation";import { useAgentContext } from "@/contexts/agent-context";import { useWorkspace } from "@/contexts/workspace-context";import { AgentCreateForm } from "@/components/agent-create-form";import { fetchModelOptions, createEmailAccount } from "@/lib/api";import { toast } from "sonner";+import { CircleHelp } from "lucide-react";export default function CreateAgentPage() {const router = useRouter();const { slug, workspaceId } = useWorkspace();const {+ agents,runtimes,handleCreateAgent,getFirstOnlineRuntimeId,@@ -20,21 +22,36 @@ export default function CreateAgentPage() {const [saving, setSaving] = useState(false);const [modelOptions, setModelOptions] = useState<Record<string, string[]>>({});+ const startTourRef = useRef<(() => void) | null>(null);useEffect(() => {fetchModelOptions().then(setModelOptions).catch(() => {});}, []);+ const handleTourReady = useCallback((startTour: () => void) => {+ startTourRef.current = startTour;+ }, []);+return (<><div className="flex items-center gap-2 border-b border-border/50 px-3 md:px-5 py-2.5"><h1 className="text-sm font-medium">Create Agent</h1>+ <button+ type="button"+ title="Show guided tour"+ onClick={() => startTourRef.current?.()}+ className="text-muted-foreground hover:text-foreground transition-colors"+ >+ <CircleHelp className="size-3.5" />+ </button></div><AgentCreateFormruntimes={runtimes}defaultRuntimeId={getFirstOnlineRuntimeId()}modelOptions={modelOptions}+ guided={agents.length === 0}+ onTourReady={handleTourReady}saving={saving}onCancel={() => router.back()}onSave={async (data) => {diff --git a/src/web/src/app/(app)/w/[slug]/runtimes/page.tsx b/src/web/src/app/(app)/w/[slug]/runtimes/page.tsxindex f78ae992e..fda6fe532 100644--- a/src/web/src/app/(app)/w/[slug]/runtimes/page.tsx+++ b/src/web/src/app/(app)/w/[slug]/runtimes/page.tsx@@ -22,7 +22,7 @@ import {import { ConfirmDialog } from "@/components/ui/confirm-dialog";import { toast } from "sonner";import { Skeleton } from "@/components/ui/skeleton";-import { Monitor, Plus } from "lucide-react";+import { Monitor, Plus, Check } from "lucide-react";import type { AgentRuntime as Runtime } from "@alook/shared";import { semverGte } from "@alook/shared";@@ -31,16 +31,34 @@ import { ProviderLogo } from "@/components/provider-logo";import { triggerRuntimeUpdate, triggerRuntimeRescan, fetchLatestCliVersion } from "@/lib/api";import { Loader2, RefreshCw } from "lucide-react";+function StepIndicator({ step, completed }: { step: number; completed: boolean }) {+ if (completed) {+ return (+ <span className="flex items-center justify-center size-5 rounded-full bg-emerald-500 text-white transition-all duration-300">+ <Check className="size-3" strokeWidth={3} />+ </span>+ );+ }+ return (+ <span className="flex items-center justify-center size-5 rounded-full bg-foreground text-background text-[10px] font-semibold">+ {step}+ </span>+ );+}+function ConnectMachineSteps({generatedToken,generatingToken,onGenerateToken,+ registered,}: {generatedToken: string;generatingToken: boolean;onGenerateToken: () => void;+ registered: boolean;}) {const hasTriggered = useRef(false);+useEffect(() => {if (!generatedToken && !generatingToken && !hasTriggered.current) {hasTriggered.current = true;@@ -48,8 +66,13 @@ function ConnectMachineSteps({}}, [generatedToken, generatingToken, onGenerateToken]);- const copyToClipboard = (text: string) => {- navigator.clipboard.writeText(text);+ const copyRegister = () => {+ navigator.clipboard.writeText(`${CLI_CMD} register --token ${generatedToken}`);+ toast.success("Copied to clipboard");+ };++ const copyDaemon = () => {+ navigator.clipboard.writeText(`${CLI_CMD} daemon start --foreground`);toast.success("Copied to clipboard");};@@ -58,10 +81,9 @@ function ConnectMachineSteps({{/* Step 1 */}<div className="space-y-2"><p className="text-xs font-medium flex items-center gap-2">- <span className="flex items-center justify-center size-5 rounded-full bg-foreground text-background text-[10px] font-semibold">- 1- </span>+ <StepIndicator step={1} completed={registered} />Register your CLI+ {registered && <span className="text-[10px] text-emerald-500 font-normal">Done</span>}</p><p className="text-xs text-muted-foreground pl-7">Run this in your terminal to link your machine.@@ -76,11 +98,7 @@ function ConnectMachineSteps({<div className="pl-7 space-y-2"><divclassName="rounded-md bg-muted p-2.5 font-mono text-xs text-muted-foreground cursor-pointer hover:bg-muted/80 transition-colors"- onClick={() =>- copyToClipboard(- `${CLI_CMD} register --token ${generatedToken}`- )- }+ onClick={copyRegister}title="Click to copy">{CLI_CMD} register --token{" "}@@ -88,30 +106,25 @@ function ConnectMachineSteps({{generatedToken.slice(0, 12)}...</span></div>- <Button- size="sm"- onClick={() => {- navigator.clipboard.writeText(- `${CLI_CMD} register --token ${generatedToken}`- );- toast.success("Copied to clipboard");- }}- className="w-full"- >- Copy Command- </Button>+ {!registered && (+ <Button+ size="sm"+ onClick={copyRegister}+ className="w-full"+ >+ Copy Command+ </Button>+ )}</div>) : null}</div>{/* Step 2 */}<div- className={`space-y-2 ${!generatedToken ? "opacity-40 pointer-events-none" : ""}`}+ className={`space-y-2 transition-opacity duration-300 ${!registered ? "opacity-40 pointer-events-none" : ""}`}><p className="text-xs font-medium flex items-center gap-2">- <span className="flex items-center justify-center size-5 rounded-full bg-foreground text-background text-[10px] font-semibold">- 2- </span>+ <StepIndicator step={2} completed={false} />Start the daemon</p><p className="text-xs text-muted-foreground pl-7">@@ -119,13 +132,22 @@ function ConnectMachineSteps({</p><divclassName="ml-7 rounded-md bg-muted p-2.5 font-mono text-xs text-muted-foreground cursor-pointer hover:bg-muted/80 transition-colors"- onClick={() =>- copyToClipboard(`${CLI_CMD} daemon start --foreground`)- }+ onClick={copyDaemon}title="Click to copy">{CLI_CMD} daemon start --foreground</div>+ {registered && (+ <div className="pl-7">+ <Button+ size="sm"+ onClick={copyDaemon}+ className="w-full"+ >+ Copy Command+ </Button>+ </div>+ )}</div></div>@@ -133,7 +155,7 @@ function ConnectMachineSteps({}export default function RuntimesPage() {- const { runtimes, loading, handleGenerateToken, handleDeleteMachine, subscribeWs, workspaceId } =+ const { agents, runtimes, loading, handleGenerateToken, handleDeleteMachine, subscribeWs, workspaceId } =useAgentContext();const searchParams = useSearchParams();const router = useRouter();@@ -142,6 +164,7 @@ export default function RuntimesPage() {const [sheetOpen, setSheetOpen] = useState(() => searchParams.has("connect"));const [generatedToken, setGeneratedToken] = useState("");const [generatingToken, setGeneratingToken] = useState(false);+ const [machineRegistered, setMachineRegistered] = useState(false);const [latestCliVersion, setLatestCliVersion] = useState<string | null>(null);const [updatingDaemons, setUpdatingDaemons] = useState<Set<string>>(new Set());@@ -169,24 +192,33 @@ export default function RuntimesPage() {}}, [searchParams, router, pathname]);- // Close the sheet only after the daemon is actually online. Runtime- // registration can happen before the user starts the daemon process.+ // Listen for registration + online events while the sheet is open.const sheetOpenRef = useRef(sheetOpen);useEffect(() => { sheetOpenRef.current = sheetOpen; }, [sheetOpen]);+ const agentsRef = useRef(agents);+ useEffect(() => { agentsRef.current = agents; }, [agents]);useEffect(() => {return subscribeWs((msg) => {+ if (!sheetOpenRef.current) return;+ if (msg.type === "runtime.registered" && msg.workspaceId === workspaceId) {+ setMachineRegistered(true);+ }if (msg.type === "runtime.status" &&msg.workspaceId === workspaceId &&- msg.status === "online" &&- sheetOpenRef.current+ msg.status === "online") {setSheetOpen(false);setGeneratedToken("");+ setMachineRegistered(false);toast.success("Machine connected");+ if (agentsRef.current.length === 0) {+ const slug = pathname.split("/")[2];+ router.push(`/w/${slug}/agents/new`);+ }}});- }, [subscribeWs, workspaceId]);+ }, [subscribeWs, workspaceId, pathname, router]);const openConfirm = (title: string,@@ -358,6 +390,7 @@ export default function RuntimesPage() {variant="outline"onClick={() => {setGeneratedToken("");+ setMachineRegistered(false);setSheetOpen(true);}}disabled={generatingToken}@@ -566,6 +599,7 @@ export default function RuntimesPage() {generatedToken={generatedToken}generatingToken={generatingToken}onGenerateToken={onGenerateToken}+ registered={machineRegistered}/></SheetBody></SheetContent>diff --git a/src/web/src/components/agent-create-form.tsx b/src/web/src/components/agent-create-form.tsxindex 1dd2591b8..bb9ce28b7 100644--- a/src/web/src/components/agent-create-form.tsx+++ b/src/web/src/components/agent-create-form.tsx@@ -1,6 +1,6 @@"use client";-import { useState, useRef } from "react";+import { useState, useRef, useEffect } from "react";import { Button } from "@/components/ui/button";import type { AgentRuntime as Runtime } from "@alook/shared";import {@@ -30,6 +30,8 @@ interface AgentCreateFormProps {runtimes: Runtime[];defaultRuntimeId?: string;modelOptions?: Record<string, string[]>;+ guided?: boolean;+ onTourReady?: (startTour: () => void) => void;onSave: (data: {name: string;description: string;@@ -44,10 +46,52 @@ interface AgentCreateFormProps {saving: boolean;}+// Stable initial config to avoid hydration mismatch (randomConfig uses Math.random)+const INITIAL_AVATAR: AvatarConfig = { shape: "circle", eye: "dots", nose: "dot", bg: 0 };++async function runTour() {+ const { driver } = await import("driver.js");+ await import("driver.js/dist/driver.css");++ const d = driver({+ showProgress: true,+ animate: true,+ allowClose: true,+ overlayClickBehavior: () => {},+ overlayColor: "black",+ overlayOpacity: 0.4,+ popoverClass: "agent-tour-popover",+ steps: [+ {+ element: "#agent-name",+ popover: {+ title: "Name your agent",+ description: "Give your agent a name — this is how you'll identify it.",+ side: "bottom" as const,+ align: "start" as const,+ },+ },+ {+ element: "#agent-runtime-select",+ disableActiveInteraction: false,+ popover: {+ title: "Choose a runtime",+ description: "Select which machine and provider will run this agent.",+ side: "bottom" as const,+ align: "start" as const,+ },+ },+ ],+ });+ d.drive();+}+export function AgentCreateForm({runtimes,defaultRuntimeId = "",modelOptions,+ guided = false,+ onTourReady,onSave,onCancel,saving,@@ -65,7 +109,16 @@ export function AgentCreateForm({null);const [model, setModel] = useState("");- const [avatarConfig, setAvatarConfig] = useState<AvatarConfig>(() => randomConfig());+ const [avatarConfig, setAvatarConfig] = useState<AvatarConfig>(INITIAL_AVATAR);++ // Randomize avatar on client mount to avoid hydration mismatch+ const avatarInitialized = useRef(false);+ useEffect(() => {+ if (!avatarInitialized.current) {+ avatarInitialized.current = true;+ setAvatarConfig(randomConfig());+ }+ }, []);const selectedRuntime = runtimes.find((r) => r.id === runtimeId);const providerModels =@@ -77,6 +130,18 @@ export function AgentCreateForm({const effectiveHandle = emailHandle || derivedHandle;const handleError = getHandleError(effectiveHandle);+ // Driver.js guided tour for first-time agent creation+ const driverStarted = useRef(false);+ useEffect(() => {+ onTourReady?.(() => runTour());+ }, [onTourReady]);+ useEffect(() => {+ if (!guided || driverStarted.current) return;+ driverStarted.current = true;+ const timeout = setTimeout(() => runTour(), 500);+ return () => clearTimeout(timeout);+ }, [guided]);+const updateName = (value: string) => {setName(value);if (fieldErrors.name && value.trim()) {@@ -85,7 +150,12 @@ export function AgentCreateForm({};const updateRuntimeId = (value: string) => {+ const oldProvider = runtimes.find((r) => r.id === runtimeId)?.provider;+ const newProvider = runtimes.find((r) => r.id === value)?.provider;setRuntimeId(value);+ if (oldProvider && oldProvider !== newProvider) {+ setModel("");+ }if (fieldErrors.runtimeId && value) {setFieldErrors((prev) => ({ ...prev, runtimeId: undefined }));}@@ -134,6 +204,7 @@ export function AgentCreateForm({runtimes={runtimes}providerModels={providerModels}errors={fieldErrors}+ runtimeAsRadio/><div className="border-t border-border/50 pt-4 mt-4 space-y-4">diff --git a/src/web/src/components/agent-form-fields.tsx b/src/web/src/components/agent-form-fields.tsxindex 128b55995..2abe3eef4 100644--- a/src/web/src/components/agent-form-fields.tsx+++ b/src/web/src/components/agent-form-fields.tsx@@ -22,6 +22,7 @@ import {DialogClose,} from "@/components/ui/dialog";import { RuntimeSelect } from "@/components/runtime-select";+import { ProviderLogo } from "@/components/provider-logo";import { isValidHandle } from "@alook/shared";import type { AgentRuntime as Runtime } from "@alook/shared";import { cn } from "@/lib/utils";@@ -72,6 +73,7 @@ interface GeneralFieldsProps {name?: string;runtimeId?: string;};+ runtimeAsRadio?: boolean;}export function GeneralFields({@@ -88,6 +90,7 @@ export function GeneralFields({runtimes,providerModels,errors,+ runtimeAsRadio = false,}: GeneralFieldsProps) {return (<>@@ -153,26 +156,77 @@ export function GeneralFields({</p></div>- <div className="space-y-1.5">- <Label htmlFor="agent-runtime">Runtime <span className="text-destructive">*</span></Label>- <RuntimeSelect- value={runtimeId}- onValueChange={(newId) => {- const oldProvider = runtimes.find((r) => r.id === runtimeId)?.provider;- const newProvider = runtimes.find((r) => r.id === newId)?.provider;- setRuntimeId(newId);- if (oldProvider && oldProvider !== newProvider) {- setModel("");- }- }}- runtimes={runtimes}- triggerProps={{- "aria-invalid": Boolean(errors?.runtimeId),- "aria-describedby": errors?.runtimeId- ? "agent-runtime-error"- : undefined,- }}- />+ <div id="agent-runtime-select" className="space-y-1.5">+ <Label>Runtime <span className="text-destructive">*</span></Label>+ {runtimeAsRadio ? (+ <div className="space-y-1.5" role="radiogroup" aria-label="Runtime">+ {runtimes.length === 0 ? (+ <p className="text-xs text-muted-foreground">No runtimes — start a daemon first</p>+ ) : (+ runtimes.map((rt) => {+ const isOnline = rt.status === "online";+ const isSelected = runtimeId === rt.id;+ const machine = typeof rt.device_info === "string" ? rt.device_info : "";+ return (+ <label+ key={rt.id}+ className={cn(+ "flex items-center gap-2.5 rounded-lg border p-2.5 cursor-pointer transition-colors",+ isSelected+ ? "border-primary bg-primary/5"+ : "border-border hover:border-foreground/20",+ !isOnline && "opacity-40 pointer-events-none"+ )}+ >+ <input+ type="radio"+ name="runtime"+ value={rt.id}+ checked={isSelected}+ disabled={!isOnline}+ onChange={() => {+ const oldProvider = runtimes.find((r) => r.id === runtimeId)?.provider;+ const newProvider = rt.provider;+ setRuntimeId(rt.id);+ if (oldProvider && oldProvider !== newProvider) {+ setModel("");+ }+ }}+ className="accent-primary size-3.5"+ />+ <ProviderLogo provider={rt.provider} className="h-4 w-4 shrink-0" />+ <span className="text-sm">{rt.provider}</span>+ {machine && (+ <span className="text-xs text-muted-foreground">{machine}</span>+ )}+ {!isOnline && (+ <span className="text-xs text-muted-foreground ml-auto">offline</span>+ )}+ </label>+ );+ })+ )}+ </div>+ ) : (+ <RuntimeSelect+ value={runtimeId}+ onValueChange={(newId) => {+ const oldProvider = runtimes.find((r) => r.id === runtimeId)?.provider;+ const newProvider = runtimes.find((r) => r.id === newId)?.provider;+ setRuntimeId(newId);+ if (oldProvider && oldProvider !== newProvider) {+ setModel("");+ }+ }}+ runtimes={runtimes}+ triggerProps={{+ "aria-invalid": Boolean(errors?.runtimeId),+ "aria-describedby": errors?.runtimeId+ ? "agent-runtime-error"+ : undefined,+ }}+ />+ )}{errors?.runtimeId && (<p id="agent-runtime-error" className="text-xs text-destructive">{errors.runtimeId}