@blade-hq/agent-react 2612.0.0-beta.0 → 2612.0.0-beta.10

package/dist/rich-input/lib/composer-content.d.ts

@@ -0,0 +1,32 @@
+import { type PluginRef, type TopicAssetRef, type SkillMentionAvailability } from "@blade-hq/agent-client";
+/**
+ * 输入框（tiptap）文档的最小结构，以及把它翻译成待发送文本的规则。
+ *
+ * 首页和会话内是两个不同的输入框组件，但「药丸怎么变成文本」「开头那个技能
+ * 是哪个」必须是同一套判定——两边各写一份就会出现只有一侧修好的 bug。
+ */
+export interface EditorJSON {
+    type?: string;
+    text?: string;
+    attrs?: Record<string, unknown>;
+    marks?: {
+        type: string;
+    }[];
+    content?: EditorJSON[];
+}
+export declare function serializeEditorContent(node: EditorJSON | null | undefined): string;
+export interface LeadingSkillMention extends SkillMentionAvailability {
+    skillId: string;
+}
+/**
+ * 只有正文最开头的技能药丸才算「这条消息要用哪个技能」。前面已经有别的内容
+ * 时，药丸只是被提到，不改写整条消息的意图。
+ */
+export declare function findLeadingSkillMention(node: EditorJSON | null | undefined): LeadingSkillMention | null;
+/** Asset identity travels separately; no metadata or retrieval instruction enters the user's text. */
+export declare function collectTopicAssetMentions(node: EditorJSON | null | undefined): TopicAssetRef[];
+export declare function buildEditorDocumentWithMentions(text: string, topicAssetRefs?: readonly TopicAssetRef[]): EditorJSON;
+/** Switching the explicitly selected topic must not leave pills from the previous one. */
+export declare function retainTopicAssetMentions(node: EditorJSON, topicId: string | null): EditorJSON;
+export declare function collectPluginMentions(node: EditorJSON | null | undefined): PluginRef[];
+export declare function buildEditorDocument(text: string): EditorJSON;

package/dist/rich-input/lib/image-input-availability.d.ts

@@ -0,0 +1,3 @@
+export declare const IMAGE_INPUT_UNSUPPORTED_MESSAGE = "\u5F53\u524D\u6A21\u578B\u6682\u4E0D\u652F\u6301\u56FE\u7247";
+export declare function isImageFile(file: Pick<File, "type" | "name">): boolean;
+export declare function getUnsupportedImageFiles(files: readonly Pick<File, "type" | "name">[], supportsImage: boolean | undefined): Pick<File, "type" | "name">[];

package/dist/rich-input/lib/input-history-document.d.ts

@@ -0,0 +1,3 @@
+import type { EditorJSON } from "./composer-content";
+/** Copy only the composer schema. Stored JSON must never introduce arbitrary nodes or attrs. */
+export declare function copyEditorDocument(value: unknown): EditorJSON | null;

package/dist/rich-input/lib/plugin-suggestions.d.ts

@@ -0,0 +1,7 @@
+import type { BladeClient, PluginRef } from "@blade-hq/agent-client";
+import type { PluginSuggestionItem, PluginSuggestionError } from "../extensions/plugin-mention";
+export declare function pluginRefsForSend(refs: PluginRef[], turns?: readonly {
+    role: string;
+    refs?: PluginRef[] | null;
+}[]): PluginRef[] | undefined;
+export declare function getPluginSuggestionItems(client: BladeClient, session: string | null | undefined, query: string, pendingPlugins?: readonly string[]): Promise<Array<PluginSuggestionItem | PluginSuggestionError>>;

package/dist/rich-input/lib/reasoning-levels.d.ts

@@ -0,0 +1 @@
+export declare function reasoningLevelLabel(level: string): string;

package/dist/rich-input/lib/reference-candidates.d.ts

