@blade-hq/agent-kit 0.0.0-placeholder.0 → 0.4.4

package/README.md

@@ -1,4 +1,67 @@
-# @blade-hq/agent-kit
+# Blade Agent 前端 SDK
 
-Placeholder package for configuring npm trusted publishing.
-Do not use version `0.0.0-placeholder.0`.
+`@blade-hq/agent-kit` 是 Blade Agent 的前端 SDK。本期只在仓库内使用和验证，不包含 npm 发布说明。
+
+## 子包
+
+SDK 通过两个子包暴露能力：
+
+- `@blade-hq/agent-kit/client`：纯网络客户端，提供 `BladeClient`、REST 资源方法和强类型 Socket.IO 连接。它不依赖 React，适合 Vue 项目、Node.js 服务端脚本和其他第三方集成。
+- `@blade-hq/agent-kit/react`：React 绑定，提供 Provider、Hooks、Stores、组件和内部业务视图。Blade Agent 自带的 `apps/web` 使用这个子包完成全栈 dogfooding。
+
+## 安装
+
+仓库内应用通过 pnpm workspace 直接引用：
+
+```bash
+pnpm install
+```
+
+第三方项目未来发布后可安装同一个包，并按需要选择子包入口：
+
+```ts
+import { BladeClient } from "@blade-hq/agent-kit/client"
+import { BladeClientProvider } from "@blade-hq/agent-kit/react"
+```
+
+## 认证
+
+SDK 支持 cookie 会话和 Bearer Token 两种模式。
+
+首方 Web 应用通常使用 cookie 会话：
+
+```ts
+const client = new BladeClient({ baseUrl: "https://blade.example.com" })
+```
+
+这种模式下，REST 请求始终使用 `credentials: "include"`，不会发送 `Authorization`；Socket.IO 连接不发送 token，由浏览器自动携带 cookie。
+
+第三方接入使用 Bearer Token。Token 必须在构造 `BladeClient` 时注入，不能在单次方法调用时临时传入：
+
+```ts
+const client = new BladeClient({
+  baseUrl: "https://blade.example.com",
+  token: "sk-blade-xxx",
+})
+```
+
+这种模式下，REST 请求仍然携带 cookie，同时额外发送 `Authorization: Bearer sk-blade-xxx`；Socket.IO 连接会发送 `auth: { token: "sk-blade-xxx" }`。当 cookie 和 Bearer Token 同时存在时，由后端按现有规则优先识别 Bearer Token，SDK 不主动二选一。
+
+如果 `token` 是空字符串，SDK 按 cookie 会话模式处理，不会发送空的 `Authorization` 或 Socket.IO token。`buildAuthedUrl()` 只会给同一后端域名追加 `?token=...`，用于文件预览等无法自定义请求头的场景；外部绝对 URL 不会被追加 Blade token。
+
+## 类型生成
+
+SDK 的类型来源以后端为准，生成产物提交到仓库，确保本地安装后可以直接 typecheck。
+
+- REST 类型来自 FastAPI 暴露的 `/openapi.json`，由 `openapi-typescript` 生成到 `src/client/types/rest.ts`。
+- Socket.IO 事件类型来自后端 `socket_schemas` 中的 Pydantic schema，生成到 `src/client/types/socket-events.ts`。
+- `src/client/types/index.ts` 提供业务侧常用类型别名，避免应用代码直接依赖冗长的 OpenAPI 路径类型。
+
+本地更新类型时，需要先启动后端，再执行：
+
+```bash
+cd web
+pnpm -F @blade-hq/agent-kit gen:types
+```
+
+CI 会重新生成类型并校验 `web/packages/agent-kit/src/client/types/` 没有 diff，用来阻止后端 schema 与前端 SDK 类型漂移。

package/dist/AskUserQuestionBlock-CjvG_pUY.d.ts

