@blade-hq/agent-client 1.1.1

package/dist/resources/auth.d.ts

@@ -0,0 +1,34 @@
+import type { BladeClient } from "../blade-client";
+import type { LoginOptions, LoginResult } from "../auth-login";
+export interface UserInfo {
+    id: string;
+    username: string;
+    display_name?: string | null;
+    avatar_url: string | null;
+    token: string;
+    auth_type: "casdoor";
+    is_admin?: boolean;
+}
+export interface ProvidersResponse {
+    providers: Array<{
+        name: string;
+        authorize_url: string;
+    }>;
+    password_enabled: boolean;
+}
+export declare class AuthResource {
+    private client;
+    constructor(client: BladeClient);
+    /**
+     * 弹窗授权登录（浏览器专用）：弹出后端授权页，用户点击"许可授权"后
+     * 自动取得 PAT 并热挂载到当前 client。等价于 client.login()。
+     */
+    login(options?: LoginOptions): Promise<LoginResult>;
+    /** 清除 login() 存储的令牌。 */
+    logoutToken(): void;
+    getProviders(): Promise<ProvidersResponse>;
+    getMe(): Promise<UserInfo>;
+    logout(): Promise<{
+        logout_url: string;
+    }>;
+}

package/dist/resources/headless.d.ts

@@ -0,0 +1,33 @@
+import type { BladeClient } from "../blade-client";
+export type JsonSchemaObject = Record<string, unknown>;
+export interface HeadlessRunOptions {
+    schema?: JsonSchemaObject | null;
+    model?: string | null;
+    timeoutMs?: number;
+}
+export interface HeadlessRunInSessionResult<T = unknown> {
+    session_id: string;
+    chat_run_id: string | null;
+    result: T | string;
+}
+export declare class HeadlessError extends Error {
+    readonly detail?: unknown;
+    constructor(message: string, detail?: unknown);
+}
+export declare class HeadlessResource {
+    private client;
+    constructor(client: BladeClient);
+    run<T = unknown>(prompt: string, options: HeadlessRunOptions & {
+        schema: JsonSchemaObject;
+    }): Promise<T>;
+    run(prompt: string, options?: HeadlessRunOptions): Promise<string>;
+    runInSession<T = unknown>(sessionId: string, prompt: string, options: HeadlessRunOptions & {
+        schema: JsonSchemaObject;
+    }): Promise<T>;
+    runInSession(sessionId: string, prompt: string, options?: HeadlessRunOptions): Promise<string>;
+    runWithSession<T = unknown>(prompt: string, options: HeadlessRunOptions & {
+        schema: JsonSchemaObject;
+    }): Promise<HeadlessRunInSessionResult<T>>;
+    runWithSession(prompt: string, options?: HeadlessRunOptions): Promise<HeadlessRunInSessionResult<string>>;
+    private runTracked;
+}

package/dist/resources/sessions.d.ts