@@ -0,0 +1,27 @@
+import type { PluginSuggestionItem, PluginSuggestionError } from "../extensions/plugin-mention";
+import type { FileEntry } from "@blade-hq/agent-client";
+import type { TopicAssetSuggestionError, TopicAssetSuggestionItem } from "../extensions/topic-asset-mention";
+export interface ReferenceCandidateGroups {
+    plugins: Array<PluginSuggestionItem | PluginSuggestionError>;
+    topics: Array<TopicAssetSuggestionItem | TopicAssetSuggestionError>;
+    files: FileEntry[];
+}
+export type ReferenceCandidateItem = ReferenceCandidateGroups[keyof ReferenceCandidateGroups][number];
+export interface ReferenceCandidateSnapshot {
+    groups: ReferenceCandidateGroups;
+    items: ReferenceCandidateItem[];
+    loading: Record<keyof ReferenceCandidateGroups, boolean>;
+    errors: Partial<Record<keyof ReferenceCandidateGroups, unknown>>;
+}
+export interface ReferenceCandidateSources {
+    plugins?: (query: string) => Promise<Array<PluginSuggestionItem | PluginSuggestionError>>;
+    topics: (query: string) => Promise<ReferenceCandidateGroups["topics"]>;
+    files: (query: string) => Promise<ReferenceCandidateGroups["files"]>;
+}
+/** Fixed @ sources only. Hosts own data access and the menu owns rendering. */
+export declare function createReferenceCandidateController(getScope: () => readonly unknown[], sources: ReferenceCandidateSources, timeoutMs?: number): {
+    cancel: () => void;
+    query(query: string): Promise<ReferenceCandidateItem[]>;
+    /** Bind by result identity, never by label/query: closing and reopening @ is a new request. */
+    observe(items: ReferenceCandidateItem[], listener: (snapshot: ReferenceCandidateSnapshot) => void): void;
+};

package/dist/rich-input/lib/session-data.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 输入框工具条要读的会话数据：本会话已加载的技能、技能统计、上下文用量、后台任务。
+ * 默认实现直接用 BladeClient 请求，一轮回复结束（或收到后台任务事件）时刷新；内置 Web 用
+ * React Query 覆盖（由它的事件桥统一失效），见 `RichInputServices`。
+ */
+import type { BackgroundTask, SessionContextStats } from "@blade-hq/agent-client/internal";
+import { useBladeClient } from "../../context";
+import type { InputDataState, InputSessionSkill, InputSkillStats } from "../../chat/runtime/input-services";
+export type { InputDataState as SessionDataState, InputSessionSkill as SessionSkillSummary, InputSkillStats as SkillStats, } from "../../chat/runtime/input-services";
+export type { SessionContextStats };
+/** 回复结束时让这些键过期重拉（有组件在用时）。 */
+export declare function useRefreshWhenRunEnds(sessionId: string | null, keys: string[]): void;
+export declare function useClientSessionSkills(sessionId: string | null): InputDataState<InputSessionSkill[]>;
+export declare function useClientSkillStats(sessionId: string | null): InputDataState<InputSkillStats>;
+export declare function useClientContextStats(sessionId: string | null): InputDataState<SessionContextStats>;
+export declare function useClientBackgroundTasks(sessionId: string | null): InputDataState<BackgroundTask[]>;
+/** 会话的技能变了（连接器开关插件等）：让默认实现的技能数据重拉。 */
+export declare function refreshClientSessionSkills(client: ReturnType<typeof useBladeClient>, sessionId: string): void;
+/** 会话保存的模型（默认实现：请求会话详情，回复结束时刷新）。 */
+export declare function useClientSessionModel(sessionId: string | null): string | null;

package/dist/rich-input/lib/skill-suggestions.d.ts

@@ -0,0 +1,19 @@
+import type { BladeClient } from "@blade-hq/agent-client";
+import type { ChatRenderMode } from "../../chat/runtime/environment";
+import type { SkillSuggestionItem, SkillSuggestionSkillItem } from "../extensions/skill-mention";
+/**
+ * `/` 补全菜单的候选来源。首页和会话内共用这一份判定，两处不要各写一份——
+ * 首页没有会话，会话内有，差别只体现在这里。
+ */
+export interface SkillSuggestionOptions {
+    client: BladeClient;
+    /** 会话内传当前会话 id；首页传 null。 */
+    sessionId: string | null;
+    /** 开发者视图显示平台内置技能，其余视图隐藏。 */
+    renderMode: ChatRenderMode;
+}
+/** 会话的技能变了（连接器开关插件等）：下一次 `/` 菜单重新取。 */
+export declare function invalidateSlashSuggestions(client: BladeClient, sessionId: string | null): void;
+/** `/` 菜单的全部候选:只有技能——固定流程也是技能(带 hasFlow),没有单独的一组。 */
+export declare function getSlashSuggestions(query: string, options: SkillSuggestionOptions): Promise<SkillSuggestionItem[]>;
+export declare function getSkillSuggestions(query: string, options: SkillSuggestionOptions): Promise<SkillSuggestionSkillItem[]>;