@@ -0,0 +1,116 @@
+import { P as PendingQuestionRef, C as ContentBlock } from './projection-DIfyh6RK.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+
+interface TextContentPart {
+    type: "text";
+    text: string;
+}
+interface ImageUrlContentPart {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+}
+interface FileContentPart {
+    type: "file";
+    name: string;
+    data: string;
+}
+type MessageContentPart = TextContentPart | ImageUrlContentPart | FileContentPart;
+type MessageContent = string | MessageContentPart[];
+interface ToolCallInfo {
+    id: string;
+    name: string;
+    display_name?: string | null;
+    arguments: string;
+    result?: unknown;
+    status?: "pending" | "done" | "error" | "cancelled" | "awaiting_answer";
+    duration_ms?: number | null;
+    pending_question_ref?: PendingQuestionRef | null;
+}
+
+interface MemoryRefInfo {
+    id: number;
+    content_preview: string;
+    skill_name?: string | null;
+}
+interface CompactionInfo {
+    compaction_id: string;
+    summary_preview?: string | null;
+    summary_full?: string | null;
+    archived_count?: number | null;
+    archived_files?: ArchivedFileInfo[] | null;
+    archived_tool_calls?: ArchivedToolCallInfo[] | null;
+    tokens_before?: number | null;
+    tokens_after?: number | null;
+    saved_ratio?: number | null;
+    trigger?: "auto" | "manual" | "forced_retry" | null;
+    failure_reason?: string | null;
+    fallback_applied?: boolean | null;
+}
+interface ArchivedFileInfo {
+    tool_name?: string | null;
+    filename?: string | null;
+    relative_path?: string | null;
+    size_bytes?: number | null;
+}
+interface ArchivedToolCallInfo {
+    tool_call_id?: string | null;
+    tool_name?: string | null;
+    archive_path?: string | null;
+    replacement_content?: string | null;
+    entry_id?: string | null;
+}
+interface ChatMessage {
+    role: "user" | "assistant" | "tool" | "error";
+    content: MessageContent;
+    reasoning?: string;
+    tool_calls?: ToolCallInfo[];
+    status?: "streaming" | "completed" | "paused" | "failed" | "interrupted";
+    duration_ms?: number;
+    timestamp?: string;
+    entry_id?: string;
+    parent_id?: string | null;
+    loop_name?: string;
+    /** Entry kind from backend — present for non-message entries like planning_enter/exit */
+    kind?: string;
+    /** Memory references injected into this turn's context */
+    memory_refs?: MemoryRefInfo[];
+    /** Raw projection blocks for block-level UI rendering. */
+    blocks?: ContentBlock[];
+    /** Compaction metadata for compaction turns. */
+    compaction?: CompactionInfo;
+}
+
+interface OptionItem {
+    label: string;
+    description: string;
+}
+interface QuestionItem {
+    question: string;
+    options: OptionItem[];
+    multiSelect?: boolean;
+}
+interface SourceLoopInfo {
+    loop_name: string;
+    description: string;
+}
+interface AskUserQuestionData {
+    questions: QuestionItem[];
+    source_loop?: SourceLoopInfo | null;
+}
+type AskUserAnswerData = {
+    selections: Record<number, number[]>;
+    custom: Record<number, string>;
+};
+interface Props {
+    data: AskUserQuestionData;
+    answered: boolean;
+    toolCallId: string;
+    sessionStatus: string;
+    answerData?: AskUserAnswerData | undefined;
+    onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
+}
+declare function AskUserQuestionBlock({ data, answered, toolCallId, sessionStatus, answerData, onAnswer, }: Props): react_jsx_runtime.JSX.Element;
+
+export { type AskUserAnswerData as A, type ChatMessage as C, type FileContentPart as F, type ImageUrlContentPart as I, type MessageContent as M, type ToolCallInfo as T, type CompactionInfo as a, AskUserQuestionBlock as b, type MessageContentPart as c, type TextContentPart as d };

package/dist/SkillStatusBar-DItrW2vv.d.ts

