@forgeax/interface 0.4.1

package/dist/package/browser/lib/composer-bridge.js

@@ -0,0 +1,448 @@
+// composer-bridge — the interface foundation's cross-app contract for the Chat composer.
+//
+// This is the chrome-level bridge any app/surface uses to push a reference into
+// the chat composer WITHOUT sharing the chat store's internals. It owns three
+// concerns that must stay in interface (per R4, docs/v2-vision/architecture-
+// evolution/17): (1) the `PillPayload` wire model + sentinel codec, (2) the
+// reference registry that maps a DOM target to a pill, and (3) the pending-
+// insert slot (`requestComposerInsert` / `useComposerPendingInsert`). The chat
+// app (@forgeax/chat) and chrome (App.tsx / ContextMenu / TopBar) talk through
+// these exports; the chat store no longer exposes a `composerPendingInsert`
+// field on `useShellStore`.
+//
+// ── Reference registry — the SINGLE source of truth for "what can be referenced
+//    into the Chat composer, and how".
+//
+// Background (see docs/features/editor-mode/editor-mode-architecture-review.md §A1):
+// the right-click "引用到 Chat" pill used to be built by a 14-branch closest()
+// chain in pill.ts AND a parallel closest() chain in menuRegistry.ts. The
+// contract (which CSS class + data-* a component must expose to be referenceable)
+// was implicit and duplicated — rename a class and references silently broke.
+//
+// Now there is ONE list (`REFERENCE_REGISTRY`). Both the pill builder
+// (`buildPillFromTarget`) and the context-menu builder (`buildMenu`) read it.
+// To make a new unit referenceable you add ONE entry here and expose the
+// documented data-* attributes on its DOM node — nothing else.
+//
+// ── data-* contract ─────────────────────────────────────────────────────────
+//   file row      .fp-row.file            data-fp-path (or .fp-name text)
+//   dir row       .fp-row.dir             .fp-name text
+//   agent card    .agent-card             data-agent-id (+ .ac-name text, data-role)
+//   agent page card .agents-agent-card        data-agent-id, data-agent-name
+//   preview game  .preview-toolbar        data-game-slug
+//   console line  .console-row            (text content)
+//   workspace tab .mode-tab               data-ws-id, data-ws-name
+//   game row      .tb-game-row            data-game-slug
+//   session row   .tb-game-row            data-session-id, data-session-name
+//   chat msg      .kc-text/.kc-body       (text content)
+//   user msg      .user-bubble            (text content)
+//   bus plugin    [data-extension-id]        data-extension-id (+ first text line)
+// ─────────────────────────────────────────────────────────────────────────────
+import { create } from 'zustand';
+import { t } from '../i18n';
+/** Pill kinds kept as chips in chat history (others expand to detail text). */
+const DISPLAY_PRESERVE_KINDS = new Set(['skill', 'command']);
+const SENTINEL_RE = /⟦pill:([A-Za-z0-9_\-]+=*)⟧/g;
+function b64urlEncode(s) {
+    const bytes = new TextEncoder().encode(s);
+    let bin = '';
+    for (let i = 0; i < bytes.length; i++)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_');
+}
+function b64urlDecode(s) {
+    const norm = s.replace(/-/g, '+').replace(/_/g, '/');
+    const pad = norm.length % 4 ? '='.repeat(4 - (norm.length % 4)) : '';
+    const bin = atob(norm + pad);
+    const bytes = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        bytes[i] = bin.charCodeAt(i);
+    return new TextDecoder().decode(bytes);
+}
+export function encodePill(p) {
+    return `⟦pill:${b64urlEncode(JSON.stringify(p))}⟧`;
+}
+export function decodePill(token) {
+    const m = token.match(/^⟦pill:([A-Za-z0-9_\-]+=*)⟧$/);
+    if (!m)
+        return null;
+    try {
+        const obj = JSON.parse(b64urlDecode(m[1]));
+        if (!obj || typeof obj !== 'object' || !obj.kind || !obj.detail)
+            return null;
+        return obj;
+    }
+    catch {
+        return null;
+    }
+}
+export function parseSegments(text) {
+    const out = [];
+    let last = 0;
+    for (const m of text.matchAll(SENTINEL_RE)) {
+        const idx = m.index ?? 0;
+        if (idx > last)
+            out.push({ kind: 'text', text: text.slice(last, idx) });
+        const payload = decodePill(m[0]);
+        if (payload)
+            out.push({ kind: 'pill', token: m[0], payload });
+        else
+            out.push({ kind: 'text', text: m[0] });
+        last = idx + m[0].length;
+    }
+    if (last < text.length)
+        out.push({ kind: 'text', text: text.slice(last) });
+    return out;
+}
+export function expandPills(text) {
+    return text.replace(SENTINEL_RE, (full) => {
+        const p = decodePill(full);
+        return p ? p.detail : full;
+    });
+}
+/** Expand pills for transcript display — paste/file/etc. become detail text;
+ *  skill/command pills stay as sentinels so PillText renders tag chips. */
+export function expandPillsForDisplay(text) {
+    return text.replace(SENTINEL_RE, (full) => {
+        const p = decodePill(full);
+        if (!p)
+            return full;
+        if (DISPLAY_PRESERVE_KINDS.has(p.kind))
+            return full;
+        return p.detail;
+    });
+}
+/** Build a slash-trigger pill for the composer slash menu (skill or server command). */
+export function buildSlashPill(p) {
+    const trigger = p.trigger.startsWith('/') ? p.trigger : `/${p.trigger}`;
+    const kind = p.source === 'skill' ? 'skill' : 'command';
+    const title = p.displayName?.trim() || trigger;
+    const desc = p.description?.trim();
+    return {
+        kind,
+        display: trigger,
+        detail: trigger,
+        tooltip: {
+            title: kind === 'skill' ? `✦ ${title}` : trigger,
+            lines: [desc, kind === 'skill' ? 'Skill' : 'Command'].filter(Boolean),
+        },
+    };
+}
+function buildLegacySlashPill(trigger) {
+    return buildSlashPill({ trigger, source: 'command' });
+}
+/** Parse message text for display — pill sentinels + leading `/command` tags. */
+export function parseDisplaySegments(text) {
+    const segs = parseSegments(text);
+    if (segs.length === 0)
+        return segs;
+    const first = segs[0];
+    if (first.kind !== 'text')
+        return segs;
+    const m = first.text.match(/^(\/[a-z][a-z0-9_-]*)([\s\S]*)$/i);
+    if (!m)
+        return segs;
+    const out = [
+        { kind: 'pill', token: '', payload: buildLegacySlashPill(m[1]) },
+    ];
+    if (m[2])
+        out.push({ kind: 'text', text: m[2] });
+    if (segs.length > 1)
+        out.push(...segs.slice(1));
+    return out;
+}
+/** Canonical visible label for the "send this into Chat" action. The ONLY
+ *  place this string is defined — every menu reads it so the wording can never
+ *  drift (it previously existed as 3 variants). */
+export const REFERENCE_LABEL = t('reference.send_to_chat');
+const text = (el) => (el?.textContent ?? '').trim();
+const truncate = (s, n) => (s.length > n ? s.slice(0, n) + '…' : s);
+export const REFERENCE_REGISTRY = [
+    {
+        kind: 'file',
+        match: '.fp-row.file',
+        build: (el) => {
+            const path = el.dataset.fpPath || text(el.querySelector('.fp-name'));
+            if (!path)
+                return null;
+            const name = path.split('/').pop() || path;
+            return {
+                kind: 'file', display: name, icon: '📄',
+                detail: `[${t('reference.file_ref')}: \`${path}\`]`,
+                tooltip: { title: `📄 ${t('reference.file')} · ${name}`, lines: [`${t('reference.path')}: ${path}`, t('reference.chip_hint')] },
+            };
+        },
+        copy: (el) => {
+            const path = el.dataset.fpPath || text(el.querySelector('.fp-name'));
+            const name = path.split('/').pop() || path;
+            return name ? [{ label: t('reference.copy_file_name'), text: name }] : [];
+        },
+    },
+    {
+        kind: 'dir',
+        match: '.fp-row.dir',
+        build: (el) => {
+            const name = text(el.querySelector('.fp-name'));
+            if (!name)
+                return null;
+            return {
+                kind: 'dir', display: name, icon: '📁',
+                detail: `[${t('reference.dir_ref')}: \`${name}\`]`,
+                tooltip: { title: `📁 ${t('reference.directory')} · ${name}`, lines: [`${t('reference.dir_name')}: ${name}`] },
+            };
+        },
+    },
+    {
+        kind: 'agent',
+        match: '.agent-card',
+        build: (el) => {
+            const agentId = el.dataset.agentId || '';
+            if (!agentId)
+                return null;
+            const name = text(el.querySelector('.ac-name')).replace('★', '').trim() || agentId;
+            const role = el.dataset.role || '';
+            return {
+                kind: 'agent', display: name || agentId, icon: '🤝',
+                detail: `@${agentId}`,
+                tooltip: { title: `🤝 Agent · ${name}`, lines: [`id: ${agentId}`, role ? `role: ${role}` : ''].filter(Boolean) },
+            };
+        },
+    },
+    {
+        kind: 'agent-page',
+        match: '.agents-agent-card[data-agent-id]',
+        build: (el) => {
+            const agentId = el.dataset.agentId || '';
+            if (!agentId)
+                return null;
+            const name = el.dataset.agentName || agentId;
+            return {
+                kind: 'agent', display: name, icon: '🤝',
+                detail: `@${agentId}`,
+                tooltip: { title: `🤝 Agent · ${name}`, lines: [`id: ${agentId}`] },
+            };
+        },
+    },
+    {
+        kind: 'preview-game',
+        match: '.preview-toolbar',
+        build: (el) => {
+            const slug = el.dataset.gameSlug || '';
+            if (!slug)
+                return null;
+            return {
+                kind: 'game', display: slug, icon: '🎮',
+                detail: `[${t('reference.current_game_ref')}: \`games/${slug}\`]`,
+                tooltip: { title: `🎮 ${t('reference.current_game')} · ${slug}`, lines: [`slug: ${slug}`, `${t('reference.path_prefix')}: .forgeax/games/${slug}/`] },
+            };
+        },
+    },
+    {
+        kind: 'console-row',
+        match: '.console-row',
+        build: (el) => {
+            const line = text(el);
+            if (!line)
+                return null;
+            return {
+                kind: 'log', display: truncate(line, 40), icon: '📜',
+                detail: `[${t('reference.console_log')}: \`${line}\`]`,
+                tooltip: { title: t('reference.console_log_line'), lines: [line] },
+            };
+        },
+        copy: (el) => { const line = text(el); return line ? [{ label: t('reference.copy_log_line'), text: line }] : []; },
+    },
+    {
+        kind: 'workspace-tab',
+        match: '.mode-tab[data-ws-id]',
+        ownMenu: true, // TopBar opens a dedicated rename/delete/reference menu
+        build: (el) => {
+            const wsId = el.dataset.wsId || '';
+            if (!wsId)
+                return null;
+            return buildWorkspacePill(wsId, el.dataset.wsName || wsId);
+        },
+    },
+    {
+        kind: 'game-row',
+        match: '.tb-game-row[data-game-slug]',
+        build: (el) => {
+            const slug = el.dataset.gameSlug || '';
+            if (!slug)
+                return null;
+            return {
+                kind: 'game', display: slug, icon: '🎮',
+                detail: `[${t('reference.game_ref')}: \`games/${slug}\`]`,
+                tooltip: { title: `🎮 Game · ${slug}`, lines: [`${t('reference.path')}: .forgeax/games/${slug}/`, `slug: ${slug}`] },
+            };
+        },
+        copy: (el) => { const s = el.dataset.gameSlug || ''; return s ? [{ label: t('reference.copy_slug'), text: s }] : []; },
+    },
+    {
+        kind: 'session-row',
+        match: '.tb-game-row[data-session-id]',
+        build: (el) => {
+            const sid = el.dataset.sessionId || '';
+            if (!sid)
+                return null;
+            const name = el.dataset.sessionName || sid.slice(0, 8);
+            return {
+                kind: 'tool', display: name, icon: '💬',
+                detail: `[${t('reference.session_ref')}: sid=${sid} name="${name}"]`,
+                tooltip: { title: `💬 Session · ${name}`, lines: [`sid: ${sid}`] },
+            };
+        },
+        copy: (el) => { const s = el.dataset.sessionId || ''; return s ? [{ label: t('reference.copy_session_id'), text: s }] : []; },
+    },
+    {
+        kind: 'chat-msg',
+        match: '.kc-text, .kc-body',
+        build: (el) => {
+            const raw = text(el);
+            if (!raw)
+                return null;
+            const head = truncate(raw, 60);
+            return {
+                kind: 'log', display: head, icon: '💭',
+                detail: `[${t('reference.chat_ref')}: "${truncate(raw, 200)}"]`,
+                tooltip: { title: `💭 ${t('reference.chat_message_ref')}`, lines: [head] },
+            };
+        },
+        copy: (el) => { const m = text(el); return m ? [{ label: t('reference.copy_message'), text: m }] : []; },
+    },
+    {
+        kind: 'user-msg',
+        match: '.user-bubble',
+        build: (el) => {
+            const raw = text(el);
+            if (!raw)
+                return null;
+            const head = truncate(raw, 60);
+            return {
+                kind: 'log', display: head, icon: '🧑',
+                detail: `[${t('reference.user_message_ref')}: "${truncate(raw, 200)}"]`,
+                tooltip: { title: `🧑 ${t('reference.user_message_ref')}`, lines: [head] },
+            };
+        },
+        copy: (el) => { const m = text(el); return m ? [{ label: t('reference.copy_message'), text: m }] : []; },
+    },
+    {
+        kind: 'bus-plugin',
+        match: '[data-extension-id]',
+        build: (el) => {
+            const extensionId = el.dataset.extensionId || '';
+            if (!extensionId)
+                return null;
+            const label = truncate(text(el).split('\n')[0] || extensionId, 40);
+            return {
+                kind: 'tool', display: label || extensionId, icon: '🔌',
+                detail: `[${t('reference.bus_extension_ref')}: id="${extensionId}" label="${label}"]`,
+                tooltip: { title: `🔌 ${t('reference.bus_extension')} · ${label}`, lines: [`extension id: ${extensionId}`] },
+            };
+        },
+        copy: (el) => { const id = el.dataset.extensionId || ''; return id ? [{ label: t('reference.copy_extension_id'), text: id }] : []; },
+    },
+];
+/** Walk the registry and return the first matching unit for an event target. */
+export function buildReferenceFor(target) {
+    if (!target)
+        return null;
+    for (const descriptor of REFERENCE_REGISTRY) {
+        const el = target.closest(descriptor.match);
+        if (!el)
+            continue;
+        const pill = descriptor.build(el);
+        if (pill)
+            return { el, descriptor, pill };
+        // matched the selector but data was missing — keep trying other descriptors.
+    }
+    return null;
+}
+/** Back-compat thin wrapper: DOM target → pill payload (or null). */
+export function buildPillFromTarget(target) {
+    return buildReferenceFor(target)?.pill ?? null;
+}
+// ── Editor reference builders ───────────────────────────────────────────────
+// The editor is in-process but its ECS units (entities/assets/components) are
+// outside the shell DOM registry above. Its injected typed bridge calls these
+// builders, keeping pill construction (icons/labels/detail format) in one place
+// so it cannot drift from the DOM path.
+export function buildEntityPill(p) {
+    const comps = Array.isArray(p.components) ? p.components.join(', ') : '';
+    const srcStr = p.source?.plugin ? ` ${t('reference.source')}=${p.source.plugin}/${p.source.docId ?? ''}` : '';
+    return {
+        kind: 'entity', display: p.name, icon: '🎯',
+        detail: `[${t('reference.scene_entity')}: id=${p.id} name="${p.name}"${comps ? ` components=[${comps}]` : ''}${srcStr}]`,
+        tooltip: {
+            title: `🎯 ${t('reference.scene_entity')} · ${p.name}`,
+            lines: [`id: ${p.id}`, comps ? `${t('reference.components')}: ${comps}` : '', p.source?.plugin ? `${t('reference.source')}: ${p.source.plugin}/${p.source.docId ?? ''}` : ''].filter(Boolean),
+        },
+    };
+}
+export function buildAssetPill(p) {
+    const name = p.name ?? p.guid.slice(0, 8);
+    const isFolderSummary = p.assetKind === 'folder' && p.payload;
+    let detail;
+    if (isFolderSummary) {
+        const s = p.payload;
+        const kindList = s.kinds ? Object.entries(s.kinds).map(([k, v]) => `${k} × ${v}`).join(', ') : '';
+        detail = `[${t('reference.asset')}: folder="${name}" path=${p.packPath ?? ''} totalAssets=${s.totalAssets ?? 0} kinds=(${kindList})]`;
+    }
+    else if (p.payload) {
+        const payloadStr = JSON.stringify(p.payload, null, 2);
+        const truncPayload = payloadStr.length > 2000 ? payloadStr.slice(0, 2000) + '\n…(truncated)' : payloadStr;
+        detail = `[${t('reference.asset')}: guid=${p.guid} kind=${p.assetKind ?? ''}${p.packPath ? ` pack=${p.packPath}` : ''}\npayload:\n${truncPayload}]`;
+    }
+    else {
+        detail = `[${t('reference.asset')}: guid=${p.guid} kind=${p.assetKind ?? ''}${p.packPath ? ` pack=${p.packPath}` : ''}]`;
+    }
+    return {
+        kind: 'entity', display: name, icon: isFolderSummary ? '📁' : '🧱',
+        detail,
+        tooltip: {
+            title: `${isFolderSummary ? '📁' : '🧱'} ${t('reference.asset')} · ${name}`,
+            lines: [`guid: ${p.guid}`, p.assetKind ? `kind: ${p.assetKind}` : '', p.packPath ? `pack: ${p.packPath}` : ''].filter(Boolean),
+        },
+    };
+}
+/** Workspace pill — used by both the DOM descriptor and TopBar's dedicated
+ *  workspace-tab context menu (which has only {id,name}, not a DOM node). */
+export function buildWorkspacePill(wsId, wsName) {
+    return {
+        kind: 'tool', display: wsName, icon: '🗂',
+        detail: `[${t('reference.workspace_ref')}: "${wsName}" id=${wsId}]`,
+        tooltip: { title: `🗂 ${t('reference.workspace')} · ${wsName}`, lines: [`id: ${wsId}`, t('reference.workspace_context_hint')] },
+    };
+}
+export function buildComponentPill(p) {
+    const json = JSON.stringify({ [p.comp]: p.value }, null, 2);
+    return {
+        kind: 'entity', display: `${p.entityName}.${p.comp}`, icon: '🔧',
+        detail: `[${t('reference.component_property')}: ${p.entityName}#${p.entityId ?? '?'}.${p.comp} = ${json}]`,
+        tooltip: { title: `🔧 ${p.comp} · ${p.entityName}`, lines: [truncate(json, 80)] },
+    };
+}
+const useComposerInsertBridge = create((set) => ({
+    pendingInsert: null,
+    queue: [],
+    request: (p) => set((s) => ({
+        queue: [...s.queue, p],
+        pendingInsert: s.queue.length === 0 ? p : s.pendingInsert,
+    })),
+    clear: () => set((s) => {
+        const q = s.queue.slice(1);
+        return { queue: q, pendingInsert: q[0] ?? null };
+    }),
+}));
+/** Publish a pill into the composer. Callable from any surface (no React ctx). */
+export function requestComposerInsert(p) {
+    useComposerInsertBridge.getState().request(p);
+}
+/** React hook — the next pending pill to insert (null when none). */
+export function useComposerPendingInsert() {
+    return useComposerInsertBridge((s) => s.pendingInsert);
+}
+/** Drop the consumed pill and advance the queue. */
+export function clearComposerPendingInsert() {
+    useComposerInsertBridge.getState().clear();
+}