@@ -0,0 +1,263 @@
+import type { BackgroundTask } from "../schemas/background";
+import type { TurnProjection } from "../schemas/projection";
+import type { SessionDetail, SessionInfo, TemplateId } from "../schemas/session";
+import type { Task } from "../schemas/task";
+import type { BladeClient, UploadProgress } from "../blade-client";
+import type { AgentSession } from "../session/agent-session";
+import type { SessionProfile } from "../types/sdk-profile";
+export interface CreateSessionRequest {
+    intent?: string;
+    template_id?: TemplateId;
+    solution_id?: string;
+    biz_role_id?: string | null;
+    primary_skill_id?: string | null;
+    model?: string | null;
+    enable_thinking?: boolean | null;
+    memory_enabled?: boolean | null;
+    env?: Record<string, string>;
+    disable_tools?: string[] | null;
+    session_solution_asset_id?: string | null;
+    compaction_ratio?: number | null;
+    runtime_type?: "sandbox" | "daemon" | null;
+    daemon_id?: string | null;
+}
+export interface CheckpointNode {
+    id: string;
+    parent_id: string | null;
+    content_preview: string;
+    content: string;
+    timestamp: string;
+}
+export type ContentPart = {
+    type: "text";
+    text: string;
+} | {
+    type: "image_url";
+    image_url: {
+        url: string;
+        detail?: string;
+    };
+};
+export interface HistoryNode {
+    id: string;
+    parent_id: string | null;
+    kind: string;
+    role: string;
+    timestamp: string;
+    preview: string;
+    content: string | ContentPart[];
+    tool_calls: Array<{
+        id?: string;
+        type?: string;
+        function?: {
+            name?: string;
+            arguments?: string;
+        };
+    }> | null;
+    usage: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+        total_tokens?: number;
+    } | null;
+    total_tokens: number;
+    token_diff: number;
+    is_deprecated: boolean;
+    loop_name: string;
+}
+export interface SessionHistory {
+    nodes: HistoryNode[];
+    active_branch: string | null;
+    branches: string[];
+    system_prompt_tokens?: number | null;
+    tools_tokens?: number | null;
+    tokenizer_model?: string | null;
+}
+export interface TokenizeResult {
+    model: string;
+    prompt_tokens: number;
+    prompt: string;
+}
+export interface PaginatedSessionsResult {
+    items: SessionInfo[];
+    total: number;
+    limit: number;
+    offset: number;
+    content_match_truncated?: boolean;
+}
+export interface SkillDevSession {
+    session: SessionInfo;
+    skill_id: string;
+    display_name: string;
+    skill_description: string;
+}
+export interface ShareLinkResult {
+    token: string;
+    url: string;
+    expires_at: string | null;
+}
+export interface SessionContextStats {
+    tokens_used: number;
+    context_window: number;
+    compaction_ratio: number;
+}
+export interface FileEntry {
+    name: string;
+    path: string;
+    is_dir: boolean;
+    created_at: number;
+    tags?: string[];
+}
+export type UploadFileEntry = File | {
+    file: File;
+    name: string;
+};
+export interface UploadFilesOptions {
+    onProgress?: (progress: UploadProgress) => void;
+}
+export interface ImportPreviewSkill {
+    name: string;
+    description: string;
+    path: string;
+}
+export interface ImportPreviewScenario {
+    scenario?: {
+        name?: string;
+    };
+    skills?: string[];
+    preview_urls?: string[];
+    init_script?: string;
+    generated_at?: string;
+}
+export interface ImportPreview {
+    user_messages: string[];
+    turn_count: number;
+    skills: ImportPreviewSkill[];
+    scenario: ImportPreviewScenario | null;
+}
+export declare class SessionsResource {
+    private client;
+    constructor(client: BladeClient);
+    /**
+     * 连接一个已存在的会话，返回实时会话对象 AgentSession
+     * （自动完成历史加载、Socket.IO 订阅、断线重连补数）。
+     */
+    connect(sessionId: string): Promise<AgentSession>;
+    /** 创建新会话并直接连接，返回可收发消息的 AgentSession。 */
+    create(request?: CreateSessionRequest): Promise<AgentSession>;
+    private fetchSessionsPage;
+    listSessions(template_id_prefix?: string, solution_id?: string): Promise<SessionInfo[]>;
+    listSessionsPaginated(params: {
+        limit: number;
+        offset: number;
+        template_id_prefix?: string;
+        solution_id?: string;
+        q?: string;
+    }): Promise<PaginatedSessionsResult>;
+    listSessionsWithSkillData(): Promise<SkillDevSession[]>;
+    createSession(intent?: string, template_id?: TemplateId, primary_skill_id?: string | null): Promise<{
+        session_id: string;
+    }>;
+    createSessionWithRequest(request: CreateSessionRequest): Promise<{
+        session_id: string;
+    }>;
+    createWithProfile(params: {
+        intent: string;
+        profile: SessionProfile;
+    }): Promise<{
+        session_id: string;
+    }>;
+    getSession(sessionId: string, init?: RequestInit): Promise<SessionDetail>;
+    updateSession(sessionId: string, payload: {
+        intent?: string;
+    }): Promise<SessionDetail>;
+    setSessionEnv(sessionId: string, env: Record<string, string>): Promise<SessionDetail>;
+    pinSession(sessionId: string, pinned: boolean): Promise<SessionInfo>;
+    startReplaySession(sourceSessionId: string, speed?: 1 | 2 | 5): Promise<{
+        session_id: string;
+    }>;
+    updateReplaySession(sessionId: string, payload: {
+        speed?: 1 | 2 | 5;
+        status?: "autonomous";
+    }): Promise<{
+        replay_state: SessionInfo["replay_state"];
+    }>;
+    updateSharing(sessionId: string, shared: boolean): Promise<{
+        shared: boolean;
+    }>;
+    updateSessionMemory(sessionId: string, memoryEnabled: boolean): Promise<{
+        memory_enabled: boolean;
+    }>;
+    createShare(sessionId: string): Promise<ShareLinkResult>;
+    revokeShare(sessionId: string, token: string): Promise<{
+        revoked: boolean;
+    }>;
+    getSharedSession(token: string): Promise<TurnProjection[]>;
+    getSessionTasks(sessionId: string): Promise<Task[]>;
+    getSessionTurns(sessionId: string): Promise<TurnProjection[]>;
+    getSessionContextStats(sessionId: string, init?: RequestInit): Promise<SessionContextStats>;
+    getSessionHistory(sessionId: string, init?: RequestInit): Promise<SessionHistory>;
+    tokenizePrompt(prompt: string, model?: string): Promise<TokenizeResult>;
+    tokenizeMessages(messages: Array<Record<string, unknown>>, options?: {
+        model?: string;
+        add_generation_prompt?: boolean;
+        enable_thinking?: boolean | null;
+        tools?: Array<Record<string, unknown>>;
+    }): Promise<TokenizeResult>;
+    getSessionCheckpoints(sessionId: string, init?: RequestInit): Promise<{
+        nodes: CheckpointNode[];
+        leaf_id: string | null;
+    }>;
+    checkoutSession(sessionId: string, checkpointId: string, position: "before" | "turn_end", mode?: "both" | "conversation" | "code", linear?: boolean): Promise<{
+        id: string;
+        content: string;
+        position: string;
+        mode?: string;
+        files_restored?: boolean;
+        linear?: boolean;
+    }>;
+    rewindSession(sessionId: string, checkpointId: string): Promise<{
+        id: string;
+        content: string;
+    }>;
+    switchBranch(sessionId: string, checkpointId: string): Promise<{
+        id: string;
+        leaf_id: string;
+    }>;
+    deleteSession(sessionId: string): Promise<{
+        deleted: boolean;
+    }>;
+    listBackgroundTasks(sessionId: string, init?: RequestInit): Promise<BackgroundTask[]>;
+    getBackgroundTask(sessionId: string, taskId: string, tail?: number, init?: RequestInit): Promise<BackgroundTask>;
+    stopBackgroundTask(sessionId: string, taskId: string): Promise<{
+        message: string;
+        task?: BackgroundTask | null;
+    }>;
+    probeSessionUrl(sessionId: string, url: string): Promise<{
+        reachable: boolean;
+    }>;
+    listDir(sessionId: string, dirPath: string): Promise<FileEntry[]>;
+    uploadFiles(sessionId: string, dirPath: string, files: FileList | File[] | UploadFileEntry[], options?: UploadFilesOptions): Promise<{
+        uploaded: string[];
+        failed: string[];
+    }>;
+    deleteFile(sessionId: string, filePath: string): Promise<void>;
+    writeFile(sessionId: string, filePath: string, content: string): Promise<{
+        success: boolean;
+    }>;
+    renameFile(sessionId: string, filePath: string, newName: string): Promise<{
+        path: string;
+    }>;
+    copyFile(sessionId: string, filePath: string): Promise<{
+        path: string;
+    }>;
+    shareFile(sessionId: string, sourcePath: string, linkName?: string, shareFolder?: string): Promise<{
+        path: string;
+        target: string;
+    }>;
+    getDownloadDirUrl(sessionId: string, dirPath: string): string;
+    exportSession(sessionId: string): Promise<void>;
+    previewImport(file: File): Promise<ImportPreview>;
+    importSession(file: File, name?: string, solutionId?: string | null): Promise<{
+        session_id: string;
+    }>;
+}

