@geminilight/mindos 0.6.28 → 0.6.30

package/app/components/renderers/workflow-yaml/serializer.ts

@@ -0,0 +1,56 @@
+import YAML from 'js-yaml';
+import type { WorkflowYaml } from './types';
+
+/**
+ * Serialize a WorkflowYaml object to a YAML string.
+ * Strips undefined/empty optional fields to keep output clean.
+ */
+export function serializeWorkflowYaml(workflow: WorkflowYaml): string {
+  const clean: Record<string, unknown> = {
+    title: workflow.title,
+  };
+  if (workflow.description) clean.description = workflow.description;
+  if (workflow.workDir) clean.workDir = workflow.workDir;
+  if (workflow.skills?.length) clean.skills = workflow.skills;
+  if (workflow.tools?.length) clean.tools = workflow.tools;
+
+  clean.steps = workflow.steps.map((step) => {
+    const s: Record<string, unknown> = {
+      id: step.id,
+      name: step.name,
+    };
+    if (step.description) s.description = step.description;
+    if (step.agent) s.agent = step.agent;
+    if (step.model) s.model = step.model;
+    if (step.skill) s.skill = step.skill;
+    if (step.skills?.length) s.skills = step.skills;
+    if (step.tools?.length) s.tools = step.tools;
+    if (step.context?.length) s.context = step.context;
+    s.prompt = step.prompt;
+    if (step.timeout) s.timeout = step.timeout;
+    return s;
+  });
+
+  return YAML.dump(clean, {
+    lineWidth: -1,
+    noRefs: true,
+    quotingType: '"',
+    forceQuotes: false,
+  });
+}
+
+/** Generate a URL-safe step ID from a name */
+export function generateStepId(name: string, existingIds: string[]): string {
+  const base = name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '')
+    || 'step';
+  let id = base;
+  let i = 2;
+  while (existingIds.includes(id)) {
+    id = `${base}-${i}`;
+    i++;
+  }
+  return id;
+}

package/app/components/renderers/workflow-yaml/types.ts

@@ -0,0 +1,46 @@
+// Types for YAML Workflow
+
+export type StepStatus = 'pending' | 'running' | 'done' | 'error' | 'skipped';
+
+export interface WorkflowStep {
+  id: string;
+  name: string;
+  description?: string;
+  agent?: string;
+  model?: string;
+  skill?: string;
+  skills?: string[];
+  tools?: string[];
+  context?: string[];
+  prompt: string;
+  timeout?: number;
+}
+
+export interface WorkflowYaml {
+  title: string;
+  description?: string;
+  workDir?: string;
+  skills?: string[];
+  tools?: string[];
+  steps: WorkflowStep[];
+}
+
+export interface WorkflowStepRuntime extends WorkflowStep {
+  index: number;
+  status: StepStatus;
+  output: string;
+  error?: string;
+  startedAt?: Date;
+  completedAt?: Date;
+  durationMs?: number;
+}
+
+export interface ParseResult {
+  workflow: WorkflowYaml | null;
+  errors: string[];
+}
+
+export interface ValidationResult {
+  valid: boolean;
+  errors: string[];
+}

package/app/components/settings/KnowledgeTab.tsx

@@ -2,6 +2,7 @@
 
 import { useState, useEffect, useCallback, useSyncExternalStore, useRef } from 'react';
 import { Copy, Check, RefreshCw, Trash2, Sparkles, ChevronDown, ChevronRight, Loader2, Cpu, Zap, Database as DatabaseIcon, HardDrive, RotateCcw } from 'lucide-react';
+import { toast } from '@/lib/toast';
 import type { KnowledgeTabProps } from './types';
 import { Field, Input, EnvBadge, SectionLabel, Toggle } from './Primitives';
 import { ConfirmDialog } from '@/components/agents/AgentsPrimitives';
