@forgeax/interface 0.4.1

package/dist/package/node/lib/agent-cli-provider.js

@@ -0,0 +1,81 @@
+/** Map agent manifest `preferredCliProvider` → kernel id used by `/api/cli/chat`.
+ *
+ *  Kernel ids match `packages/orchestrator/src/kernel/*-kernel.ts` and the Composer
+ *  provider picker (`cursor-agent`, `claude-code`, `codex`, …). `null` means
+ *  the forgeax-native EventBus path (no CLI subprocess). */
+import { listExtensionsShared } from './extension-api.js';
+/** Marketplace cli-provider plugin id → runtime kernel id. */
+const PREFERRED_CLI_TO_KERNEL = {
+    'forgeax-native': null,
+    '@forgeax-plugin/cli-forgeax': null,
+    '@forgeax-plugin/cli-claude-code': 'claude-code',
+    '@forgeax-plugin/cli-bc': 'claude-code',
+    '@forgeax-plugin/cli-codex': 'codex',
+    '@forgeax-plugin/cli-cursor-agent': 'cursor-agent',
+    '@forgeax-plugin/cli-kimi-code': 'kimi-code',
+    '@forgeax-plugin/cli-deepseek-harness': 'deepseek-harness',
+};
+/** Fallback when bus is unavailable (standalone editor / boot race). */
+const AGENT_KERNEL_FALLBACK = {
+    'cursor-default': 'cursor-agent',
+    'codex-default': 'codex',
+    'claude-code-default': 'claude-code',
+    'cc-coder': 'claude-code',
+    'kimi-code-default': 'kimi-code',
+    'deepseek-harness-default': 'deepseek-harness',
+};
+export function preferredCliProviderToKernel(preferred) {
+    const key = preferred?.trim();
+    if (!key)
+        return null;
+    if (key in PREFERRED_CLI_TO_KERNEL)
+        return PREFERRED_CLI_TO_KERNEL[key] ?? null;
+    // Already a kernel id (defensive).
+    if (key === 'claude-code' || key === 'codex' || key === 'cursor-agent' || key === 'codebuddy' || key === 'kimi-code' || key === 'deepseek-harness')
+        return key;
+    return null;
+}
+let agentExtensionsCache = null;
+let agentExtensionsInflight = null;
+async function loadAgentExtensions() {
+    if (agentExtensionsCache)
+        return agentExtensionsCache;
+    if (!agentExtensionsInflight) {
+        agentExtensionsInflight = listExtensionsShared()
+            .then((res) => res.items.filter((p) => p.kind === 'agent'))
+            .then((items) => {
+            agentExtensionsCache = items;
+            agentExtensionsInflight = null;
+            return items;
+        })
+            .catch(() => {
+            agentExtensionsInflight = null;
+            return [];
+        });
+    }
+    return agentExtensionsInflight;
+}
+/** Resolve the CLI kernel id for an agent path/display id (e.g. `cursor-default`). */
+export async function resolveKernelForAgent(agentId) {
+    const key = agentId.trim();
+    if (!key)
+        return null;
+    const plugins = await loadAgentExtensions();
+    const hit = plugins.find((p) => {
+        const id = p.agent?.id;
+        if (!id)
+            return false;
+        if (id === key)
+            return true;
+        return key.startsWith(`${id}#`);
+    });
+    if (hit?.agent?.preferredCliProvider) {
+        return preferredCliProviderToKernel(hit.agent.preferredCliProvider);
+    }
+    return AGENT_KERNEL_FALLBACK[key] ?? null;
+}
+/** Test-only: bust the bus agent cache between cases. */
+export function _resetAgentCliProviderCacheForTests() {
+    agentExtensionsCache = null;
+    agentExtensionsInflight = null;
+}

package/dist/package/node/lib/ai-intents.js