package/dist/rich-input/lib/token-estimate.d.ts

@@ -0,0 +1,2 @@
+/** Approximate input size only; generation speed uses provider usage and timing. */
+export declare function estimateTokenCount(text: string): number;

package/dist/rich-input/lib/token-pressure.d.ts

@@ -0,0 +1,8 @@
+import type { SessionContextStats } from "@blade-hq/agent-client/internal";
+export type TokenPressureLevel = "normal" | "warn" | "critical";
+export interface TokenPressure {
+    ratio: number;
+    level: TokenPressureLevel;
+}
+/** 上下文用量占窗口的比例与压力档位（接近自动整理阈值时提醒）。 */
+export declare function tokenPressureOf(stats: SessionContextStats | undefined | null): TokenPressure;

package/dist/rich-input/lib/topic-asset-suggestions.d.ts

@@ -0,0 +1,6 @@
+import type { BladeClient, TopicAssetRef } from "@blade-hq/agent-client";
+import type { TopicAssetSuggestionItem, TopicAssetSuggestionError } from "../extensions/topic-asset-mention";
+/** Dedicated source, intentionally independent of a generic mention registry. */
+export declare function getTopicAssetSuggestionItems(client: BladeClient, topicId: string | null | undefined, query: string): Promise<Array<TopicAssetSuggestionItem | TopicAssetSuggestionError>>;
+/** May be called before navigating. The matching session composer consumes it once. */
+export declare function queueTopicAssetReference(sessionId: string, ref: TopicAssetRef): void;

package/dist/rich-input/lib/upload-results.d.ts

@@ -0,0 +1,8 @@
+/** Match a batch upload response to the submitted attachments by input position. */
+export declare function uploadedPathsById<T extends {
+    id: string;
+}>(attachments: readonly T[], results: readonly {
+    index: number;
+    path?: string;
+    error?: string;
+}[]): Map<string, string>;

package/dist/rich-input/lib/user-home.d.ts

@@ -0,0 +1,33 @@
+import type { BladeClient } from "@blade-hq/agent-client";
+export interface UserHomeEntry {
+    name: string;
+    path: string;
+    is_dir: boolean;
+}
+export interface UserHomeRuntime {
+    /** 云电脑 HOME 的绝对路径。沙盒是 `/root`，daemon 是它自报的用户目录。 */
+    homePath: string;
+    /** Windows daemon 的路径用反斜杠，拼子目录时不能写死 `/`。 */
+    separator: "/" | "\\";
+}
+/**
+ * 用户云电脑的 HOME 位置。不能假定是 `/root`：用户把某台 daemon 设成默认运行
+ * 环境时，HOME 是它自报的路径（`/home/alice`、`C:\Users\alice`），拿 `/root`
+ * 去问会被判为越界，补全菜单就会静默空掉。
+ */
+export declare function getUserHomeRuntime(client: BladeClient): Promise<UserHomeRuntime>;
+/**
+ * 最近一次解析出的运行环境。补全菜单渲染时条目已经拉好了，此时运行环境必然
+ * 已解析——同步读一份，省得把 Promise 传进渲染路径。
+ */
+export declare function getLastUserHomeRuntime(): UserHomeRuntime;
+/**
+ * 列出用户云电脑 HOME 下某个目录的内容。不需要会话——首页在还没建会话时
+ * 就要能引用这些文件。后端已按统一规则跳过隐藏项、依赖目录和编译产物。
+ *
+ * 补全菜单每敲一个字符都会问一次候选，而在同一个目录里继续输入时问的是同
+ * 一个目录——后端返回整个目录、过滤在前端做，几千个文件的目录每次就是几百
+ * KB。所以按目录缓存一小段时间：缓存的是 Promise，连续输入产生的并发请求
+ * 也会自动合并成一个。失败不留缓存，下次重试。
+ */
+export declare function listUserHomeDir(client: BladeClient, dirPath: string): Promise<UserHomeEntry[]>;