package/dist/rest.d.ts

@@ -0,0 +1,21 @@
+export declare class BladeApiError extends Error {
+    readonly response: Response;
+    readonly status: number;
+    readonly statusText: string;
+    constructor(response: Response, message?: string);
+}
+/**
+ * 从 FastAPI 风格的错误响应中提取 detail 字段，作为用户可读的中文错误文案。
+ * 失败时返回 undefined，调用方会回退到默认提示。
+ */
+export declare function extractErrorDetail(response: Response): Promise<string | undefined>;
+/** 401/403 补充"怎么办"的指引，避免初级开发者对着裸状态码发呆。 */
+export declare function decorateAuthError(error: unknown): unknown;
+export type HttpMethod = "DELETE" | "GET" | "PATCH" | "POST" | "PUT" | (string & {});
+export interface BladeFetchInit {
+    body?: BodyInit | null;
+    credentials?: RequestCredentials;
+    expectOk?: boolean;
+    headers?: HeadersInit;
+    signal?: AbortSignal | null;
+}

package/dist/schemas/background.d.ts

@@ -0,0 +1,16 @@
+export interface BackgroundTask {
+    id: string;
+    command: string;
+    description?: string;
+    status: "queued" | "starting" | "running" | "succeeded" | "done" | "failed" | "timeout" | "cancelled" | "lost";
+    legacy_status?: "running" | "done" | "failed";
+    exit_code?: number | null;
+    elapsed_seconds: number;
+    output_lines_count?: number;
+    output_preview?: string[];
+    output?: string;
+    log_path?: string | null;
+    started_at?: number | null;
+    finished_at?: number | null;
+    heartbeat_at?: number | null;
+}