@@ -0,0 +1,52 @@
+import { getAction } from './action-registry.js';
+/** 按 RefDescriptor.kind 的专属 intent(SSOT:每类可引用单元的 AI 动作都列在这里)。 */
+const KIND_INTENTS = {
+    'console-row': [
+        { label: '解释这个报错', buildDetail: (p) => `请解释下面这条游戏控制台输出的含义与可能原因:\n${p.detail}` },
+        { label: '帮我修掉', buildDetail: (p) => `下面这条游戏控制台报错来自当前游戏,请定位原因并修复对应代码:\n${p.detail}` },
+    ],
+    file: [
+        { label: '看看这个文件', buildDetail: (p) => `请读一下这个文件并概述它的职责与关键逻辑:\n${p.detail}` },
+    ],
+    'preview-game': [
+        { label: '给这个游戏提建议', buildDetail: (p) => `请体验性地评审这个游戏(可用 query_world/capture_frame 取真值),给出改进建议:\n${p.detail}` },
+    ],
+};
+const GENERIC_INTENT = {
+    label: '问 AI 这是什么',
+    buildDetail: (p) => `请解释下面引用的这个对象是什么、当前状态如何:\n${p.detail}`,
+};
+/** 给一个可引用单元列出 intent(kind 专属在前,通用兜底在后)。 */
+export function aiIntentsFor(refKind) {
+    return [...(refKind ? (KIND_INTENTS[refKind] ?? []) : []), GENERIC_INTENT];
+}
+/** 把「原 pill × intent」加工成插 composer 的意图 pill(chip 显示意图名,detail 是完整指令)。 */
+export function intentPill(pill, intent) {
+    return {
+        kind: pill.kind,
+        display: `${intent.label}:${pill.display}`,
+        icon: '🤖',
+        detail: intent.buildDetail(pill),
+        tooltip: { title: `🤖 ${intent.label}`, lines: [pill.display] },
+    };
+}
+/** 从 ActionRegistry derive 的右键项(方案 §3C.2):右键落在 data-fx-action 元素上
+ *  → 「让 AI 执行此功能」。返回 null = 目标不在任何已登记 action 上。 */
+export function actionIntentPill(target) {
+    const el = target.closest('[data-fx-action]');
+    const id = el?.dataset.fxAction?.trim();
+    if (!el || !id)
+        return null;
+    const def = getAction(id);
+    const title = def?.title ?? el.dataset.fxTitle?.trim() ?? id;
+    return {
+        title,
+        pill: {
+            kind: 'tool',
+            display: `执行:${title}`,
+            icon: '🤖',
+            detail: `请通过 ui_invoke 执行 UI action "${id}"(${title})。若需要参数,先用 ui_snapshot { detail:'schema', ids:['${id}'] } 查看 schema。`,
+            tooltip: { title: `🤖 让 AI 执行此功能`, lines: [title, id] },
+        },
+    };
+}

package/dist/package/node/lib/broadcast-stream.js

