@forgeax/interface 0.4.1

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

@@ -0,0 +1,54 @@
+/** checkpoint-api —— checkpoint 回退点的 REST 包装(server api/sessions.ts 路由)。
+ *  与 forgeax-bridge 同款风格:不持状态,调用方显式传 sid。 */
+export interface CheckpointEntry {
+    msgId: string;
+    ts: number;
+    /** false = 该消息时刻无游戏目录(纯会话),只能会话回退。 */
+    hasCode: boolean;
+}
+export interface PendingRewindInfo {
+    boundaryId: string;
+    targetMsgId: string;
+    mode: "both" | "conversation" | "code";
+    preManifestId: string | null;
+    keptDirty: string[];
+    overwrite: {
+        safetyManifestId: string;
+        files: string[];
+    } | null;
+}
+/** 单文件变更明细(server snapshot-store FileDiffStat 镜像)。 */
+export interface FileDiffStat {
+    path: string;
+    status: "added" | "deleted" | "modified";
+    insertions: number;
+    deletions: number;
+    binary: boolean;
+}
+export interface RewindPreview {
+    filesChanged: string[];
+    insertions: number;
+    deletions: number;
+    binaryOrLarge: number;
+    /** 逐文件明细;旧 server 可能不返回,消费侧用 `files ?? []`。 */
+    files?: FileDiffStat[];
+}
+export declare function fetchCheckpoints(sid: string, signal?: AbortSignal): Promise<{
+    checkpoints: CheckpointEntry[];
+    pending: PendingRewindInfo | null;
+}>;
+export declare function rewindPreview(sid: string, msgId: string): Promise<RewindPreview>;
+export declare function rewindTo(sid: string, msgId: string, mode: "both" | "conversation" | "code"): Promise<{
+    boundaryId: string;
+    filesChanged: string[];
+    keptDirty: string[];
+}>;
+export declare function rewindCancel(sid: string, boundaryId: string): Promise<{
+    keptDirty: string[];
+}>;
+export declare function rewindOverwriteDirty(sid: string, boundaryId: string): Promise<{
+    files: string[];
+}>;
+export declare function rewindUndoOverwrite(sid: string, boundaryId: string): Promise<{
+    files: string[];
+}>;

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

@@ -0,0 +1,41 @@
+/** checkpoint-api —— checkpoint 回退点的 REST 包装(server api/sessions.ts 路由)。
+ *  与 forgeax-bridge 同款风格:不持状态,调用方显式传 sid。 */
+async function post(url, body) {
+    const r = await fetch(url, {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: JSON.stringify(body),
+    });
+    if (!r.ok) {
+        let detail;
+        try {
+            detail = (await r.json()).error ?? `HTTP ${r.status}`;
+        }
+        catch {
+            detail = `HTTP ${r.status}`;
+        }
+        throw new Error(detail);
+    }
+    return (await r.json());
+}
+export async function fetchCheckpoints(sid, signal) {
+    const r = await fetch(`/api/sessions/${encodeURIComponent(sid)}/checkpoints`, { signal });
+    if (!r.ok)
+        throw new Error(`GET checkpoints ${r.status}`);
+    return (await r.json());
+}
+export function rewindPreview(sid, msgId) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind/preview`, { msgId });
+}
+export function rewindTo(sid, msgId, mode) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind`, { msgId, mode });
+}
+export function rewindCancel(sid, boundaryId) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind/cancel`, { boundaryId });
+}
+export function rewindOverwriteDirty(sid, boundaryId) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind/overwrite-dirty`, { boundaryId });
+}
+export function rewindUndoOverwrite(sid, boundaryId) {
+    return post(`/api/sessions/${encodeURIComponent(sid)}/rewind/undo-overwrite`, { boundaryId });
+}

package/dist/package/browser/lib/cli-providers.d.ts

@@ -0,0 +1,33 @@
+/** /api/cli/health → 旧 /api/cli-providers 格式适配层。
+ *
+ *  历史背景：
+ *  - 旧路径 `/api/cli-providers` 由删掉的"统一 chat daemon"提供，UI 各处轮询
+ *    它显示 provider 健康灯。
+ *  - 新路径 `/api/cli/health` 来自 R3 阶段独立 cli-provider 桥
+ *    (`packages/server/src/api/cli/chat.ts`)，所有响应附 `Deprecation: true`
+ *    header —— 它本身也是临时的，最终会被 `commands.attach_script_agent` 取代。
+ *  - 本模块只做字段 mapping，让旧 UI 代码无感切回上游，避免在 6+ 个地方重复
+ *    解构。等 commands 接管之后，整个文件可以删。
+ *
+ *  返回形态对齐旧 dashboard-api `ProviderHealth` / Composer `CliProviderInfo`：
+ *    { id, displayName, health: { ok, detail }, capabilities }
+ *
+ *  Display name fallback table：与 Composer 既有 PROVIDER_DISPLAY_FALLBACK
+ *  保持一致，集中维护一份。 */
+export interface CliProviderInfo {
+    id: string;
+    displayName: string;
+    health: {
+        ok: boolean;
+        detail?: string;
+    };
+    capabilities: Record<string, boolean>;
+}
+export declare function displayableKernelCapabilities(capabilities: Record<string, boolean> | undefined): Record<string, boolean>;
+/** Single source of truth for the /api/cli/health → CliProviderInfo[] mapping.
+ *  `force` is currently ignored upstream (R3 桥每次都打到 provider.health) but
+ *  保留参数兼容旧 dashApi.providers(true) caller。 */
+export declare function fetchCliProviders(force?: boolean): Promise<{
+    providers: CliProviderInfo[];
+    cachedAt: number;
+}>;