package/dist/rich-input/model/model-data.d.ts

@@ -0,0 +1,6 @@
+import { type InputModelCatalog, type InputModelPreferences } from "../../chat/runtime/input-services";
+export type { InputModelCatalog as ModelCatalogState, InputModelOption as ModelOption, InputModelPreferences as ModelPreferencesState, } from "../../chat/runtime/input-services";
+export declare function useClientModelCatalog(): InputModelCatalog;
+export declare const PREFERRED_MODEL_KEY = "preferred_model";
+export declare const MODEL_REASONING_LEVELS_KEY = "llm.model_thinking_preferences";
+export declare function useClientModelPreferences(): InputModelPreferences;

package/dist/rich-input/model/resolve-model.d.ts

@@ -0,0 +1,59 @@
+/**
+ * 模型目录还在加载时按回车的提示。这时发出去拿不到用户选的模型与推理强度，所以不发送；
+ * 但发送按钮只对点击生效，回车绕过了它，不提示就是静默吞掉（#3103）。
+ */
+export declare const MODEL_LOADING_SEND_HINT = "\u6B63\u5728\u52A0\u8F7D\u6A21\u578B\u914D\u7F6E\uFF0C\u8BF7\u7A0D\u540E\u518D\u53D1\u9001";
+export type ModelLoadingSendGate = {
+    blocked: false;
+} | {
+    blocked: true;
+    hint: string | null;
+};
+/**
+ * 模型目录加载中的发送判定，首页输入框（apps/web HomeInput）与会话输入框（ChatInput）共用：
+ * 加载中一律不发；输入框里有可发送的内容时给出提示，空输入框按回车不打扰。
+ * 「有没有可发送的内容」由各输入框按自己的内容模型算好传进来。
+ */
+export declare function gateSendWhileModelLoading(isModelLoading: boolean, hasContent: boolean): ModelLoadingSendGate;
+interface ResolvedModelState {
+    resolvedModel: string;
+    hasAvailableModel: boolean;
+    isLoading: boolean;
+}
+export interface ExplicitModelSelection {
+    sessionId: string | null;
+    model: string;
+}
+/**
+ * A selector choice is a composer draft until chat:send accepts it and the
+ * server broadcasts session:updated. Keep it separate from the persisted
+ * session model so a session-list refresh cannot discard the next-send choice.
+ */
+export declare function resolveComposerModel(activeSessionId: string | null, persistedModel: string | null | undefined, explicitSelection: ExplicitModelSelection | null): string | null;
+export declare function resolveModelChoice({ activeSessionModel, preferredModel, defaultModel, models, isLoading, unavailableProviderIds, unavailableModelIds, }: {
+    activeSessionModel?: string | null;
+    preferredModel?: string | null;
+    defaultModel: string;
+    models: readonly {
+        id: string;
+    }[];
+    isLoading: boolean;
+    unavailableProviderIds?: readonly string[];
+    unavailableModelIds?: readonly string[];
+}): ResolvedModelState;
+export declare function useResolvedModel(activeSessionModel?: string | null): {
+    resolvedModel: string;
+    hasAvailableModel: boolean;
+    thinkingAvailable: boolean;
+    reasoningLevels: string[];
+    defaultReasoningLevel: string;
+    modelAvailabilityMessage: string;
+    supportsImage: boolean | undefined;
+    isLoading: boolean;
+};
+/** 某个模型上次选的推理强度（没有选过时为 null）。 */
+export declare function useReasoningLevelPreference(modelId: string): {
+    reasoningLevelPreference: string | null;
+    setReasoningLevelPreference: (level: string) => void;
+};
+export {};

package/dist/rich-input/model/use-composer-model.d.ts