@@ -0,0 +1,163 @@
+// interface 公共广播 WS primitive —— 全页唯一一条 `/ws` 广播连接，按帧 `type` 分发。
+//
+// 设计意图（R5 store 收敛 · WS 归位）：
+//  - 后端在 `/ws`（无 sid）上 broadcast 一批 app-agnostic 帧：`daemon-tick-*`（chat）、
+//    `telemetry`（观测）等 app-agnostic 帧。它们本是**同一条广播流**，
+//    R4 期间被拆成了两条 raw socket（store.connectDaemonWs + chat/daemon-tick.ts）。
+//  - 本 primitive 把它收敛回**一条**：全页单例、按 `msg.type` 字符串分发给订阅者。
+//    它**不认识**任何帧的含义（daemon-tick 归 chat、telemetry 归观测），只做传输 + 分发。
+//  - 「按 type 客户端分发」≠「后端多路复用」：后端本就 broadcast 全部帧，此处零后端改动。
+//
+// 关键纪律：**不在 module-load 自动连**（那是 R4 前 store 的反模式：import 即偷偷开 socket）。
+// 由挂载方 boot 显式调 `connect()` 一次 —— studio 聚合壳 boot 一次；各独立 app boot 各一次。
+// 全页因此只有一条广播 socket。
+//
+// HMR 安全：socket + 订阅表挂 globalThis；模块重求值时不重复建连、不丢订阅。
+const _STREAM_FLAG = '__FORGEAX_BROADCAST_STREAM__';
+const _gt = globalThis;
+const _s = _gt[_STREAM_FLAG] ??
+    (_gt[_STREAM_FLAG] = {
+        ws: null,
+        desired: false,
+        url: '',
+        retryMs: 1000,
+        retryTimer: null,
+        handlers: new Map(),
+    });
+const RECONNECT_MAX_MS = 30_000;
+function defaultUrl() {
+    const proto = window.location.protocol === 'https:' ? 'wss:' : 'ws:';
+    return `${proto}//${window.location.host}/ws`;
+}
+function dispatch(msg) {
+    const type = typeof msg.type === 'string' ? msg.type : '';
+    const exact = type ? _s.handlers.get(type) : undefined;
+    const wildcard = _s.handlers.get('*');
+    if (exact) {
+        for (const h of [...exact]) {
+            try {
+                h(msg);
+            }
+            catch (err) {
+                console.warn(`[broadcast-stream] handler "${type}" threw`, err);
+            }
+        }
+    }
+    if (wildcard) {
+        for (const h of [...wildcard]) {
+            try {
+                h(msg);
+            }
+            catch (err) {
+                console.warn('[broadcast-stream] "*" handler threw', err);
+            }
+        }
+    }
+}
+function open() {
+    if (typeof window === 'undefined')
+        return;
+    if (_s.ws && _s.ws.readyState !== WebSocket.CLOSED)
+        return;
+    let ws;
+    try {
+        ws = new WebSocket(_s.url || defaultUrl());
+    }
+    catch {
+        scheduleReconnect();
+        return;
+    }
+    _s.ws = ws;
+    ws.onopen = () => {
+        if (_s.ws !== ws)
+            return;
+        _s.retryMs = 1000;
+    };
+    ws.onmessage = (e) => {
+        if (_s.ws !== ws)
+            return;
+        let obj;
+        try {
+            obj = JSON.parse(typeof e.data === 'string' ? e.data : '');
+        }
+        catch {
+            return;
+        }
+        if (obj && typeof obj === 'object')
+            dispatch(obj);
+    };
+    ws.onclose = () => {
+        if (_s.ws !== ws)
+            return;
+        _s.ws = null;
+        if (_s.desired)
+            scheduleReconnect();
+    };
+    ws.onerror = () => {
+        try {
+            ws.close();
+        }
+        catch { /* ignore */ }
+    };
+}
+function scheduleReconnect() {
+    if (_s.retryTimer !== null)
+        return;
+    if (!_s.desired)
+        return;
+    _s.retryTimer = window.setTimeout(() => {
+        _s.retryTimer = null;
+        _s.retryMs = Math.min(_s.retryMs * 2, RECONNECT_MAX_MS);
+        if (_s.desired)
+            open();
+    }, _s.retryMs);
+}
+/** boot 时调一次，拉起全页唯一的广播连接。幂等：已连则 no-op。
+ *  @param url 可注入（默认 `${location.host}/ws`）——留一个注入点，方便未来 mock/回放。 */
+export function connect(url) {
+    if (typeof window === 'undefined')
+        return;
+    _s.desired = true;
+    if (url)
+        _s.url = url;
+    if (_s.ws && _s.ws.readyState !== WebSocket.CLOSED)
+        return;
+    _s.retryMs = 1000;
+    open();
+}
+/** 显式断开（一般不用；测试/卸载壳时可用）。 */
+export function disconnect() {
+    _s.desired = false;
+    if (_s.retryTimer !== null) {
+        window.clearTimeout(_s.retryTimer);
+        _s.retryTimer = null;
+    }
+    if (_s.ws) {
+        try {
+            _s.ws.close();
+        }
+        catch { /* ignore */ }
+        _s.ws = null;
+    }
+}
+/** 订阅某 `type` 的广播帧，返回 unsubscribe。`type='*'` 收全部帧。 */
+export function subscribeBroadcast(type, handler) {
+    let set = _s.handlers.get(type);
+    if (!set) {
+        set = new Set();
+        _s.handlers.set(type, set);
+    }
+    set.add(handler);
+    return () => {
+        const cur = _s.handlers.get(type);
+        if (cur) {
+            cur.delete(handler);
+            if (cur.size === 0)
+                _s.handlers.delete(type);
+        }
+    };
+}
+/** 连接状态（调试/健康灯用）。 */
+export function getBroadcastStatus() {
+    return { connected: _s.ws?.readyState === WebSocket.OPEN, url: _s.url || (typeof window !== 'undefined' ? defaultUrl() : '') };
+}

package/dist/package/node/lib/browser-prefs-sync.js

