@zhin.js/client 2.0.6 → 2.1.1

package/README.md

@@ -23,9 +23,15 @@ Peer：`react >= 18`（`createPluginRegisterHostApi` 需要 React 引用）。
 | `app` | 路由与工具注册单例（`addRoute`、`addTool` 等） |
 | `configureConsole` / `getRuntimeEnv` | 运行时环境（development / production） |
 | `createRegistryStore` / `useRegistry` | 可选 registry store |
+| `ENDPOINT_RPC` / `INBOX_RPC` / `SIDE_EVENT_RPC` / `SIDE_EVENT_PUSH` | `@zhin.js/console-protocol` 的规范 RPC 与推送名称 |
+| `normalizeConsolePushType` / `normalizeConsolePushMessage` | 在 SDK 边界兼容旧 `endpoint:*` 推送并输出规范事件与 payload |
+| `parseConsoleInboxEvent` | 一次完成 Inbox 推送名称、身份别名和 message/request/notice 分类 |
+| `ConsoleEndpointSummary` / `EndpointManagementCapability` | Host 与 Remote Console 共享的 Endpoint wire 类型 |
 
 类型与 Entry 契约来自 `@zhin.js/contract`。
 
+业务 UI 应使用 SDK 导出的协议常量和 Endpoint 类型，不要硬编码旧 `endpoint:list`、`endpoint:sendMessage` 等名称，也不要复制 `EndpointInfo`。SDK 会把旧 Host 推送别名归一化为 `message.receive` / `request.receive` / `notice.receive`，并统一 `endpointId`、`channelId` 字段。
+
 ## 启动：加载插件 Console Entry
 
 Remote Console 壳层在登录后调用：
@@ -117,4 +123,4 @@ pnpm --filter @zhin.js/client build
 
 - [Remote Console 使用说明](../../../docs/console-remote.md)
 - [Console 栈概览](../README.md)
-- [@zhin.js/host-api 管理面 API](../../host/api/README.md)
+- [@zhin.js/host-http（Console/HTTP Host 传输）](../../host/http/README.md)

package/client/bootstrap/loadConsoleEntries.test.ts

@@ -1,5 +1,9 @@
 import { describe, expect, it, vi } from "vitest";