package/dist/schemas/event.d.ts

@@ -0,0 +1,51 @@
+export interface ContentDelta {
+    content: string;
+    loop_name?: string;
+}
+export interface ToolCallCreated {
+    index: number;
+    id: string;
+    loop_name?: string;
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+export interface ToolResultDone {
+    tool_call_id: string;
+    loop_name?: string;
+    function: {
+        name: string;
+    };
+    content: string;
+}
+export interface ToolResultDelta {
+    tool_call_id: string;
+    loop_name?: string;
+    content: string;
+    stream?: "stdout" | "stderr";
+}
+export interface LlmResponseDone {
+    role: string;
+    content?: string | null;
+    reasoning?: string | null;
+    loop_name?: string;
+    tool_calls?: {
+        id: string;
+        function: {
+            name: string;
+            arguments: string;
+        };
+    }[];
+}
+export interface ChatEnd {
+    status: string;
+    duration_ms: number;
+}
+export interface SystemError {
+    message: string;
+}
+export interface SessionStatusEvent {
+    session_id: string;
+    status: string;
+}

package/dist/schemas/message-utils.d.ts

@@ -0,0 +1,48 @@
+import type { ChatMessage, FileContentPart, ImageUrlContentPart, MessageContent } from "./message";
+export declare function normalizeMessageContent(content: unknown): MessageContent;
+export declare function getTextContent(content: MessageContent): string;
+export declare function isSystemReminderText(text: string): boolean;
+export declare function isLegacyForkContextText(text: string): boolean;
+export declare function isHiddenInternalMessage(message: Pick<ChatMessage, "role" | "content">): boolean;
+export declare function buildMessageContent(text: string, attachments: Array<{
+    kind: "file";
+    name: string;
+    uploadedPath?: string;
+    textContent?: string | null;
+    mimeType?: string;
+}>): MessageContent;
+export declare function contentPreview(content: MessageContent, maxLen?: number): string;
+/**
+ * Transform a skill mention into a natural language skill invocation.
+ * Strips the `<skill>name</skill>` tag from the raw input and prepends the instruction.
+ */
+export declare function transformSlashCommand(skillName: string, rawInput: string): string;
+export interface ParsedTextAttachment {
+    name: string;
+    uploadedPath?: string;
+}
+export interface ParsedTextContext {
+    label: string;
+    content: string;
+}
+/**
+ * Extract `[附件: name]` and `[上下文: label]` tags from text parts and return
+ * the cleaned text plus the collected attachment / context metadata. 每个 text
+ * part 独立匹配，以避免跨 part 拼接打乱正则。
+ */
+export declare function extractTextAttachments(content: MessageContent): {
+    cleanText: string;
+    attachments: ParsedTextAttachment[];
+    contexts: ParsedTextContext[];
+};
+export declare function getImageParts(content: MessageContent): ImageUrlContentPart[];
+export declare function getFileParts(content: MessageContent): FileContentPart[];
+interface MessageGroup {
+    root: ChatMessage | null;
+    childLoops: {
+        loopName: string;
+        messages: ChatMessage[];
+    }[];
+}
+export declare function groupMessagesByLoop(messages: ChatMessage[]): MessageGroup[];
+export {};

package/dist/schemas/message.d.ts

@@ -0,0 +1,83 @@
+import type { ContentBlock, PendingQuestionRef, ToolBridgeContent } from "./projection";
+export interface TextContentPart {
+    type: "text";
+    text: string;
+}
+export interface ImageUrlContentPart {
+    type: "image_url";
+    image_url: {
+        url: string;
+    };
+}
+export interface FileContentPart {
+    type: "file";
+    name: string;
+    data: string;
+}
+export type MessageContentPart = TextContentPart | ImageUrlContentPart | FileContentPart;
+export type MessageContent = string | MessageContentPart[];
+export 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;
+}
+export type { ToolBridgeContent };
+/** Derive tool status from the result content string. */
+export declare function inferToolStatus(resultStr: string): "done" | "error" | "cancelled";
+export interface MemoryRefInfo {
+    id: number;
+    content_preview: string;
+    skill_name?: string | null;
+}
+export 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;
+}
+export interface ArchivedFileInfo {
+    tool_name?: string | null;
+    filename?: string | null;
+    relative_path?: string | null;
+    size_bytes?: number | null;
+}
+export interface ArchivedToolCallInfo {
+    tool_call_id?: string | null;
+    tool_name?: string | null;
+    archive_path?: string | null;
+    replacement_content?: string | null;
+    entry_id?: string | null;
+}
+export 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 mode changes. */
+    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;
+}