@@ -96,7 +97,6 @@ export function KnowledgeTab({ data, setData, t }: KnowledgeTabProps) {
   const [showPassword, setShowPassword] = useState(false);
   const isPasswordMasked = data.webPassword === '***set***';
 
-  const [copied, setCopied] = useState(false);
   const [resetting, setResetting] = useState(false);
   // revealed holds the plaintext token after regenerate, until user navigates away
   const [revealedToken, setRevealedToken] = useState<string | null>(null);
@@ -130,10 +130,7 @@ export function KnowledgeTab({ data, setData, t }: KnowledgeTabProps) {
     const text = revealedToken ?? data.authToken ?? '';
     if (!text) return;
     copyToClipboard(text).then((ok) => {
-      if (ok) {
-        setCopied(true);
-        setTimeout(() => setCopied(false), 2000);
-      }
+      if (ok) toast.copy();
     });
   }
 
@@ -229,7 +226,7 @@ export function KnowledgeTab({ data, setData, t }: KnowledgeTabProps) {
                 className="shrink-0 p-1 rounded text-muted-foreground hover:text-foreground transition-colors"
                 title={k.authTokenCopy}
               >
-                {copied ? <Check size={13} className="text-success" /> : <Copy size={13} />}
+                <Copy size={13} />
               </button>
             )}
           </div>

package/app/components/settings/McpSkillsSection.tsx

@@ -3,8 +3,9 @@
 import { useState, useEffect, useCallback, useMemo } from 'react';
 import {
   Loader2, ChevronDown, ChevronRight,
-  Plus, X, Search, Copy, Check,
+  Plus, X, Search, Copy,
 } from 'lucide-react';
+import { toast } from '@/lib/toast';
 import { apiFetch } from '@/lib/api';
 import { useMcpDataOptional } from '@/hooks/useMcpData';
 import { ConfirmDialog } from '@/components/agents/AgentsPrimitives';