-import { createPluginRegisterHostApi, getRegisterFn } from "./loadConsoleEntries.js";
+import {
+  createPluginRegisterHostApi,
+  getRegisterFn,
+  resolveEntryRegister,
+} from "./loadConsoleEntries.js";
 
 describe("console entries bootstrap", () => {
   it("resolves named register export", () => {
@@ -16,6 +20,29 @@ describe("console entries bootstrap", () => {
     expect(getRegisterFn({ default: {} })).toBeNull();
   });
 
+  it("synthesizes register from default component + entry.route", () => {
+    const Page = () => null;
+    const register = resolveEntryRegister(
+      { default: Page, meta: { title: "Sandbox", icon: "Box" } },
+      { id: "sandbox", resolvedModule: "/assets/client/sandbox.js", route: "/p-sandbox" } as any,
+    );
+    expect(typeof register).toBe("function");
+    const addRoute = vi.fn();
+    const createElement = vi.fn((c: unknown) => ({ type: c }));
+    register!({
+      React: { createElement } as any,
+      addRoute,
+      addPage: addRoute,
+      addTool: vi.fn(),
+    });
+    expect(addRoute).toHaveBeenCalledWith(expect.objectContaining({
+      path: "/p-sandbox",
+      name: "Sandbox",
+      icon: "Box",
+    }));
+    expect(createElement).toHaveBeenCalledWith(Page);
+  });
+
   it("creates a host API with addPage aliased to addRoute", () => {
     const React = {} as any;
     const addRoute = vi.fn();
@@ -29,4 +56,3 @@ describe("console entries bootstrap", () => {
     expect(api.addTool({ id: "t", name: "T" })).toBe("tool-id");
   });
 });
-

package/client/bootstrap/loadConsoleEntries.ts

@@ -1,4 +1,5 @@
 import { DEFAULT_CONSOLE_BASE_PATH, type ConsoleClientEntry, type ConsoleEntriesResponse, type ConsolePluginRegister, type PluginRegisterHostApi } from '@zhin.js/contract';
+import type * as React from 'react';
 
 export type FetchConsoleEntriesOptions = {
   entriesUrl?: string;
@@ -91,6 +92,43 @@ export function getRegisterFn(mod: Record<string, unknown> | null | undefined):
   return null;
 }
 
+/**
+ * Convention pages (ADR 0046) export a React component as `default` + optional `meta`,
+ * without a legacy `register(api)`. Synthesize register from entry.route / entry meta
+ * so Remote Console can still mount them.
+ */
+export function resolveEntryRegister(
+  mod: Record<string, unknown> | null | undefined,
+  entry: ConsoleClientEntry & { readonly route?: string; readonly title?: string },
+): ConsolePluginRegister | null {
+  const named = getRegisterFn(mod);
+  if (named) return named;
+  if (!mod) return null;
+  const Component = mod["default"];
+  if (typeof Component !== "function" && !(Component && typeof Component === "object")) {
+    return null;
+  }
+  const path = typeof entry.route === "string" && entry.route
+    ? entry.route
+    : `/${entry.id}`;
+  const meta = mod["meta"] && typeof mod["meta"] === "object"
+    ? mod["meta"] as { title?: string; icon?: unknown; hideInNav?: boolean }
+    : undefined;
+  const name = (typeof meta?.title === "string" && meta.title)
+    || (typeof entry.title === "string" && entry.title)
+    || entry.meta?.name
+    || entry.id;
+  return (api) => {
+    api.addRoute({
+      path,
+      name,
+      element: api.React.createElement(Component as React.ComponentType),
+      ...(meta?.icon != null ? { icon: meta.icon } : {}),
+      meta: { hideInMenu: meta?.hideInNav === true },
+    });
+  };
+}
+
 export async function registerConsolePluginsFromEntries(
   entries: ConsoleClientEntry[],
   hostApi: PluginRegisterHostApi,
@@ -103,7 +141,7 @@ export async function registerConsolePluginsFromEntries(
       try {
         const specifier = resolvePluginImportUrl(entry.resolvedModule, assetOrigin);
         const mod = (await import(/* @vite-ignore */ specifier)) as Record<string, unknown>;
-        const register = getRegisterFn(mod);
+        const register = resolveEntryRegister(mod, entry);
         if (register) await register(hostApi);
         else throw new Error(`entry "${entry.id}" has no register export`);
       } catch (error) {

package/client/console-utils/remoteApi.test.ts

@@ -0,0 +1,68 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+
+import { apiFetch, getToken } from "./remoteApi.js";
+
+function mockStorage(map: Record<string, string> = {}): Storage {
+  return {
+    getItem: (key: string) => map[key] ?? null,
+    setItem: (key: string, value: string) => {
+      map[key] = value;
+    },
+    removeItem: (key: string) => {
+      delete map[key];
+    },
+    clear: () => {
+      for (const key of Object.keys(map)) delete map[key];
+    },
+    key: () => null,
+    length: 0,
+  };
+}
+
+function installBrowserGlobals(runtimeToken?: string) {
+  const win = {
+    location: { origin: "http://localhost:5173", protocol: "http:", host: "localhost:5173" },
+    __ZHIN_API_TOKEN: runtimeToken as string | undefined,
+    dispatchEvent: vi.fn(),
+  };
+  vi.stubGlobal("window", win);
+  vi.stubGlobal("localStorage", mockStorage());
+  vi.stubGlobal("sessionStorage", mockStorage());
+  return win;
+}
+
+function fakeResponse(status: number): Response {
+  return { ok: status >= 200 && status < 300, status } as Response;
+}
+
+describe("apiFetch 401 handling", () => {
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("invalidates an expired runtime token on 401 so it cannot 401-loop forever", async () => {
+    // 回归：runtime token（Demo 预置）优先级最高，而旧实现 401 只清 local/sessionStorage，
+    // 过期 demo token 会让后续每个请求都 401。
+    const win = installBrowserGlobals("expired-demo-token");
+    vi.stubGlobal("fetch", vi.fn(async () => fakeResponse(401)));
+
+    expect(getToken()).toBe("expired-demo-token");
+    await apiFetch("/api/system/status");
+
+    expect(win.__ZHIN_API_TOKEN).toBeUndefined();
+    expect(getToken()).toBeNull();
+    expect(win.dispatchEvent).toHaveBeenCalledTimes(1);
+  });
+
+  it("keeps the runtime token when the response is not 401", async () => {
+    const win = installBrowserGlobals("valid-demo-token");
+    vi.stubGlobal("fetch", vi.fn(async () => fakeResponse(200)));
+
+    await apiFetch("/api/system/status");
+
+    expect(win.__ZHIN_API_TOKEN).toBe("valid-demo-token");
+    expect(getToken()).toBe("valid-demo-token");
+    expect(win.dispatchEvent).not.toHaveBeenCalled();
+  });
+});

package/client/console-utils/remoteApi.ts

@@ -9,7 +9,17 @@ export function getApiBase(): string {
 }
 
 export function getToken(): string | null {
-  return getRuntimeToken() ?? localStorage.getItem(TOKEN_KEY);
+  const runtime = getRuntimeToken();
+  if (runtime) return runtime;
+  if (typeof localStorage !== "undefined") {
+    const local = localStorage.getItem(TOKEN_KEY)?.trim();
+    if (local) return local;
+  }
+  if (typeof sessionStorage !== "undefined") {
+    const session = sessionStorage.getItem(TOKEN_KEY)?.trim();
+    if (session) return session;
+  }
+  return null;
 }
 
 export function resolveApiUrl(path: string): string {
@@ -41,6 +51,9 @@ export async function apiFetch(
 
   const res = await fetch(url, { ...init, headers });
   if (res.status === 401) {
+    // runtime token（Demo 预置）过期后也必须失效，否则 getToken() 永远优先命中它，
+    // local/sessionStorage 清理不掉，造成 401 死循环。
+    clearRuntimeToken();
     sessionStorage.removeItem(TOKEN_KEY);
     localStorage.removeItem(TOKEN_KEY);
     window.dispatchEvent(new CustomEvent("zhin:auth-required"));
@@ -57,3 +70,8 @@ function getRuntimeToken(): string | null {
   const token = (window as unknown as { __ZHIN_API_TOKEN?: string }).__ZHIN_API_TOKEN;
   return token?.trim() || null;
 }
+
+function clearRuntimeToken(): void {
+  if (typeof window === "undefined") return;
+  delete (window as unknown as { __ZHIN_API_TOKEN?: string }).__ZHIN_API_TOKEN;
+}

package/client/index.ts

@@ -1,5 +1,20 @@
 // Types
 export * from "./types";
+export {
+  ENDPOINT_RPC,
+  ENDPOINT_MANAGEMENT_CAPABILITIES,
+  INBOX_RPC,
+  SIDE_EVENT_PUSH,
+  SIDE_EVENT_RPC,
+  normalizeConsolePushMessage,
+  normalizeConsolePushType,
+  parseConsoleInboxEvent,
+  type ConsoleInboxEvent,
+  type ConsoleInboxEventKind,
+  type ConsoleEndpointPhase,
+  type ConsoleEndpointSummary,
+  type EndpointManagementCapability,
+} from "@zhin.js/console-protocol";
 
 // Media URL resolution
 export { resolveMediaSrc, pickMediaRawUrl, type MediaKind } from "./mediaSrc";
@@ -46,6 +61,7 @@ export {
   getRegisterFn,
   loadConsoleEntries,
   registerConsolePluginsFromEntries,
+  resolveEntryRegister,
   type CreatePluginRegisterHostApiOptions,
   type FetchConsoleEntriesOptions,
   type LoadConsoleEntriesOptions,

package/client/mediaSrc.test.ts

@@ -0,0 +1,34 @@
+import { describe, expect, it } from 'vitest';
+import { pickMediaRawUrl, resolveMediaSrc } from '../client/mediaSrc.js';
+
+describe('pickMediaRawUrl', () => {
+  it('prefers canonical media.value / url / file', () => {
+    expect(pickMediaRawUrl({ media: { value: 'https://a/b.png' } })).toBe('https://a/b.png');
+    expect(pickMediaRawUrl({ url: 'https://a/b.png' })).toBe('https://a/b.png');
+    expect(pickMediaRawUrl({ file: '/tmp/a.png' })).toBe('/tmp/a.png');
+  });
+
+  it('reads agent outbound image segment (base64 + mime, no url)', () => {
+    // media-publisher 出站形态：{ type:'image', data:{ base64, mime, name } }
+    const raw = pickMediaRawUrl({ base64: 'aGVsbG8=', mime: 'image/png', name: 'system-status.png' });
+    expect(raw).toBe('data:image/png;base64,aGVsbG8=');
+    expect(resolveMediaSrc(raw, 'image')).toBe('data:image/png;base64,aGVsbG8=');
+  });
+
+  it('falls back to base64:// so resolveMediaSrc applies the kind default MIME', () => {
+    const raw = pickMediaRawUrl({ base64: 'aGVsbG8=' });
+    expect(raw).toBe('base64://aGVsbG8=');
+    expect(resolveMediaSrc(raw, 'image')).toBe('data:image/png;base64,aGVsbG8=');
+    expect(resolveMediaSrc(raw, 'audio')).toBe('data:audio/mpeg;base64,aGVsbG8=');
+  });
+
+  it('passes through base64 values that already carry a scheme', () => {
+    expect(pickMediaRawUrl({ base64: 'base64://aGVsbG8=' })).toBe('base64://aGVsbG8=');
+    expect(pickMediaRawUrl({ base64: 'data:image/png;base64,aGVsbG8=' })).toBe('data:image/png;base64,aGVsbG8=');
+  });
+
+  it('returns undefined when no media field exists', () => {
+    expect(pickMediaRawUrl(undefined)).toBeUndefined();
+    expect(pickMediaRawUrl({})).toBeUndefined();
+  });
+});

package/client/mediaSrc.ts

@@ -52,5 +52,20 @@ export function pickMediaRawUrl(data: Record<string, unknown> | undefined): stri
     if (typeof value === 'string' && value.trim()) return value.trim()
   }
   const v = data.url ?? data.file ?? data.src ?? data.href
-  return typeof v === 'string' && v.trim() ? v.trim() : undefined
+  if (typeof v === 'string' && v.trim()) return v.trim()
+  // agent 出站媒体段（media-publisher）直接携带纯 base64，无 url/file；
+  // 有 mime 时拼成 data: URL 透传，否则走 base64:// 让 resolveMediaSrc 按 kind 补默认 MIME
+  const b64 = data.base64
+  if (typeof b64 === 'string' && b64.trim()) {
+    const payload = b64.trim()
+    if (payload.startsWith('data:') || payload.startsWith('base64://')
+      || payload.startsWith('http://') || payload.startsWith('https://')) {
+      return payload
+    }
+    const mime = typeof data.mime === 'string' && data.mime.trim() ? data.mime.trim() : ''
+    return mime
+      ? `data:${mime};base64,${payload.replace(/\s/g, '')}`
+      : `base64://${payload}`
+  }
+  return undefined
 }

package/client/persistence/idb-store.test.ts

@@ -0,0 +1,128 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+import { applyConsoleEvent, idbListInbox } from "./idb-store.js";
+
+/**
+ * 最小内存 IndexedDB stub：仅实现 idb-store 用到的 open/upgrade/getAll/put 语义，
+ * 含版本检查（低版本 open 触发 VersionError）。
+ */
+type StoreData = Map<string, Record<string, unknown>>;
+interface DbData {
+  version: number;
+  stores: Map<string, StoreData>;
+}
+
+function createFakeIndexedDB() {
+  const dbs = new Map<string, DbData>();
+
+  function makeRequest<T>(run: (req: IDBRequest<T>) => void): IDBRequest<T> {
+    const req = {
+      result: undefined as T,
+      error: null as unknown,
+      onsuccess: null as (() => void) | null,
+      onerror: null as (() => void) | null,
+      onupgradeneeded: null as (() => void) | null,
+    } as unknown as IDBRequest<T>;
+    queueMicrotask(() => run(req));
+    return req;
+  }
+
+  function makeDb(data: DbData): IDBDatabase {
+    return {
+      objectStoreNames: {
+        contains: (name: string) => data.stores.has(name),
+      },
+      createObjectStore: (name: string) => {
+        data.stores.set(name, new Map());
+      },
+      transaction: (name: string) => {
+        const store = data.stores.get(name);
+        const tx = {
+          oncomplete: null as (() => void) | null,
+          onerror: null as (() => void) | null,
+          error: null as unknown,
+          objectStore: () => ({
+            getAll: () =>
+              makeRequest<Record<string, unknown>[]>((req) => {
+                (req as { result: unknown }).result = [...(store?.values() ?? [])];
+                req.onsuccess?.();
+              }),
+            put: (record: Record<string, unknown>) => {
+              store?.set(String(record.id), record);
+              queueMicrotask(() => tx.oncomplete?.());
+            },
+          }),
+        };
+        return tx;
+      },
+      close: () => undefined,
+    } as unknown as IDBDatabase;
+  }
+
+  return {
+    open(name: string, version = 1) {
+      return makeRequest<IDBDatabase>((req) => {
+        let data = dbs.get(name);
+        if (data && data.version > version) {
+          (req as { error: unknown }).error = new Error("VersionError");
+          req.onerror?.();
+          return;
+        }
+        const upgrading = !data || data.version < version;
+        if (!data) {
+          data = { version, stores: new Map() };
+          dbs.set(name, data);
+        }
+        data.version = version;
+        (req as { result: unknown }).result = makeDb(data);
+        if (upgrading) req.onupgradeneeded?.();
+        req.onsuccess?.();
+      });
+    },
+  };
+}
+
+const PUSH = {
+  type: "message.receive",
+  data: { adapter: "icqq", endpointId: "bot-1", channelId: "1001" },
+};
+
+describe("applyConsoleEvent inbox record ids", () => {
+  beforeEach(() => {
+    vi.stubGlobal("indexedDB", createFakeIndexedDB());
+  });
+
+  afterEach(() => {
+    vi.unstubAllGlobals();
+    vi.restoreAllMocks();
+  });
+
+  it("keeps two events of the same conversation within one millisecond (no key overwrite)", async () => {
+    // 回归：旧主键 `${adapter}:${endpointId}:${type}:${Date.now()}` 在同毫秒会互相覆盖。
+    vi.spyOn(Date, "now").mockReturnValue(1700000000000);
+    await applyConsoleEvent(PUSH);
+    await applyConsoleEvent(PUSH);
+
+    const rows = await idbListInbox("icqq", "bot-1", "message");
+    expect(rows).toHaveLength(2);
+    expect(new Set(rows.map((r) => r.id)).size).toBe(2);
+  });
+
+  it("reads legacy records that only carry endpointId (camelCase)", async () => {
+    // 旧版（DB v1 时代）记录只有 endpointId 字段，升级后仍需能被列出
+    const { idbPutInbox } = await import("./idb-store.js");
+    const legacy = {
+      id: "icqq:bot-1:message:1700000000000:legacy",
+      adapter: "icqq",
+      endpointId: "bot-1",
+      kind: "message",
+      payload: {},
+      updatedAt: 1700000000000,
+    };
+    await idbPutInbox(legacy as unknown as Parameters<typeof idbPutInbox>[0]);
+
+    const rows = await idbListInbox("icqq", "bot-1", "message");
+    expect(rows).toHaveLength(1);
+    expect(rows[0].id).toBe(legacy.id);
+  });
+});

package/client/persistence/idb-store.ts

@@ -1,8 +1,12 @@
+import { parseConsoleInboxEvent } from "@zhin.js/console-protocol";
+
 const DB_NAME = "zhin-console";
 const DB_VERSION = 2;
 const STORE_INBOX = "inbox";
 const STORE_PENDING = "pending";
 
+let inboxEventSeq = 0;
+
 export type InboxRecord = {
   id: string;
   adapter: string;
@@ -63,20 +67,16 @@ export async function idbListInbox(
 }
 
 export async function applyConsoleEvent(event: { type: string; data?: unknown }): Promise<void> {
-  const t = event.type;
-  if (t === "message.receive" || t === "request.receive" || t === "notice.receive") {
-    const data = event.data as Record<string, unknown> | undefined;
-    if (!data) return;
-    const adapter = String(data.$adapter ?? data.adapter ?? "");
-    const endpoint_id = String(data.$endpoint ?? data.endpoint_id ?? data.endpointId ?? data.bot ?? "");
-    const id = `${adapter}:${endpoint_id}:${t}:${Date.now()}`;
-    await idbPutInbox({
-      id,
-      adapter,
-      endpoint_id,
-      kind: t === "message.receive" ? "message" : t === "request.receive" ? "request" : "notice",
-      payload: data,
-      updatedAt: Date.now(),
-    });
-  }
+  const parsed = parseConsoleInboxEvent(event);
+  if (!parsed) return;
+  const updatedAt = Date.now();
+  await idbPutInbox({
+    // 追加自增+随机后缀：同毫秒同会话的两条事件不会因主键相同而互相覆盖
+    id: `${parsed.adapter}:${parsed.endpointId}:${parsed.type}:${updatedAt}:${inboxEventSeq++}:${Math.random().toString(36).slice(2, 8)}`,
+    adapter: parsed.adapter,
+    endpoint_id: parsed.endpointId,
+    kind: parsed.kind,
+    payload: parsed.payload,
+    updatedAt,
+  });
 }

package/client/websocket/hooks.test.ts

@@ -0,0 +1,21 @@
+import { describe, expect, it } from "vitest";
+
+import { resolveKeyedValue } from "./hooks.js";
+
+describe("resolveKeyedValue (useConfig stale-state guard)", () => {
+  it("returns the value when the entry key matches", () => {
+    const entry = { key: "plugin-a", value: { foo: 1 } };
+    expect(resolveKeyedValue(entry, "plugin-a")).toEqual({ foo: 1 });
+  });
+
+  it("treats a previous plugin's leftover state as empty after pluginName switches", () => {
+    // 回归：旧实现中 config state 跨 pluginName 残留，ready(config != null) 永远为真，
+    // 切换插件后不再自动加载新配置。
+    const stale = { key: "plugin-a", value: { foo: 1 } };
+    expect(resolveKeyedValue(stale, "plugin-b")).toBeNull();
+  });
+
+  it("returns null when nothing has been loaded", () => {
+    expect(resolveKeyedValue(null, "plugin-a")).toBeNull();
+  });
+});

package/client/websocket/hooks.ts

@@ -1,7 +1,25 @@
-import { useCallback, useEffect, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import { getWebSocketManager } from "./instance";
 import type { UseWebSocketOptions } from "./types";
 
+/**
+ * 每次连接会话只对同一 key 自动加载一次：失败后不再零退避死循环
+ * （旧行为：加载失败 → 状态保持空 → effect 反复立即重试，打爆 /api/console/request）。
+ * 断连后重置；key 变化（如 pluginName 切换）视为新目标重新尝试；手动重试走各 hook 返回的 load 函数。
+ */
+function useAutoLoadOnce(connected: boolean, key: unknown, ready: boolean, fire: () => void) {
+  const attemptedRef = useRef<unknown>(undefined);
+  useEffect(() => {
+    if (!connected) {
+      attemptedRef.current = undefined;
+      return;
+    }
+    if (ready || attemptedRef.current === key) return;
+    attemptedRef.current = key;
+    fire();
+  });
+}
+
 export function useWebSocket(options: UseWebSocketOptions = {}) {
   const { autoConnect = true } = options;
   const wsManager = getWebSocketManager();
@@ -26,14 +44,28 @@ export function useWebSocket(options: UseWebSocketOptions = {}) {
   return { connected, connect, disconnect, send, sendRequest, manager: wsManager };
 }
 
+/**
+ * 按 key 绑定异步加载结果：key（如 pluginName）切换后，旧 key 的残留值视为 null，
+ * 避免 useConfig 的 ready 判断（config != null）被上一插件的 state 挡住而不再加载新配置。
+ * @internal
+ */
+export function resolveKeyedValue<T>(
+  entry: { readonly key: string; readonly value: T } | null,
+  key: string,
+): T | null {
+  return entry && entry.key === key ? entry.value : null;
+}
+
 export function useConfig(pluginName: string, options?: { autoLoad?: boolean; autoLoadSchema?: boolean }) {
   const { autoLoad = true, autoLoadSchema = true } = options ?? {};
   const wsManager = getWebSocketManager();
   const [connected, setConnected] = useState(wsManager.isConnected());
-  const [config, setConfigState] = useState<unknown>(null);
-  const [schema, setSchemaState] = useState<unknown>(null);
+  const [configEntry, setConfigEntry] = useState<{ key: string; value: unknown } | null>(null);
+  const [schemaEntry, setSchemaEntry] = useState<{ key: string; value: unknown } | null>(null);
   const [loading, setLoading] = useState(false);
   const [error, setError] = useState<string | null>(null);
+  const config = resolveKeyedValue(configEntry, pluginName);
+  const schema = resolveKeyedValue(schemaEntry, pluginName);
 
   useEffect(() => wsManager.onConnectionChange(setConnected), [wsManager]);
 
@@ -42,7 +74,7 @@ export function useConfig(pluginName: string, options?: { autoLoad?: boolean; au
     setError(null);
     try {
       const result = await wsManager.getConfig(pluginName);
-      setConfigState(result);
+      setConfigEntry({ key: pluginName, value: result });
       return result;
     } catch (e) {
       setError(e instanceof Error ? e.message : "Unknown error");
@@ -71,20 +103,19 @@ export function useConfig(pluginName: string, options?: { autoLoad?: boolean; au
   const getSchema = useCallback(async () => {
     try {
       const result = await wsManager.getSchema(pluginName);
-      if (result) setSchemaState(result);
+      if (result) setSchemaEntry({ key: pluginName, value: result });
       return result;
     } catch (e) {
       throw e;
     }
   }, [pluginName, wsManager]);
 
-  useEffect(() => {
-    if (connected && autoLoad && !config && !loading) getConfig().catch(() => {});
-  }, [connected, autoLoad, config, loading, getConfig]);
-
-  useEffect(() => {
-    if (connected && autoLoadSchema && !schema) getSchema().catch(() => {});
-  }, [connected, autoLoadSchema, schema, getSchema]);
+  useAutoLoadOnce(connected, `config:${pluginName}`, !autoLoad || config != null || loading, () => {
+    getConfig().catch(() => {});
+  });
+  useAutoLoadOnce(connected, `schema:${pluginName}`, !autoLoadSchema || schema != null, () => {
+    getSchema().catch(() => {});
+  });
 
   return useMemo(
     () => ({ config, schema, loading, error, connected, getConfig, setConfig, getSchema }),
@@ -136,9 +167,9 @@ export function useConfigYaml() {
     [wsManager],
   );
 
-  useEffect(() => {
-    if (connected && !yaml && !loading) load().catch(() => {});
-  }, [connected, yaml, loading, load]);
+  useAutoLoadOnce(connected, "config-yaml", !!yaml || loading, () => {
+    load().catch(() => {});
+  });
 
   return useMemo(() => ({ yaml, pluginKeys, loading, error, load, save }), [yaml, pluginKeys, loading, error, load, save]);
 }
@@ -173,9 +204,9 @@ export function useFiles() {
     [wsManager],
   );
 
-  useEffect(() => {
-    if (connected && tree.length === 0 && !loading) loadTree().catch(() => {});
-  }, [connected, tree.length, loading, loadTree]);
+  useAutoLoadOnce(connected, "file-tree", tree.length > 0 || loading, () => {
+    loadTree().catch(() => {});
+  });
 
   return useMemo(() => ({ tree, loading, error, loadTree, readFile, saveFile }), [tree, loading, error, loadTree, readFile, saveFile]);
 }
@@ -217,9 +248,9 @@ export function useEnvFiles() {
     [wsManager],
   );
 
-  useEffect(() => {
-    if (connected && files.length === 0 && !loading) listFiles().catch(() => {});
-  }, [connected, files.length, loading, listFiles]);
+  useAutoLoadOnce(connected, "env-files", files.length > 0 || loading, () => {
+    listFiles().catch(() => {});
+  });
 
   return useMemo(
     () => ({ files, loading, error, listFiles, getFile, saveFile }),
@@ -275,12 +306,10 @@ export function useDatabase() {
   const kvDelete = useCallback(async (table: string, key: string) => wsManager.kvDelete(table, key), [wsManager]);
   const kvEntries = useCallback(async (table: string) => wsManager.kvGetEntries(table), [wsManager]);
 
-  useEffect(() => {
-    if (connected && !info && !loading) {
-      loadInfo().catch(() => {});
-      loadTables().catch(() => {});
-    }
-  }, [connected, info, loading, loadInfo, loadTables]);
+  useAutoLoadOnce(connected, "db-info", info != null || loading, () => {
+    loadInfo().catch(() => {});
+    loadTables().catch(() => {});
+  });
 
   return useMemo(
     () => ({ info, tables, loading, error, loadInfo, loadTables, dropTable, select, insert, update, remove, kvGet, kvSet, kvDelete, kvEntries }),