package/dist/schemas/projection.d.ts

@@ -0,0 +1,87 @@
+export interface ToolBridgeContent {
+    action: string;
+    payload?: unknown;
+}
+export interface ContentBlock {
+    type: "text" | "thinking" | "tool_use" | "tool_result" | "tool_ui" | "tool_bridge" | "system_notification" | "mode_change" | "plan_status" | "ask_user_answer";
+    content: unknown;
+    tool_call_id?: string | null;
+    tool_name?: string | null;
+    display_name?: string | null;
+}
+export interface PendingQuestionRef {
+    child_loop_name: string;
+    child_tool_call_id: string;
+    description?: string | null;
+}
+export interface ToolCallProjection {
+    id: string;
+    tool_name: string;
+    display_name: string;
+    arguments: string;
+    status: "pending" | "done" | "error" | "cancelled" | "awaiting_answer" | string;
+    result?: unknown;
+    duration_ms?: number | null;
+    pending_question_ref?: PendingQuestionRef | null;
+}
+export interface MemoryRef {
+    id: number;
+    content_preview: string;
+    skill_name?: string | null;
+}
+export interface TurnProjection {
+    id: string;
+    sequence: number;
+    turn_id: string;
+    loop_id: string;
+    kind?: "message" | "compaction";
+    role: "user" | "assistant" | "system";
+    status: "streaming" | "completed" | "paused" | "failed" | "interrupted";
+    blocks: ContentBlock[];
+    tool_calls: ToolCallProjection[];
+    model?: string | null;
+    usage?: Record<string, unknown> | null;
+    duration_ms?: number;
+    started_at?: string | null;
+    context_window?: number;
+    memory_refs?: MemoryRef[] | null;
+    parent_fork_tool_call_id?: string | null;
+    compaction_id?: string | null;
+    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;
+}
+export interface ArchivedFileInfo {
+    tool_name?: string | null;
+    filename?: string | null;
+    relative_path?: string | null;
+    size_bytes?: number | null;
+}
+export interface ArchivedToolCallInfo {
+    tool_call_id?: string | null;
+    tool_name?: string | null;
+    archive_path?: string | null;
+    replacement_content?: string | null;
+    entry_id?: string | null;
+}
+export interface PatchEnvelope {
+    sequence: number;
+    turn_id: string;
+    loop_id: string;
+    patch_type: string;
+    data: {
+        turn?: TurnProjection;
+        workspace_changed?: {
+            tool_call_id?: string;
+            tool_name?: string;
+        };
+    };
+}