package/dist/package/browser/lib/cli-providers.js

@@ -0,0 +1,61 @@
+/** /api/cli/health → 旧 /api/cli-providers 格式适配层。
+ *
+ *  历史背景：
+ *  - 旧路径 `/api/cli-providers` 由删掉的"统一 chat daemon"提供，UI 各处轮询
+ *    它显示 provider 健康灯。
+ *  - 新路径 `/api/cli/health` 来自 R3 阶段独立 cli-provider 桥
+ *    (`packages/server/src/api/cli/chat.ts`)，所有响应附 `Deprecation: true`
+ *    header —— 它本身也是临时的，最终会被 `commands.attach_script_agent` 取代。
+ *  - 本模块只做字段 mapping，让旧 UI 代码无感切回上游，避免在 6+ 个地方重复
+ *    解构。等 commands 接管之后，整个文件可以删。
+ *
+ *  返回形态对齐旧 dashboard-api `ProviderHealth` / Composer `CliProviderInfo`：
+ *    { id, displayName, health: { ok, detail }, capabilities }
+ *
+ *  Display name fallback table：与 Composer 既有 PROVIDER_DISPLAY_FALLBACK
+ *  保持一致，集中维护一份。 */
+const PROVIDER_DISPLAY = {
+    // The native kernel arrives from /api/cli/health as `forgeax-core` (the
+    // product-shell-injected kernel id). There is NO bare `forgeax` provider —
+    // the pre-R3 `forgeax` CliProvider was dropped (see cli-providers registry
+    // comment), so a `forgeax` mapping here would just point at a ghost id.
+    "forgeax-core": "ForgeaX Kernel",
+    "claude-code": "Claude Code",
+    "codex": "OpenAI Codex",
+    "cursor-agent": "Cursor Agent",
+    "codebuddy": "CodeBuddy",
+    "kimi-code": "Kimi Code",
+    "deepseek-harness": "DeepSeek Harness",
+};
+// `/api/cli/health` still carries legacy provider-adapter fields such as
+// `sessions` and `jsonlReplay`. Those do not mean that a neutral AgentKernel
+// supports native history resume, so rendering them as kernel capabilities is
+// misleading. Keep the UI projection to capabilities whose meaning is shared
+// by the current kernel contract; unknown/legacy fields remain server-internal.
+const DISPLAYABLE_KERNEL_CAPABILITIES = new Set([
+    'streaming',
+    'thinking',
+    'toolCalls',
+    'midTurnInject',
+    'forkExtract',
+]);
+export function displayableKernelCapabilities(capabilities) {
+    return Object.fromEntries(Object.entries(capabilities ?? {}).filter(([key]) => DISPLAYABLE_KERNEL_CAPABILITIES.has(key)));
+}
+/** Single source of truth for the /api/cli/health → CliProviderInfo[] mapping.
+ *  `force` is currently ignored upstream (R3 桥每次都打到 provider.health) but
+ *  保留参数兼容旧 dashApi.providers(true) caller。 */
+export async function fetchCliProviders(force = false) {
+    void force; // R3: upstream `/api/cli/health` always lives-checks.
+    const r = await fetch("/api/cli/health");
+    if (!r.ok)
+        throw new Error(`/api/cli/health ${r.status}`);
+    const j = (await r.json());
+    const providers = (j.providers ?? []).map((p) => ({
+        id: p.id,
+        displayName: PROVIDER_DISPLAY[p.id] ?? p.id,
+        health: { ok: !!p.ok, detail: p.detail },
+        capabilities: displayableKernelCapabilities(p.capabilities),
+    }));
+    return { providers, cachedAt: Date.now() };
+}

package/dist/package/browser/lib/command-palette-store.d.ts

@@ -0,0 +1,5 @@
+export declare function getCommandPaletteOpen(): boolean;
+export declare function setCommandPaletteOpen(next: boolean): void;
+export declare function toggleCommandPalette(): void;
+export declare function subscribeCommandPalette(listener: () => void): () => void;
+export declare function useCommandPaletteOpen(): boolean;

package/dist/package/browser/lib/command-palette-store.js