@@ -0,0 +1,151 @@
+/** Persist + restore browser localStorage UI prefs via `/api/prefs/browser-localStorage`.
+ *  Snapshot lands in `.forgeax/prefs/browser-localStorage.json` for export-instance. */
+import { installStorageObservation } from '@forgeax/app-shell/react';
+import { STORAGE_KEYS } from './storageKeys.js';
+const SYNC_DEBOUNCE_MS = 1500;
+const SYNC_INTERVAL_MS = 30_000;
+const KEY_PREFIXES = ['forgeax.', 'forgeax:project:'];
+// First-run onboarding is a per-browser-profile gate, NOT a portable UI pref.
+// Mirroring it through the server snapshot re-seeds a stale phase back into
+// localStorage on every load (and races the async restore against first paint),
+// which silently kills / replays the wizard and makes a local reset impossible.
+// Keep onboarding purely local: excluding here blocks BOTH push and restore
+// (restoreBrowserLocalStorage also gates on shouldSyncKey), so any pre-existing
+// snapshot entries become inert. Trade-off: an imported instance re-runs the
+// first-run flow once — acceptable, and safer than silently skipping it.
+const KEY_EXCLUDE = new Set([
+    STORAGE_KEYS.onboarding,
+    STORAGE_KEYS.onboardingSeenLegacy,
+]);
+function shouldSyncKey(key) {
+    if (KEY_EXCLUDE.has(key))
+        return false;
+    return KEY_PREFIXES.some((p) => key.startsWith(p));
+}
+export function captureBrowserLocalStorage() {
+    if (typeof window === 'undefined')
+        return {};
+    const entries = {};
+    try {
+        for (let i = 0; i < window.localStorage.length; i++) {
+            const key = window.localStorage.key(i);
+            if (!key || !shouldSyncKey(key))
+                continue;
+            const val = window.localStorage.getItem(key);
+            if (val !== null)
+                entries[key] = val;
+        }
+    }
+    catch {
+        /* private mode */
+    }
+    return entries;
+}
+export function restoreBrowserLocalStorage(entries) {
+    if (typeof window === 'undefined')
+        return 0;
+    let n = 0;
+    try {
+        for (const [key, val] of Object.entries(entries)) {
+            if (!shouldSyncKey(key) || typeof val !== 'string')
+                continue;
+            // Non-destructive: never overwrite a value that already exists locally.
+            // localStorage survives reloads natively, so a fresh same-tab change
+            // (e.g. resetting the dock layout) must win over the periodically-pushed
+            // server snapshot — which is only refreshed on the 30s interval /
+            // unreliable beforeunload. Only fill genuinely-missing keys (fresh
+            // browser, cleared storage, or import into a fresh profile).
+            if (window.localStorage.getItem(key) !== null)
+                continue;
+            window.localStorage.setItem(key, val);
+            n += 1;
+        }
+    }
+    catch {
+        /* ignore */
+    }
+    return n;
+}
+async function pushBrowserPrefs() {
+    const entries = captureBrowserLocalStorage();
+    if (Object.keys(entries).length === 0)
+        return;
+    try {
+        await fetch('/api/prefs/browser-localStorage', {
+            method: 'PUT',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                v: 1,
+                exportedAt: new Date().toISOString(),
+                origin: window.location.origin,
+                entries,
+            }),
+        });
+    }
+    catch {
+        /* server may be down during boot */
+    }
+}
+/** Push the current localStorage snapshot to the server immediately (no debounce).
+ *  Call after a same-tab pref change that must survive a quick reload — the
+ *  `storage` event only fires in OTHER tabs, so same-tab writes are otherwise
+ *  only flushed on the 30s interval / beforeunload (unreliable). */
+export function flushBrowserPrefs() {
+    void pushBrowserPrefs();
+}
+/** Pull server snapshot into localStorage. Non-destructive: the snapshot only
+ *  fills keys that are MISSING locally (fresh browser / cleared storage / import
+ *  into a fresh profile). On a normal reload the local value always wins, so a
+ *  same-tab change (e.g. layout reset) is never clobbered by a stale snapshot. */
+export async function syncBrowserPrefsFromServer() {
+    try {
+        const res = await fetch('/api/prefs/browser-localStorage');
+        if (!res.ok)
+            return 0;
+        // Standalone (no backend) serves the SPA index.html for unknown /api
+        // routes — a 200 with text/html. Guard against parsing that as JSON.
+        if (!res.headers.get('content-type')?.includes('application/json'))
+            return 0;
+        const snap = (await res.json());
+        if (!snap.entries || Object.keys(snap.entries).length === 0)
+            return 0;
+        return restoreBrowserLocalStorage(snap.entries);
+    }
+    catch {
+        return 0;
+    }
+}
+let debounceTimer;
+let started = false;
+function schedulePush() {
+    if (debounceTimer)
+        clearTimeout(debounceTimer);
+    debounceTimer = setTimeout(() => {
+        debounceTimer = undefined;
+        void pushBrowserPrefs();
+    }, SYNC_DEBOUNCE_MS);
+}
+/** Start periodic + event-driven sync to server (call once from main.tsx). */
+export function startBrowserPrefsSync() {
+    if (started || typeof window === 'undefined')
+        return;
+    started = true;
+    const onBrowserPreferenceStorage = (e) => {
+        if (e.key && shouldSyncKey(e.key))
+            schedulePush();
+    };
+    void installStorageObservation({ target: window, onStorage: onBrowserPreferenceStorage });
+    window.addEventListener('beforeunload', () => {
+        void pushBrowserPrefs();
+    });
+    const interval = window.setInterval(() => {
+        void pushBrowserPrefs();
+    }, SYNC_INTERVAL_MS);
+    window.addEventListener('beforeunload', () => {
+        window.clearInterval(interval);
+    });
+    // Initial push after UI settles (captures keys written during boot).
+    window.setTimeout(() => {
+        void pushBrowserPrefs();
+    }, 4000);
+}