package/dist/package/browser/lib/dashboard-api.d.ts

@@ -0,0 +1,104 @@
+export interface SessionListItem {
+    sid: string;
+    displayName?: string;
+    defaultDir?: string;
+    autoStart?: boolean;
+}
+export interface AgentNode {
+    path: string;
+    display: string;
+    depth: number;
+    fullId: string;
+    parent: string | null;
+    hasLedger: boolean;
+    running: boolean;
+}
+export interface SessionAgentSummary {
+    sid: string;
+    agents: AgentNode[];
+    agentCount: number;
+    runningCount: number;
+    error?: string;
+}
+export interface ProviderHealth {
+    id: string;
+    displayName: string;
+    capabilities: Record<string, boolean>;
+    health: {
+        ok: boolean;
+        detail?: string;
+    };
+}
+export interface SessionLedgerEvent {
+    seq: number;
+    ts: number;
+    source: string;
+    type: string;
+    payload: Record<string, unknown>;
+    to?: string;
+}
+export interface HealthResponse {
+    status: string;
+    version: string;
+    pid: number;
+    uptime: number;
+    projectRoot: string;
+    providers: string[];
+    wsClients: number;
+    mem?: {
+        rss: number;
+        heapUsed: number;
+    };
+    bus?: {
+        extensionCount: number;
+        brokenCount: number;
+        listenerCount: number;
+        ringSize: number;
+        uptimeMs: number;
+    };
+}
+export declare const dashApi: {
+    health: () => Promise<HealthResponse>;
+    providers: (force?: boolean) => Promise<{
+        providers: ProviderHealth[];
+        cachedAt: number;
+    }>;
+    sessions: () => Promise<{
+        sessions: SessionListItem[];
+    }>;
+    /** 单 session 的 agent tree（含 running 标志）。错误时 throw,调用方决定降级。 */
+    sessionAgents: (sid: string) => Promise<AgentNode[]>;
+    /** 批量拉多 session 的 agent 概况,失败的 session 落 `error` 字段而不是 throw。
+     *  Dashboard sessions 列表用,一次性并行展开所有 sid。 */
+    sessionAgentSummaries: (sids: string[]) => Promise<Map<string, SessionAgentSummary>>;
+    /** REST DELETE /api/sessions/:sid —— session 目录 + ledger 一并清理。 */
+    deleteSession: (sid: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** POST /api/sessions/:sid/abort[?agent=path] —— 打断某 agent 的当前 turn。
+     *  agent 缺省时打断 session 内所有 in-flight agent。 */
+    abortSession: (sid: string, agent?: string) => Promise<{
+        ok: boolean;
+        error?: string;
+    }>;
+    /** ledger replay —— fetch_session_events command。`agentPath` 是 list_agents
+     *  返回的 path 字段（"" = root agent）。`from` 是上一次拿到的最后一个 seq;
+     *  缺省从头拉。 */
+    sessionEvents: (sid: string, agentPath: string, opts?: {
+        from?: number;
+        limit?: number;
+    }) => Promise<SessionLedgerEvent[]>;
+};
+export declare function summarizeSessions(sessions: SessionListItem[], summaries: Map<string, SessionAgentSummary>): {
+    totals: {
+        sessionCount: number;
+        agentCount: number;
+        runningSessions: number;
+        runningAgents: number;
+    };
+    byDir: Record<string, {
+        sessionCount: number;
+        runningCount: number;
+    }>;
+};

package/dist/package/browser/lib/dashboard-api.js

@@ -0,0 +1,125 @@
+// Dashboard API client — thin typed wrappers over the forgeax-server endpoints.
+//
+// R3 migration (2026-05-20):
+//   The old surface targeted `/api/runs`, `/api/threads/*`, `/api/daemons/*`
+//   which were deleted in wu-tian807's runtime rewrite. Run + Thread + Session
+//   collapsed into a single Session model (see docs/features/runtime-rewrite-
+//   core-plan.md). Daemons concept retired entirely.
+//
+//   This module now exposes session-centric helpers backed by:
+//     - REST  /api/sessions           (list / create / delete / abort)
+//     - REST  /api/health             (uptime / wsClients / bus stats)
+//     - cmd   list_agents             (per-session agent tree + running flag)
+//     - cmd   fetch_session_events    (ledger replay for a single agent)
+//
+//   Provider health stays on the dedicated `/api/cli/health` bridge (see
+//   `./cli-providers`) since cli-providers is still its own subsystem.
+async function getJSON(path) {
+    const r = await fetch(path);
+    if (!r.ok)
+        throw new Error(`${path} ${r.status}`);
+    return (await r.json());
+}
+async function runCommand(name, args) {
+    const r = await fetch(`/api/commands/${encodeURIComponent(name)}/query`, {
+        method: 'POST',
+        headers: { 'content-type': 'application/json' },
+        body: JSON.stringify({ args }),
+    });
+    if (!r.ok)
+        throw new Error(`commands/${name} ${r.status}`);
+    const j = (await r.json());
+    if (!j.result?.ok)
+        throw new Error(j.result?.error ?? `commands/${name} failed`);
+    return j.result.data;
+}
+export const dashApi = {
+    health: () => getJSON('/api/health'),
+    // R3 适配:原 `/api/cli-providers` 已下线,桥到独立 `/api/cli/health`。
+    // 字段 mapping 抽在 lib/cli-providers.ts,集中维护。等 commands.attach_script_agent
+    // 替代当前 cli-provider 桥之后,本调用直接退役。
+    providers: async (force = false) => {
+        const { fetchCliProviders } = await import('./cli-providers');
+        return fetchCliProviders(force);
+    },
+    sessions: () => getJSON('/api/sessions'),
+    /** 单 session 的 agent tree（含 running 标志）。错误时 throw,调用方决定降级。 */
+    sessionAgents: (sid) => runCommand('list_agents', [sid]).then((d) => d.agents ?? []),
+    /** 批量拉多 session 的 agent 概况,失败的 session 落 `error` 字段而不是 throw。
+     *  Dashboard sessions 列表用,一次性并行展开所有 sid。 */
+    sessionAgentSummaries: async (sids) => {
+        const m = new Map();
+        await Promise.all(sids.map(async (sid) => {
+            try {
+                const agents = await dashApi.sessionAgents(sid);
+                m.set(sid, {
+                    sid,
+                    agents,
+                    agentCount: agents.length,
+                    runningCount: agents.filter((a) => a.running).length,
+                });
+            }
+            catch (err) {
+                m.set(sid, {
+                    sid,
+                    agents: [],
+                    agentCount: 0,
+                    runningCount: 0,
+                    error: err.message,
+                });
+            }
+        }));
+        return m;
+    },
+    /** REST DELETE /api/sessions/:sid —— session 目录 + ledger 一并清理。 */
+    deleteSession: async (sid) => {
+        const r = await fetch(`/api/sessions/${encodeURIComponent(sid)}`, { method: 'DELETE' });
+        if (r.ok)
+            return { ok: true };
+        const j = (await r.json().catch(() => ({})));
+        return { ok: false, error: j.error ?? `HTTP ${r.status}` };
+    },
+    /** POST /api/sessions/:sid/abort[?agent=path] —— 打断某 agent 的当前 turn。
+     *  agent 缺省时打断 session 内所有 in-flight agent。 */
+    abortSession: async (sid, agent) => {
+        const qs = agent ? `?agent=${encodeURIComponent(agent)}` : '';
+        const r = await fetch(`/api/sessions/${encodeURIComponent(sid)}/abort${qs}`, { method: 'POST' });
+        if (r.ok)
+            return { ok: true };
+        const j = (await r.json().catch(() => ({})));
+        return { ok: false, error: j.error ?? `HTTP ${r.status}` };
+    },
+    /** ledger replay —— fetch_session_events command。`agentPath` 是 list_agents
+     *  返回的 path 字段（"" = root agent）。`from` 是上一次拿到的最后一个 seq;
+     *  缺省从头拉。 */
+    sessionEvents: (sid, agentPath, opts) => runCommand('fetch_session_events', [
+        { sid, agentPath, ...(opts?.from !== undefined ? { from: opts.from } : {}), ...(opts?.limit !== undefined ? { limit: opts.limit } : {}) },
+    ]).then((d) => d.events ?? []),
+};
+// Aggregate helpers — 客户端聚合 sessions[] 以喂 dashboard cards。
+// /api/sessions 在 studio 的典型规模（≤200 条）下 O(N) 完全够用。
+export function summarizeSessions(sessions, summaries) {
+    const totals = {
+        sessionCount: sessions.length,
+        agentCount: 0,
+        runningSessions: 0,
+        runningAgents: 0,
+    };
+    const byDir = {};
+    for (const s of sessions) {
+        const sum = summaries.get(s.sid);
+        if (sum) {
+            totals.agentCount += sum.agentCount;
+            totals.runningAgents += sum.runningCount;
+            if (sum.runningCount > 0)
+                totals.runningSessions += 1;
+        }
+        const dir = s.defaultDir ?? '(no dir)';
+        if (!byDir[dir])
+            byDir[dir] = { sessionCount: 0, runningCount: 0 };
+        byDir[dir].sessionCount += 1;
+        if (sum && sum.runningCount > 0)
+            byDir[dir].runningCount += 1;
+    }
+    return { totals, byDir };
+}