@@ -398,14 +399,12 @@ function SkillCliHint({ agents, skillName, m }: {
   m: Record<string, any> | undefined;
 }) {
   const [selectedAgent, setSelectedAgent] = useState('claude-code');
-  const [copied, setCopied] = useState(false);
-
   const cmd = `npx skills add GeminiLight/MindOS --skill ${skillName} -a ${selectedAgent} -g -y`;
   const skillPath = `~/.agents/skills/${skillName}/SKILL.md`;
 
   const handleCopy = async () => {
     const ok = await copyToClipboard(cmd);
-    if (ok) { setCopied(true); setTimeout(() => setCopied(false), 2000); }
+    if (ok) toast.copy();
   };
 
   // Group agents: connected first, then detected, then not found
@@ -447,7 +446,7 @@ function SkillCliHint({ agents, skillName, m }: {
         </code>
         <button onClick={handleCopy}
           className="p-1.5 rounded-md border border-border text-muted-foreground hover:text-foreground hover:bg-muted transition-colors shrink-0">
-          {copied ? <Check size={11} /> : <Copy size={11} />}
+          <Copy size={11} />
         </button>
       </div>
 

package/app/components/settings/McpTab.tsx

@@ -1,5 +1,6 @@
 import { useState, useMemo, useRef, useEffect } from 'react';
-import { Loader2, Copy, Check, Monitor, Globe, AlertCircle, RotateCcw, RefreshCw } from 'lucide-react';
+import { Loader2, Copy, Monitor, Globe, AlertCircle, RotateCcw, RefreshCw } from 'lucide-react';
+import { toast } from '@/lib/toast';
 import { useMcpDataOptional } from '@/hooks/useMcpData';
 import { generateSnippet } from '@/lib/mcp-snippets';
 import { copyToClipboard } from '@/lib/clipboard';
@@ -22,7 +23,6 @@ export function McpTab({ t }: McpTabProps) {
   const [restarting, setRestarting] = useState(false);
   const [selectedAgent, setSelectedAgent] = useState('');
   const [transport, setTransport] = useState<'stdio' | 'http'>('stdio');
-  const [copied, setCopied] = useState(false);
   const restartPollRef = useRef<ReturnType<typeof setInterval>>(undefined);
 
   // Cleanup restart poll on unmount
@@ -99,10 +99,9 @@ export function McpTab({ t }: McpTabProps) {
             onSelectAgent={(key) => setSelectedAgent(key)}
             transport={transport}
             onTransportChange={setTransport}
-            copied={copied}
             onCopy={async (snippet) => {
               const ok = await copyToClipboard(snippet);
-              if (ok) { setCopied(true); setTimeout(() => setCopied(false), 2000); }
+              if (ok) toast.copy();
             }}
             m={m}
           />
@@ -177,7 +176,7 @@ function McpStatusCard({ status, restarting, onRestart, onRefresh, m }: {
 
 /* ── Agent Config Viewer (dropdown + snippet) ── */
 
-function AgentConfigViewer({ connectedAgents, detectedAgents, notFoundAgents, currentAgent, mcpStatus, selectedAgent, onSelectAgent, transport, onTransportChange, copied, onCopy, m }: {
+function AgentConfigViewer({ connectedAgents, detectedAgents, notFoundAgents, currentAgent, mcpStatus, selectedAgent, onSelectAgent, transport, onTransportChange, onCopy, m }: {
   connectedAgents: AgentInfo[];
   detectedAgents: AgentInfo[];
   notFoundAgents: AgentInfo[];
@@ -187,7 +186,6 @@ function AgentConfigViewer({ connectedAgents, detectedAgents, notFoundAgents, cu
   onSelectAgent: (key: string) => void;
   transport: 'stdio' | 'http';
   onTransportChange: (t: 'stdio' | 'http') => void;
-  copied: boolean;
   onCopy: (snippet: string) => void;
   m: Record<string, any> | undefined;
 }) {
@@ -292,8 +290,8 @@ function AgentConfigViewer({ connectedAgents, detectedAgents, notFoundAgents, cu
               <div className="flex items-center gap-3 text-xs">
                 <button onClick={() => onCopy(snippet.snippet)}
                   className="inline-flex items-center gap-1.5 px-2.5 py-1.5 rounded-lg border border-border text-muted-foreground hover:text-foreground hover:bg-muted transition-colors shrink-0">
-                  {copied ? <Check size={12} /> : <Copy size={12} />}
-                  {copied ? (m?.copied ?? 'Copied!') : (m?.copyConfig ?? 'Copy config')}
+                  <Copy size={12} />
+                  {m?.copyConfig ?? 'Copy config'}
                 </button>
                 <span className="text-muted-foreground">→</span>
                 <span className="font-mono text-muted-foreground truncate text-2xs">{snippet.path}</span>

package/app/components/setup/StepSecurity.tsx

@@ -1,13 +1,12 @@
 'use client';
 
 import { useState } from 'react';
-import { Copy, Check, RefreshCw } from 'lucide-react';
+import { Copy, RefreshCw } from 'lucide-react';
 import { Field, Input } from '@/components/settings/Primitives';
 import type { SetupMessages } from './types';
 
 export interface StepSecurityProps {
   authToken: string;
-  tokenCopied: boolean;
   onCopy: () => void;
   onGenerate: (seed?: string) => void;
   webPassword: string;
@@ -16,7 +15,7 @@ export interface StepSecurityProps {
 }
 
 export default function StepSecurity({
-  authToken, tokenCopied, onCopy, onGenerate, webPassword, onPasswordChange, s,
+  authToken, onCopy, onGenerate, webPassword, onPasswordChange, s,
 }: StepSecurityProps) {
   const [seed, setSeed] = useState('');
   const [showSeed, setShowSeed] = useState(false);
@@ -29,8 +28,8 @@ export default function StepSecurity({
           <button onClick={onCopy}
             className="flex items-center gap-1 px-3 py-2 text-xs rounded-lg border border-border hover:bg-muted transition-colors shrink-0"
             style={{ color: 'var(--foreground)' }}>
-            {tokenCopied ? <Check size={14} /> : <Copy size={14} />}
-            {tokenCopied ? s.copiedToken : s.copyToken}
+            <Copy size={14} />
+            {s.copyToken}
           </button>
           <button onClick={() => onGenerate()}
             aria-label={s.generateToken}

package/app/components/setup/index.tsx

@@ -4,6 +4,7 @@ import { useState, useEffect, useCallback } from 'react';
 import { Sparkles, Loader2, ChevronLeft, ChevronRight } from 'lucide-react';
 import { useLocale } from '@/lib/LocaleContext';
 import { copyToClipboard } from '@/lib/clipboard';
+import { toast } from '@/lib/toast';
 import type { SetupState, PortStatus, AgentEntry, AgentInstallStatus } from './types';
 import { TOTAL_STEPS, STEP_KB, STEP_PORTS, STEP_AGENTS } from './constants';
 import StepKB from './StepKB';
@@ -127,7 +128,6 @@ export default function SetupWizard() {
     webPassword: '',
   });
   const [homeDir, setHomeDir] = useState('~');
-  const [tokenCopied, setTokenCopied] = useState(false);
   const [submitting, setSubmitting] = useState(false);
   const [completed, setCompleted] = useState(false);
   const [error, setError] = useState('');
@@ -230,15 +230,9 @@ export default function SetupWizard() {
   }, []);
 
   const copyToken = useCallback(() => {
-    copyToClipboard(state.authToken)
-      .then(() => {
-        setTokenCopied(true);
-        setTimeout(() => setTokenCopied(false), 2000);
-      })
-      .catch((err) => {
-        console.error('[Setup] Token copy failed:', err);
-        // Show error toast instead of success
-      });
+    copyToClipboard(state.authToken).then((ok) => {
+      if (ok) toast.copy();
+    });
   }, [state.authToken]);
 
   const checkPort = useCallback(async (port: number, which: 'web' | 'mcp') => {
@@ -384,7 +378,7 @@ export default function SetupWizard() {
         )}
         {step === 3 && (
           <StepSecurity
-            authToken={state.authToken} tokenCopied={tokenCopied}
+            authToken={state.authToken}
             onCopy={copyToken} onGenerate={generateToken}
             webPassword={state.webPassword} onPasswordChange={v => update('webPassword', v)}
             s={s}

package/app/components/ui/Toaster.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+import { useSyncExternalStore } from 'react';
+import { Check, AlertCircle, Info, X } from 'lucide-react';
+import { subscribe, getSnapshot, dismiss, type Toast } from '@/lib/toast';
+
+const icons: Record<Toast['type'], React.ReactNode> = {
+  success: <Check size={15} className="text-success shrink-0" />,
+  error: <AlertCircle size={15} className="text-error shrink-0" />,
+  info: <Info size={15} className="text-muted-foreground shrink-0" />,
+};
+
+export default function Toaster() {
+  const toasts = useSyncExternalStore(subscribe, getSnapshot, getSnapshot);
+
+  if (toasts.length === 0) return null;
+
+  return (
+    <div className="fixed bottom-4 right-4 z-50 flex flex-col-reverse gap-2 pointer-events-none" aria-live="polite">
+      {toasts.map((t) => (
+        <div
+          key={t.id}
+          className="pointer-events-auto flex items-center gap-2.5 bg-card border border-border rounded-lg shadow-lg px-4 py-2.5 min-w-[180px] max-w-[320px] animate-in slide-in-from-right-4 fade-in duration-200"
+        >
+          {icons[t.type]}
+          <span className="text-sm text-foreground flex-1 truncate">{t.message}</span>
+          <button
+            type="button"
+            onClick={() => dismiss(t.id)}
+            className="shrink-0 p-0.5 rounded text-muted-foreground hover:text-foreground transition-colors"
+            aria-label="Dismiss"
+          >
+            <X size={13} />
+          </button>
+        </div>
+      ))}
+    </div>
+  );
+}

package/app/hooks/useA2aRegistry.ts

@@ -8,6 +8,7 @@ interface A2aRegistry {
   discovering: boolean;
   error: string | null;
   discover: (url: string) => Promise<RemoteAgent | null>;
+  remove: (id: string) => void;
   refresh: () => void;
 }
 
@@ -44,10 +45,14 @@ export function useA2aRegistry(): A2aRegistry {
     }
   }, []);
 
+  const remove = useCallback((id: string) => {
+    setAgents(prev => prev.filter(a => a.id !== id));
+  }, []);
+
   const refresh = useCallback(() => {
     setAgents([]);
     setError(null);
   }, []);
 
-  return { agents, discovering, error, discover, refresh };
+  return { agents, discovering, error, discover, remove, refresh };
 }

package/app/hooks/useAcpConfig.ts

@@ -0,0 +1,96 @@
+'use client';
+
+import { useState, useEffect, useCallback } from 'react';
+import type { AcpAgentOverride } from '@/lib/acp/agent-descriptors';
+
+interface AcpConfigState {
+  configs: Record<string, AcpAgentOverride>;
+  loading: boolean;
+  saving: boolean;
+  error: string | null;
+  /** Save a per-agent override. */
+  save: (agentId: string, config: AcpAgentOverride) => Promise<boolean>;
+  /** Reset a single agent to defaults. */
+  reset: (agentId: string) => Promise<boolean>;
+  /** Refresh from server. */
+  refresh: () => void;
+}
+
+export function useAcpConfig(): AcpConfigState {
+  const [configs, setConfigs] = useState<Record<string, AcpAgentOverride>>({});
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [trigger, setTrigger] = useState(0);
+
+  const refresh = useCallback(() => setTrigger((n) => n + 1), []);
+
+  useEffect(() => {
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+
+    fetch('/api/acp/config')
+      .then((res) => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then((data) => {
+        if (cancelled) return;
+        setConfigs(data.agents ?? {});
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        setError((err as Error).message);
+      })
+      .finally(() => {
+        if (!cancelled) setLoading(false);
+      });
+
+    return () => { cancelled = true; };
+  }, [trigger]);
+
+  const save = useCallback(async (agentId: string, config: AcpAgentOverride): Promise<boolean> => {
+    setSaving(true);
+    setError(null);
+    try {
+      const res = await fetch('/api/acp/config', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ agentId, config }),
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      setConfigs(data.agents ?? {});
+      return true;
+    } catch (err) {
+      setError((err as Error).message);
+      return false;
+    } finally {
+      setSaving(false);
+    }
+  }, []);
+
+  const reset = useCallback(async (agentId: string): Promise<boolean> => {
+    setSaving(true);
+    setError(null);
+    try {
+      const res = await fetch('/api/acp/config', {
+        method: 'DELETE',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ agentId }),
+      });
+      if (!res.ok) throw new Error(`HTTP ${res.status}`);
+      const data = await res.json();
+      setConfigs(data.agents ?? {});
+      return true;
+    } catch (err) {
+      setError((err as Error).message);
+      return false;
+    } finally {
+      setSaving(false);
+    }
+  }, []);
+
+  return { configs, loading, saving, error, save, reset, refresh };
+}

package/app/hooks/useAcpDetection.ts

@@ -0,0 +1,120 @@
+'use client';
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+
+export interface DetectedAgent {
+  id: string;
+  name: string;
+  binaryPath: string;
+  resolvedCommand?: {
+    cmd: string;
+    args: string[];
+    source: 'user-override' | 'descriptor' | 'registry';
+  };
+}
+
+export interface NotInstalledAgent {
+  id: string;
+  name: string;
+  installCmd: string;
+  packageName?: string;
+}
+
+interface AcpDetectionState {
+  installedAgents: DetectedAgent[];
+  notInstalledAgents: NotInstalledAgent[];
+  loading: boolean;
+  error: string | null;
+  refresh: () => void;
+}
+
+const STORAGE_KEY = 'mindos:acp-detection';
+const STALE_TTL_MS = 30 * 60 * 1000;
+const REVALIDATE_TTL_MS = 5 * 60 * 1000;
+
+interface DetectionCache {
+  installed: DetectedAgent[];
+  notInstalled: NotInstalledAgent[];
+  ts: number;
+}
+
+function readStorage(): DetectionCache | null {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (typeof parsed.ts !== 'number' || Date.now() - parsed.ts > STALE_TTL_MS) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(installed: DetectedAgent[], notInstalled: NotInstalledAgent[]) {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify({ installed, notInstalled, ts: Date.now() }));
+  } catch { /* quota exceeded */ }
+}
+
+export function useAcpDetection(): AcpDetectionState {
+  const cached = useRef(readStorage());
+  const [installedAgents, setInstalledAgents] = useState<DetectedAgent[]>(cached.current?.installed ?? []);
+  const [notInstalledAgents, setNotInstalledAgents] = useState<NotInstalledAgent[]>(cached.current?.notInstalled ?? []);
+  const [loading, setLoading] = useState(!cached.current);
+  const [error, setError] = useState<string | null>(null);
+  const [trigger, setTrigger] = useState(0);
+  const inflight = useRef(false);
+
+  const forceRef = useRef(false);
+
+  const refresh = useCallback(() => {
+    try { sessionStorage.removeItem(STORAGE_KEY); } catch { /* ignore */ }
+    cached.current = null;
+    forceRef.current = true;
+    setTrigger((n) => n + 1);
+  }, []);
+
+  useEffect(() => {
+    const isForce = forceRef.current;
+    forceRef.current = false;
+
+    const fresh = cached.current && Date.now() - cached.current.ts < REVALIDATE_TTL_MS;
+    if (fresh && trigger === 0) return;
+
+    if (inflight.current) return;
+    inflight.current = true;
+
+    const hasCachedData = installedAgents.length > 0 || notInstalledAgents.length > 0;
+    if (!hasCachedData) setLoading(true);
+    setError(null);
+
+    let cancelled = false;
+
+    fetch(`/api/acp/detect${isForce ? '?force=1' : ''}`)
+      .then((res) => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then((data) => {
+        if (cancelled) return;
+        const inst: DetectedAgent[] = data.installed ?? [];
+        const notInst: NotInstalledAgent[] = data.notInstalled ?? [];
+        writeStorage(inst, notInst);
+        cached.current = { installed: inst, notInstalled: notInst, ts: Date.now() };
+        setInstalledAgents(inst);
+        setNotInstalledAgents(notInst);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        if (!hasCachedData) setError((err as Error).message);
+      })
+      .finally(() => {
+        inflight.current = false;
+        if (!cancelled) setLoading(false);
+      });
+
+    return () => { cancelled = true; };
+  }, [trigger]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return { installedAgents, notInstalledAgents, loading, error, refresh };
+}

package/app/hooks/useAcpRegistry.ts

@@ -0,0 +1,86 @@
+'use client';
+
+import { useState, useEffect, useCallback, useRef } from 'react';
+import type { AcpRegistryEntry } from '@/lib/acp/types';
+
+interface AcpRegistryState {
+  agents: AcpRegistryEntry[];
+  loading: boolean;
+  error: string | null;
+  retry: () => void;
+}
+
+const STORAGE_KEY = 'mindos:acp-registry';
+const STALE_TTL_MS = 30 * 60 * 1000; // 30 min — show stale data instantly
+const REVALIDATE_TTL_MS = 10 * 60 * 1000; // 10 min — background refresh interval
+
+function readStorage(): { agents: AcpRegistryEntry[]; ts: number } | null {
+  try {
+    const raw = sessionStorage.getItem(STORAGE_KEY);
+    if (!raw) return null;
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed.agents) || typeof parsed.ts !== 'number') return null;
+    if (Date.now() - parsed.ts > STALE_TTL_MS) return null;
+    return parsed;
+  } catch {
+    return null;
+  }
+}
+
+function writeStorage(agents: AcpRegistryEntry[]) {
+  try {
+    sessionStorage.setItem(STORAGE_KEY, JSON.stringify({ agents, ts: Date.now() }));
+  } catch { /* quota exceeded — ignore */ }
+}
+
+export function useAcpRegistry(): AcpRegistryState {
+  const cached = useRef(readStorage());
+  const [agents, setAgents] = useState<AcpRegistryEntry[]>(cached.current?.agents ?? []);
+  const [loading, setLoading] = useState(!cached.current);
+  const [error, setError] = useState<string | null>(null);
+  const [trigger, setTrigger] = useState(0);
+  const inflight = useRef(false);
+
+  const retry = useCallback(() => {
+    setTrigger((n) => n + 1);
+  }, []);
+
+  useEffect(() => {
+    const fresh = cached.current && Date.now() - cached.current.ts < REVALIDATE_TTL_MS;
+    if (fresh && trigger === 0) return;
+
+    if (inflight.current) return;
+    inflight.current = true;
+
+    const hasCachedData = agents.length > 0;
+    if (!hasCachedData) setLoading(true);
+    setError(null);
+
+    let cancelled = false;
+
+    fetch('/api/acp/registry')
+      .then((res) => {
+        if (!res.ok) throw new Error(`HTTP ${res.status}`);
+        return res.json();
+      })
+      .then((data) => {
+        if (cancelled) return;
+        const list: AcpRegistryEntry[] = data.registry?.agents ?? [];
+        writeStorage(list);
+        cached.current = { agents: list, ts: Date.now() };
+        setAgents(list);
+      })
+      .catch((err) => {
+        if (cancelled) return;
+        if (!hasCachedData) setError((err as Error).message);
+      })
+      .finally(() => {
+        inflight.current = false;
+        if (!cancelled) setLoading(false);
+      });
+
+    return () => { cancelled = true; };
+  }, [trigger]); // eslint-disable-line react-hooks/exhaustive-deps
+
+  return { agents, loading, error, retry };
+}