@@ -0,0 +1,24 @@
+export interface ComposerSubmitModels {
+    /** 还没有会话、先建会话时用的模型。 */
+    newSessionModel: string | null;
+    /** 随消息发送的模型；null 表示沿用会话已保存的模型。 */
+    sendModel: string | null;
+}
+/** 输入框当前的模型选择与推理档位（发送时带上）。 */
+export interface ComposerModelState {
+    /** 当前选中的模型（加载中时是乐观值）。 */
+    selectedModel: string;
+    hasAvailableModel: boolean;
+    isLoading: boolean;
+    /** 没有可用模型时给用户看的说明。 */
+    availabilityMessage: string;
+    thinkingAvailable: boolean;
+    reasoningLevels: string[];
+    selectedReasoningLevel: string;
+    setReasoningLevel: (level: string) => void;
+    /** 用户在选择器里选了一个模型。 */
+    selectModel: (model: string) => void;
+    /** 提交那一刻冻结的模型选择（上传与 onBeforeSend 可能要等，发出去的仍是提交时看到的模型）。 */
+    freezeForSubmit: () => ComposerSubmitModels;
+}
+export declare function useComposerModel(activeSessionId: string | null): ComposerModelState;

package/dist/rich-input/services.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 富输入的数据来源：宿主覆盖了就用宿主的（内置 Web 的 React Query 缓存、全局 store），
+ * 否则用基于 BladeClient 的默认实现。覆盖点见 `RichInputServices`（internal 入口）。
+ */
+import type { BackgroundTask, ConnectionStatus, SessionContextStats } from "@blade-hq/agent-client/internal";
+import { type InputConnection, type InputDataState, type InputModelCatalog, type InputModelPreferences, type InputSessionSkill, type InputSkillStats } from "../chat/runtime/input-services";
+export { type ConnectorComputerSectionProps, type InputConnection, type InputDataState, type InputModelCatalog, type InputModelOption, type InputModelPreferences, type InputSessionSkill, type InputSkillStats, type RichInputServices, RichInputServicesProvider, useRichInputServices, } from "../chat/runtime/input-services";
+export declare function useModelCatalog(): InputModelCatalog;
+export declare function useModelPreferences(): InputModelPreferences;
+/** 连接情况：宿主给了就用宿主的（内置 Web 看全局连接），否则看当前会话。 */
+export declare function useComposerConnectionInfo(sessionId: string | null): InputConnection;
+export declare function useComposerConnection(sessionId: string | null): ConnectionStatus;
+export declare function useSessionSkills(sessionId: string | null): InputDataState<InputSessionSkill[]>;
+export declare function useSkillStats(sessionId: string | null): InputDataState<InputSkillStats>;
+export declare function useContextStats(sessionId: string | null): InputDataState<SessionContextStats>;
+export declare function useBackgroundTaskList(sessionId: string | null): InputDataState<BackgroundTask[]>;
+/** 附件上传、插件开关之后让相关数据刷新。 */
+export declare function useSessionDataInvalidation(): {
+    filesUploaded: (sessionId: string) => void;
+    pluginsChanged: (sessionId: string) => void;
+};

package/dist/rich-input/use-dismiss-skill-suggestions-on-mode-change.d.ts

@@ -0,0 +1,3 @@
+import type { Editor } from "@tiptap/react";
+/** 切换渲染模式（普通 / 精简 / 开发者）时收起正在显示的技能菜单。 */
+export declare function useDismissSkillSuggestionsOnModeChange(editor: Editor | null): void;

package/dist/rich-input/use-input-history.d.ts

@@ -0,0 +1,14 @@
+import type { BladeClient } from "@blade-hq/agent-client";
+import { type EditorJSON } from "./lib/composer-content";
+/** The editor document is authoritative; display text never grants mention identity. */
+export interface InputHistoryEntry {
+    version: 2;
+    document: EditorJSON;
+}
+export declare function useInputHistory(sessionId: string | null, client?: BladeClient): {
+    addEntry: (value: unknown) => void;
+    navigateUp: (currentDraft?: EditorJSON) => InputHistoryEntry | null;
+    navigateDown: () => InputHistoryEntry | null;
+    currentEntry: InputHistoryEntry;
+    isNavigating: boolean;
+};

package/dist/rich-input/use-reference-candidates.d.ts