@@ -0,0 +1,22 @@
+import { useSyncExternalStore } from 'react';
+let open = false;
+const listeners = new Set();
+function notify() {
+    for (const listener of listeners)
+        listener();
+}
+export function getCommandPaletteOpen() { return open; }
+export function setCommandPaletteOpen(next) {
+    if (open === next)
+        return;
+    open = next;
+    notify();
+}
+export function toggleCommandPalette() { setCommandPaletteOpen(!open); }
+export function subscribeCommandPalette(listener) {
+    listeners.add(listener);
+    return () => listeners.delete(listener);
+}
+export function useCommandPaletteOpen() {
+    return useSyncExternalStore(subscribeCommandPalette, getCommandPaletteOpen, () => false);
+}

package/dist/package/browser/lib/composer-bridge.d.ts

@@ -0,0 +1,103 @@
+export type PillKind = 'file' | 'dir' | 'agent' | 'tool' | 'game' | 'log' | 'entity' | 'paste' | 'skill' | 'command';
+export interface PillPayload {
+    kind: PillKind;
+    display: string;
+    icon?: string;
+    detail: string;
+    tooltip: {
+        title: string;
+        lines: string[];
+    };
+}
+export declare function encodePill(p: PillPayload): string;
+export declare function decodePill(token: string): PillPayload | null;
+export type TextSegment = {
+    kind: 'text';
+    text: string;
+} | {
+    kind: 'pill';
+    token: string;
+    payload: PillPayload;
+};
+export declare function parseSegments(text: string): TextSegment[];
+export declare function expandPills(text: string): string;
+/** Expand pills for transcript display — paste/file/etc. become detail text;
+ *  skill/command pills stay as sentinels so PillText renders tag chips. */
+export declare function expandPillsForDisplay(text: string): string;
+export type SlashPillSource = 'skill' | 'command';
+/** Build a slash-trigger pill for the composer slash menu (skill or server command). */
+export declare function buildSlashPill(p: {
+    trigger: string;
+    source: SlashPillSource;
+    displayName?: string;
+    description?: string;
+}): PillPayload;
+/** Parse message text for display — pill sentinels + leading `/command` tags. */
+export declare function parseDisplaySegments(text: string): TextSegment[];
+/** 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 declare const REFERENCE_LABEL: string;
+/** A copy action a unit can offer in its context menu (in addition to the
+ *  reference action). Plain data so this module stays free of menu/JSX deps. */
+export interface RefCopyItem {
+    label: string;
+    text: string;
+}
+/** One referenceable unit type. */
+export interface RefDescriptor {
+    /** Stable id (tests / telemetry). */
+    kind: string;
+    /** CSS selector; the first matching ancestor of the event target wins.
+     *  Order in REFERENCE_REGISTRY = specificity priority (most specific first). */
+    match: string;
+    /** Build the pill payload from the matched element. Return null to skip
+     *  (e.g. a required data-* is missing) and let later descriptors try. */
+    build: (el: HTMLElement) => PillPayload | null;
+    /** Optional extra copy items for this unit's context menu. */
+    copy?: (el: HTMLElement) => RefCopyItem[];
+    /** True when this unit has its OWN dedicated context menu (e.g. workspace
+     *  tabs open a rename/delete menu via onContextMenu). The global ContextMenu
+     *  then skips it entirely so the two menus don't stack and fight for clicks. */
+    ownMenu?: boolean;
+}
+export declare const REFERENCE_REGISTRY: RefDescriptor[];
+/** Walk the registry and return the first matching unit for an event target. */
+export declare function buildReferenceFor(target: Element | null): {
+    el: HTMLElement;
+    descriptor: RefDescriptor;
+    pill: PillPayload;
+} | null;
+/** Back-compat thin wrapper: DOM target → pill payload (or null). */
+export declare function buildPillFromTarget(target: Element | null): PillPayload | null;
+export declare function buildEntityPill(p: {
+    id?: number | string;
+    name: string;
+    components?: unknown;
+    source?: {
+        plugin?: string;
+        docId?: string;
+    };
+}): PillPayload;
+export declare function buildAssetPill(p: {
+    guid: string;
+    name?: string;
+    assetKind?: string;
+    packPath?: string;
+    payload?: Record<string, unknown>;
+}): PillPayload;
+/** 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 declare function buildWorkspacePill(wsId: string, wsName: string): PillPayload;
+export declare function buildComponentPill(p: {
+    entityId?: number;
+    entityName: string;
+    comp: string;
+    value: unknown;
+}): PillPayload;
+/** Publish a pill into the composer. Callable from any surface (no React ctx). */
+export declare function requestComposerInsert(p: PillPayload): void;
+/** React hook — the next pending pill to insert (null when none). */
+export declare function useComposerPendingInsert(): PillPayload | null;
+/** Drop the consumed pill and advance the queue. */
+export declare function clearComposerPendingInsert(): void;