@@ -0,0 +1,203 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { M as MessageContent, C as ChatMessage, A as AskUserAnswerData } from './AskUserQuestionBlock-CjvG_pUY.js';
+import * as zustand from 'zustand';
+import { M as ModeId, S as SessionInfo, a as SessionStatus } from './session-CDeiO81j.js';
+import { m as BladeClient } from './blade-client-nOsdVlb1.js';
+
+/**
+ * 把 whatif-rerun 后端组装的 prompt 文本解析成可折叠展示的结构。
+ *
+ * 当前后端格式（`host/orchestrator/whatif_rerun.py::_compose_whatif_prompt`）：
+ *
+ *   以下消息和 step 产物标记为 deprecated_by_rerun，请基于最新用户假设从 step{N} 开始完整重新推演，不要复用旧结论。
+ *
+ *   [引用]
+ *   [步骤{n} · {label}]
+ *   {snapshot markdown…（内部允许空行）}
+ *   [步骤{m} · {label}]
+ *   {snapshot markdown…}
+ *
+ *   [用户输入]
+ *   {用户真正输入的文本}
+ *
+ * Legacy 格式（历史 session 里没有 `[用户输入]` 标签）：
+ *   …最后一条 snapshot 末尾…
+ *   <空行>
+ *   {用户真正输入的文本}
+ *
+ * Legacy 情况下用"从末尾反向扫描第一段连续空行"做切分。markdown 末尾段落
+ * 被误吃的风险可接受——总比让用户完全看不到自己的输入好。
+ */
+interface WhatIfQuote {
+    stepNumber: number | null;
+    label: string;
+    snapshot: string;
+}
+interface ParsedWhatIfPrompt {
+    fromStep: number | null;
+    quotes: WhatIfQuote[];
+    userText: string;
+}
+interface BuildWhatIfPromptInput {
+    fromStep: number;
+    quotes: Array<{
+        stepNumber?: number | null;
+        label?: string | null;
+        snapshot?: string | null;
+    }>;
+    userText: string;
+}
+declare function buildWhatIfPrompt({ fromStep, quotes, userText, }: BuildWhatIfPromptInput): string;
+declare function parseWhatIfPrompt(text: string): ParsedWhatIfPrompt | null;
+
+interface ClientAwareState {
+    _client: BladeClient | null;
+    setClient: (client: BladeClient) => void;
+}
+
+declare const ATTACHMENT_SIZE_LIMIT_BYTES: number;
+type OversizedFileInfo = {
+    name: string;
+    size: number;
+};
+declare function formatFileSize(size: number): string;
+declare function splitFilesBySize(files: FileList | File[], limitBytes?: number): {
+    accepted: File[];
+    rejected: OversizedFileInfo[];
+};
+
+interface ChatViewProps {
+    sessionId: string;
+    renderAttachments?: () => ReactNode;
+    onBeforeSend?: (content: MessageContent) => MessageContent;
+    onCommand?: (commandId: string) => void | Promise<void>;
+    canShareSession?: boolean;
+    onResyncSkills?: () => void;
+    isResyncingSkills?: boolean;
+}
+declare function ChatView({ sessionId, renderAttachments, onBeforeSend, onCommand, canShareSession, onResyncSkills, isResyncingSkills, }: ChatViewProps): react_jsx_runtime.JSX.Element;
+
+type SessionMode = ModeId;
+interface SessionState extends ClientAwareState {
+    sessions: SessionInfo[];
+    activeSessionId: string | null;
+    loading: boolean;
+    modes: Record<string, SessionMode>;
+    rewindDrafts: Record<string, string>;
+    /** Session IDs that were just created and haven't had their first history load yet */
+    _freshSessions: Set<string>;
+    fetchSessions: () => Promise<void>;
+    createSession: (intent?: string) => Promise<string>;
+    registerCreatedSession: (session: SessionInfo, mode?: SessionMode) => void;
+    upsertSession: (session: SessionInfo) => void;
+    isFreshSession: (sessionId: string) => boolean;
+    setActiveSession: (id: string) => void;
+    clearActiveSession: () => void;
+    deleteSession: (id: string) => Promise<void>;
+    updateSessionStatus: (sessionId: string, status: SessionStatus) => void;
+    updateSessionIntent: (sessionId: string, intent: string) => void;
+    /**
+     * ship-attack v2：通用增量更新 session 字段。用于 session:updated 等事件
+     * 广播"后端刚改了 session 元数据（intent / bound_skill_id / ...）"时，
+     * 前端原地 patch sessions 缓存，而不需要重新拉整个列表。
+     */
+    patchSession: (sessionId: string, patch: Partial<SessionInfo>) => void;
+    pinSession: (sessionId: string, pinned: boolean) => Promise<void>;
+    setRewindDraft: (sessionId: string, text: string | null) => void;
+    setMode: (sessionId: string, mode: SessionMode) => void;
+    togglePlanningMode: (sessionId: string) => void;
+    toggleSharing: (sessionId: string) => Promise<void>;
+    reset: () => void;
+}
+/** 侧栏等使用 React Query 拉取会话列表时，与 zustand patch 同步失效。 */
+declare function invalidateHomeSidebarSessions(): void;
+declare const useSessionStore: zustand.UseBoundStore<zustand.StoreApi<SessionState>>;
+
+interface Props$2 {
+    onSend: (message: MessageContent, targetSessionId?: string, model?: string | null) => void;
+    onStop: () => void;
+    isStreaming: boolean;
+    mode?: SessionMode;
+    onToggleMode?: () => void;
+    renderAttachments?: () => ReactNode;
+    onBeforeSend?: (content: MessageContent) => MessageContent;
+    /**
+     * Creates (or returns) a session to upload pending attachments into when
+     * the composer has files but no active session yet. The returned id is
+     * used for the upload, and is also passed back to `onSend` so the send
+     * path reaches exactly the session the files landed in — independent of
+     * whatever the global activeSessionId is at that moment.
+     */
+    ensureSession?: (draftText: string) => Promise<string>;
+    onCommand?: (commandId: string) => void | Promise<void>;
+    canShareSession?: boolean;
+    /**
+     * Optional slot rendered directly above the textarea (below any file-pill
+     * bar). ship-attack uses this to mount QuoteChipList for R4.
+     */
+    slotAboveTextarea?: ReactNode;
+    /**
+     * Optional external draft channel. When provided, the composer initializes
+     * from `value` on mount and mirrors every internal `setInput` call into
+     * `setValue`. Intended for ship-attack's cross-view draft sharing (R3.8),
+     * not full controlled-input semantics — the tiptap editor remains the
+     * source of truth, this is a persistence side-channel.
+     */
+    externalDraft?: {
+        value: string;
+        setValue: (v: string) => void;
+    };
+    /**
+     * Optional external attachments channel. Same mirror semantics as
+     * externalDraft. Upload state (pending/uploading/...) is carried on
+     * `FileComposerAttachment.status`, so sharing the array is enough.
+     */
+    externalAttachments?: {
+        value: FileComposerAttachment[];
+        setValue: (a: FileComposerAttachment[]) => void;
+    };
+    /** Tailwind class for the inner max-width wrapper. Defaults to `max-w-3xl`. */
+    maxWidthClassName?: string;
+    onResyncSkills?: () => void;
+    isResyncingSkills?: boolean;
+}
+type FileComposerAttachment = {
+    id: string;
+    kind: "file";
+    name: string;
+    size: number;
+    mimeType: string;
+    status: "pending" | "uploading" | "uploaded" | "failed";
+    file?: File;
+    uploadedPath?: string;
+    textContent?: string | null;
+};
+declare function ChatInput({ onSend, onStop, isStreaming, mode, onToggleMode, renderAttachments, onBeforeSend, ensureSession, onCommand, canShareSession, slotAboveTextarea, externalDraft, externalAttachments, maxWidthClassName, onResyncSkills, isResyncingSkills, }: Props$2): react_jsx_runtime.JSX.Element;
+
+interface Props$1 {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+    files: OversizedFileInfo[];
+    limitBytes?: number;
+}
+declare function FileSizeLimitDialog({ open, onOpenChange, files, limitBytes, }: Props$1): react.ReactPortal | null;
+
+interface Props {
+    sessionId: string;
+    messages: ChatMessage[];
+    onAnswer?: (answer: string, toolCallId: string, answerData: AskUserAnswerData) => void;
+    sessionStatus?: string;
+    onConfirmPlan?: (action: "execute" | "revise", text?: string) => void;
+}
+declare function MessageList({ sessionId, messages: rawMessages, onAnswer, sessionStatus, onConfirmPlan, }: Props): react_jsx_runtime.JSX.Element;
+
+declare function SkillStatusBar({ sessionId, onResync, isResyncing, vertical, }: {
+    sessionId: string;
+    onResync?: () => void;
+    isResyncing?: boolean;
+    vertical?: boolean;
+}): react_jsx_runtime.JSX.Element;
+
+export { ATTACHMENT_SIZE_LIMIT_BYTES as A, type BuildWhatIfPromptInput as B, ChatInput as C, type FileComposerAttachment as F, MessageList as M, type OversizedFileInfo as O, type ParsedWhatIfPrompt as P, SkillStatusBar as S, type WhatIfQuote as W, ChatView as a, FileSizeLimitDialog as b, type ClientAwareState as c, buildWhatIfPrompt as d, formatFileSize as f, invalidateHomeSidebarSessions as i, parseWhatIfPrompt as p, splitFilesBySize as s, useSessionStore as u };