@@ -0,0 +1,8 @@
+import type { BladeClient } from "@blade-hq/agent-client";
+import { type ReferenceCandidateSources } from "./lib/reference-candidates";
+/** One controller per editor; source callbacks always use the current host services. */
+export declare function useReferenceCandidates(getScope: () => readonly [BladeClient, unknown, unknown, unknown], sources: ReferenceCandidateSources): {
+    cancel: () => void;
+    query(query: string): Promise<import("./lib/reference-candidates").ReferenceCandidateItem[]>;
+    observe(items: import("./lib/reference-candidates").ReferenceCandidateItem[], listener: (snapshot: import("./lib/reference-candidates").ReferenceCandidateSnapshot) => void): void;
+};

package/dist/rich-input/voice/VoiceWaveform.d.ts

@@ -0,0 +1,10 @@
+interface VoiceWaveformProps {
+    /** RMS 幅度 0..1 */
+    level: number;
+    /** 线条颜色；默认跟随 currentColor */
+    color?: string;
+    /** 按钮直径参考值，决定波形尺寸 */
+    size?: number;
+}
+export declare function VoiceWaveform({ level, color, size }: VoiceWaveformProps): import("react/jsx-runtime").JSX.Element;
+export {};

package/dist/rich-input/voice/use-tiptap-voice-input.d.ts

@@ -0,0 +1,47 @@
+import type { Editor as TiptapEditor } from "@tiptap/react";
+import type { VoiceInputError } from "./voice-input-support";
+export type VoiceInputStatus = "idle" | "starting" | "recording" | "stopping" | "error";
+export interface UseVoiceInputOptions {
+    workletUrl: string;
+    onPartial?: (text: string) => void;
+    onFinal?: (text: string) => void;
+    onError?: (error: VoiceInputError) => void;
+}
+export interface UseVoiceInputResult {
+    status: VoiceInputStatus;
+    error: string | null;
+    /** 当前音频 RMS 幅度，0..1，仅在 recording 期间有意义，用于驱动波形动画 */
+    level: number;
+    start: () => Promise<void>;
+    stop: () => Promise<void>;
+}
+/** 语音识别（宿主注入：内置 Web 走自己的 ASR 通道）。 */
+export type UseVoiceInput = (options: UseVoiceInputOptions) => UseVoiceInputResult;
+export interface UseTiptapVoiceInputOptions {
+    /** Tiptap editor ref；null 时 voice 回调会静默丢弃 */
+    editorRef: {
+        current: TiptapEditor | null;
+    };
+    /** AudioWorklet processor 文件 URL */
+    workletUrl: string;
+    /** 外部可选回调：识别错误时拿 message */
+    onError?: (error: VoiceInputError) => void;
+    /** 语音识别实现；不传时语音不可用（toggle 无效果）。 */
+    useVoiceInput?: UseVoiceInput;
+}
+export interface UseTiptapVoiceInputResult {
+    status: VoiceInputStatus;
+    isRecording: boolean;
+    error: string | null;
+    /** 当前音频 RMS 幅度，0..1，仅在 recording 期间有意义，用于驱动波形动画 */
+    level: number;
+    toggle: () => void;
+    stop: () => Promise<void>;
+}
+/**
+ * Tiptap 编辑器里的语音输入集成：
+ * - partial 段用 `insertContentAt({from,to}, text)` 替换一个可变 range
+ * - final 段落定后把 range 推进到末尾，下一段重新起
+ * - 录音期间调用 `editor.setEditable(false)` 锁定键盘输入
+ */
+export declare function useTiptapVoiceInput(options: UseTiptapVoiceInputOptions): UseTiptapVoiceInputResult;

package/dist/rich-input/voice/use-voice-input.d.ts

@@ -0,0 +1,2 @@
+import type { UseVoiceInputOptions, UseVoiceInputResult } from "./use-tiptap-voice-input";
+export declare function useVoiceInput(options: UseVoiceInputOptions): UseVoiceInputResult;

package/dist/rich-input/voice/voice-input-support.d.ts

@@ -0,0 +1,5 @@
+export interface VoiceInputError {
+    title: string;
+    description?: string;
+}
+export declare function buildVoiceInputUnavailableError(): VoiceInputError;