@blade-hq/agent-client 1.1.1

package/dist/types/sdk-profile.d.ts

@@ -0,0 +1,47 @@
+export interface ExistingSolutionRef {
+    kind: "existing";
+    solutionId: string;
+    bizRoleId?: string;
+}
+export interface PreparedSolutionAsset {
+    kind: "prepared";
+    assetId: string;
+    bizRoleId?: string;
+}
+export type SolutionRef = ExistingSolutionRef | PreparedSolutionAsset;
+export interface SessionProfile {
+    solution?: SolutionRef;
+    model?: string;
+    compactionRatio?: number;
+    enableThinking?: boolean;
+    memoryEnabled?: boolean;
+    disableTools?: string[];
+    env?: Record<string, string>;
+}
+export interface RunOptions {
+    headless?: boolean;
+    outputSchema?: Record<string, unknown>;
+    runtimeEnv?: Record<string, string>;
+    timeoutMs?: number;
+    trace?: boolean;
+    compactionRatio?: number;
+    model?: string;
+}
+export interface PreparedSolution extends PreparedSolutionAsset {
+    assetId: string;
+    solutionId: string;
+    roles: string[];
+    expiresAt: string;
+}
+export interface RunResult {
+    sessionId: string;
+    chatRunId?: string;
+    result: unknown;
+    events: unknown[];
+}
+export interface RunTrace {
+    events: unknown[];
+    history: unknown[];
+    result: unknown;
+    configSnapshot: Record<string, unknown>;
+}

package/dist/types/socket-events.d.ts

@@ -0,0 +1,401 @@
+/**
+ * 语音识别音频帧。后端（socketio_handlers.py）两种都收：
+ * 裸二进制，或带 request_id 的对象——一条连接上并发多个识别会话时，
+ * 只有带 request_id 才能区分是哪一路的音频。
+ */
+export type AsrAudioPayload = ArrayBuffer | Uint8Array | {
+    pcm: ArrayBuffer | Uint8Array;
+    request_id?: string;
+};
+export declare namespace ChatSendPayloadSchema {
+    type SessionId = string;
+    type Mode = (("planning" | "executing") | null);
+    type AskuserAnswer = ({
+        [k: string]: unknown;
+    } | null);
+    type Model = (string | null);
+    type ThinkingOverride = (boolean | null);
+    type Headless = boolean;
+    type OutputSchema = ({
+        [k: string]: unknown;
+    } | null);
+    type FromStep = (number | string | null);
+    type Quotes = (unknown[] | null);
+    type DeprecateEntryIds = (string[] | null);
+    type ReplayDecision = (string | null);
+    type RuntimeEnv = ({
+        [k: string]: string;
+    } | null);
+    type CompactionRatio = (number | null);
+    interface ChatSendPayload {
+        session_id: SessionId;
+        message: Message;
+        mode?: Mode;
+        askuser_answer?: AskuserAnswer;
+        model?: Model;
+        thinking_override?: ThinkingOverride;
+        headless?: Headless;
+        output_schema?: OutputSchema;
+        whatif?: (WhatIfPayload | null);
+        replay_decision?: ReplayDecision;
+        runtime_env?: RuntimeEnv;
+        compaction_ratio?: CompactionRatio;
+        [k: string]: unknown;
+    }
+    interface Message {
+        [k: string]: unknown;
+    }
+    interface WhatIfPayload {
+        from_step?: FromStep;
+        quotes?: Quotes;
+        deprecate_entry_ids?: DeprecateEntryIds;
+        [k: string]: unknown;
+    }
+}
+export type ChatSendPayload = ChatSendPayloadSchema.ChatSendPayload;
+export declare namespace ChatStopPayloadSchema {
+    type SessionId = string;
+    interface ChatStopPayload {
+        session_id: SessionId;
+        [k: string]: unknown;
+    }
+}
+export type ChatStopPayload = ChatStopPayloadSchema.ChatStopPayload;
+export declare namespace ChatAppendPayloadSchema {
+    type SessionId = string;
+    type Message = string;
+    interface ChatAppendPayload {
+        session_id: SessionId;
+        message: Message;
+        [k: string]: unknown;
+    }
+}
+export type ChatAppendPayload = ChatAppendPayloadSchema.ChatAppendPayload;
+export declare namespace ChatCompactPayloadSchema {
+    type SessionId = string;
+    interface ChatCompactPayload {
+        session_id: SessionId;
+        [k: string]: unknown;
+    }
+}
+export type ChatCompactPayload = ChatCompactPayloadSchema.ChatCompactPayload;
+export declare namespace SessionSubscribePayloadSchema {
+    type SessionId = string;
+    type Mode = string;
+    type EventFormat = "raw";
+    type AfterSequence = number;
+    type Resume = boolean;
+    interface SessionSubscribePayload {
+        session_id: SessionId;
+        mode?: Mode;
+        event_format?: EventFormat;
+        after_sequence?: AfterSequence;
+        resume?: Resume;
+        [k: string]: unknown;
+    }
+}
+export type SessionSubscribePayload = SessionSubscribePayloadSchema.SessionSubscribePayload;
+export declare namespace SessionSubscribeBatchPayloadSchema {
+    /**
+     * @minItems 1
+     * @maxItems 200
+     */
+    type Sessions = [SessionSubscribe, ...(SessionSubscribe)[]];
+    type SessionId = string;
+    type Mode = string;
+    type EventFormat = "raw";
+    type AfterSequence = number;
+    type Resume = boolean;
+    interface SessionSubscribeBatchPayload {
+        sessions: Sessions;
+        [k: string]: unknown;
+    }
+    interface SessionSubscribe {
+        session_id: SessionId;
+        mode?: Mode;
+        event_format?: EventFormat;
+        after_sequence?: AfterSequence;
+        resume?: Resume;
+        [k: string]: unknown;
+    }
+}
+export type SessionSubscribeBatchPayload = SessionSubscribeBatchPayloadSchema.SessionSubscribeBatchPayload;
+export declare namespace SessionUnsubscribePayloadSchema {
+    type SessionId = string;
+    interface SessionUnsubscribePayload {
+        session_id: SessionId;
+        [k: string]: unknown;
+    }
+}
+export type SessionUnsubscribePayload = SessionUnsubscribePayloadSchema.SessionUnsubscribePayload;
+export declare namespace AgentBoardProjectSubscribePayloadSchema {
+    type ProjectId = number;
+    interface AgentBoardProjectSubscribePayload {
+        project_id: ProjectId;
+        [k: string]: unknown;
+    }
+}
+export type AgentBoardProjectSubscribePayload = AgentBoardProjectSubscribePayloadSchema.AgentBoardProjectSubscribePayload;
+export declare namespace AgentBoardProjectUnsubscribePayloadSchema {
+    type ProjectId = number;
+    interface AgentBoardProjectUnsubscribePayload {
+        project_id: ProjectId;
+        [k: string]: unknown;
+    }
+}
+export type AgentBoardProjectUnsubscribePayload = AgentBoardProjectUnsubscribePayloadSchema.AgentBoardProjectUnsubscribePayload;
+export declare namespace ChatStartPayloadSchema {
+    type SessionId = (string | null);
+    interface ChatStartPayload {
+        session_id?: SessionId;
+        [k: string]: unknown;
+    }
+}
+export type ChatStartPayload = ChatStartPayloadSchema.ChatStartPayload;
+export declare namespace ChatEndPayloadSchema {
+    type SessionId = (string | null);
+    type Status = (string | null);
+    type FinishReason = (string | null);
+    type ChatRunId = (string | null);
+    interface ChatEndPayload {
+        session_id?: SessionId;
+        status?: Status;
+        result?: unknown;
+        finish_reason?: FinishReason;
+        chat_run_id?: ChatRunId;
+        [k: string]: unknown;
+    }
+}
+export type ChatEndPayload = ChatEndPayloadSchema.ChatEndPayload;
+export declare namespace SessionUpdatedPayloadSchema {
+    type SessionId = string;
+    type Model = (string | null);
+    type ReplayState = ({
+        [k: string]: unknown;
+    } | null);
+    type Intent = (string | null);
+    type ProjectId = (number | null);
+    type ProjectName = (string | null);
+    interface SessionUpdatedPayload {
+        session_id: SessionId;
+        model?: Model;
+        replay_state?: ReplayState;
+        intent?: Intent;
+        project_id?: ProjectId;
+        project_name?: ProjectName;
+        [k: string]: unknown;
+    }
+}
+export type SessionUpdatedPayload = SessionUpdatedPayloadSchema.SessionUpdatedPayload;
+export declare namespace WorkspaceFilesChangedPayloadSchema {
+    type SessionId = string;
+    type FilePath = (string | null);
+    interface WorkspaceFilesChangedPayload {
+        session_id: SessionId;
+        file_path?: FilePath;
+        [k: string]: unknown;
+    }
+}
+export type WorkspaceFilesChangedPayload = WorkspaceFilesChangedPayloadSchema.WorkspaceFilesChangedPayload;
+export declare namespace SystemErrorPayloadSchema {
+    type Message = string;
+    type SessionId = (string | null);
+    type Code = (string | number | null);
+    interface SystemErrorPayload {
+        message: Message;
+        session_id?: SessionId;
+        code?: Code;
+        detail?: Detail;
+        [k: string]: unknown;
+    }
+    interface Detail {
+        [k: string]: unknown;
+    }
+}
+export type SystemErrorPayload = SystemErrorPayloadSchema.SystemErrorPayload;
+export declare namespace SystemNotificationPayloadSchema {
+    type SessionId = (string | null);
+    type NotificationType = string;
+    type Title = string;
+    type Detail = (string | null);
+    type Status = (string | null);
+    type Metadata = ({
+        [k: string]: unknown;
+    } | null);
+    interface SystemNotificationPayload {
+        session_id?: SessionId;
+        notification_type: NotificationType;
+        title: Title;
+        detail?: Detail;
+        status?: Status;
+        metadata?: Metadata;
+        [k: string]: unknown;
+    }
+}
+export type SystemNotificationPayload = SystemNotificationPayloadSchema.SystemNotificationPayload;
+export declare namespace TurnEventsPayloadSchema {
+    type SessionId = string;
+    type Type = string;
+    type StreamSequence = (number | null);
+    type Events = RawWireEvent[];
+    interface TurnEventsPayload {
+        session_id: SessionId;
+        events: Events;
+        [k: string]: unknown;
+    }
+    interface RawWireEvent {
+        type: Type;
+        payload: Payload;
+        stream_sequence?: StreamSequence;
+        [k: string]: unknown;
+    }
+    interface Payload {
+        [k: string]: unknown;
+    }
+}
+export type TurnEventsPayload = TurnEventsPayloadSchema.TurnEventsPayload;
+export declare namespace AsrReadyPayloadSchema {
+    type RequestId = string;
+    type Provider = string;
+    interface AsrReadyPayload {
+        request_id: RequestId;
+        provider: Provider;
+        [k: string]: unknown;
+    }
+}
+export type AsrReadyPayload = AsrReadyPayloadSchema.AsrReadyPayload;
+export declare namespace AsrTextPayloadSchema {
+    type Text = string;
+    type RequestId = (string | null);
+    interface AsrTextPayload {
+        text: Text;
+        request_id?: RequestId;
+        [k: string]: unknown;
+    }
+}
+export type AsrTextPayload = AsrTextPayloadSchema.AsrTextPayload;
+export declare namespace AsrClosedPayloadSchema {
+    type RequestId = string;
+    interface AsrClosedPayload {
+        request_id: RequestId;
+        [k: string]: unknown;
+    }
+}
+export type AsrClosedPayload = AsrClosedPayloadSchema.AsrClosedPayload;
+export declare namespace AsrErrorPayloadSchema {
+    type Message = string;
+    type RequestId = (string | null);
+    interface AsrErrorPayload {
+        message: Message;
+        request_id?: RequestId;
+        [k: string]: unknown;
+    }
+}
+export type AsrErrorPayload = AsrErrorPayloadSchema.AsrErrorPayload;
+export declare namespace AgentBoardBoardTaskChangedPayloadSchema {
+    type ProjectId = number;
+    type Action = ("created" | "updated" | "deleted");
+    interface AgentBoardBoardTaskChangedPayload {
+        project_id: ProjectId;
+        action: Action;
+        task: Task;
+        [k: string]: unknown;
+    }
+    interface Task {
+        [k: string]: unknown;
+    }
+}
+export type AgentBoardBoardTaskChangedPayload = AgentBoardBoardTaskChangedPayloadSchema.AgentBoardBoardTaskChangedPayload;
+export declare namespace AgentBoardFileOpPayloadSchema {
+    type ProjectId = number;
+    type SessionId = string;
+    type ToolCallId = (string | null);
+    type Action = string;
+    type FilePath = string;
+    type Description = (string | null);
+    type ContentPreview = (string | null);
+    type FinalContent = (string | null);
+    type ContentDelta = (boolean | null);
+    type IsFinal = (boolean | null);
+    type CreatedAt = string;
+    interface AgentBoardFileOpPayload {
+        project_id: ProjectId;
+        session_id: SessionId;
+        tool_call_id?: ToolCallId;
+        action: Action;
+        file_path: FilePath;
+        description?: Description;
+        content_preview?: ContentPreview;
+        final_content?: FinalContent;
+        content_delta?: ContentDelta;
+        is_final?: IsFinal;
+        created_at: CreatedAt;
+        [k: string]: unknown;
+    }
+}
+export type AgentBoardFileOpPayload = AgentBoardFileOpPayloadSchema.AgentBoardFileOpPayload;
+export declare namespace ChatStopAckSchema {
+    type Status = string;
+    type Message = (string | null);
+    type Code = (string | number | null);
+    interface ChatStopAck {
+        status: Status;
+        message?: Message;
+        code?: Code;
+        [k: string]: unknown;
+    }
+}
+export type ChatStopAck = ChatStopAckSchema.ChatStopAck;
+export declare namespace ChatCompactAckSchema {
+    type Status = string;
+    type Message = (string | null);
+    type Code = (string | number | null);
+    interface ChatCompactAck {
+        status: Status;
+        message?: Message;
+        code?: Code;
+        [k: string]: unknown;
+    }
+}
+export type ChatCompactAck = ChatCompactAckSchema.ChatCompactAck;
+export interface ClientToServerEvents {
+    "chat:send": (payload: ChatSendPayload) => void;
+    "chat:stop": (payload: ChatStopPayload, ack: (response: ChatStopAck) => void) => void;
+    "chat:append": (payload: ChatAppendPayload) => void;
+    "chat:compact": (payload: ChatCompactPayload, ack: (response: ChatCompactAck) => void) => void;
+    "session:subscribe": (payload: SessionSubscribePayload) => void;
+    "session:subscribe_batch": (payload: SessionSubscribeBatchPayload) => void;
+    "session:unsubscribe": (payload: SessionUnsubscribePayload) => void;
+    "agent-board:project:subscribe": (payload: AgentBoardProjectSubscribePayload) => void;
+    "agent-board:project:unsubscribe": (payload: AgentBoardProjectUnsubscribePayload) => void;
+    "asr:start": (payload: unknown) => void;
+    "asr:audio": (payload: AsrAudioPayload) => void;
+    "asr:stop": (payload: unknown) => void;
+    "gis.event.analysis.request": (payload: unknown, ack: (response: unknown) => void) => void;
+}
+export interface ServerToClientEvents {
+    "chat:start": (payload: ChatStartPayload) => void;
+    "chat:end": (payload: ChatEndPayload) => void;
+    "chat:append:ack": (payload: unknown) => void;
+    "session:updated": (payload: SessionUpdatedPayload) => void;
+    "workspace:files_changed": (payload: WorkspaceFilesChangedPayload) => void;
+    "system:error": (payload: SystemErrorPayload) => void;
+    "system:notification": (payload: SystemNotificationPayload) => void;
+    "turn:events": (payload: TurnEventsPayload) => void;
+    "task:updated": (payload: unknown) => void;
+    "task:synced": (payload: unknown) => void;
+    "artifact:created": (payload: unknown) => void;
+    "artifact:updated": (payload: unknown) => void;
+    "bg:started": (payload: unknown) => void;
+    "bg:tasks_completed": (payload: unknown) => void;
+    "skills:changed": (payload: unknown) => void;
+    "session:rewind": (payload: unknown) => void;
+    "asr:ready": (payload: AsrReadyPayload) => void;
+    "asr:partial": (payload: AsrTextPayload) => void;
+    "asr:final": (payload: AsrTextPayload) => void;
+    "asr:closed": (payload: AsrClosedPayload) => void;
+    "asr:error": (payload: AsrErrorPayload) => void;
+    "replay:input_mismatch": (payload: unknown) => void;
+    "agent-board:board-task:changed": (payload: AgentBoardBoardTaskChangedPayload) => void;
+    "agent-board:file-op": (payload: AgentBoardFileOpPayload) => void;
+}

package/dist/version.d.ts

@@ -0,0 +1,45 @@
+/**
+ * SDK 与 Server 的版本握手。
+ *
+ * 本次 SDK 拆分是一次性破坏性升级：旧 agent-kit 与新 Server、新 SDK 与旧 Server
+ * 都不能工作。握手的目的不是兼容，而是把「新旧组合失配」从难以理解的运行时异常
+ * 变成一句明确的升级指引。
+ *
+ * 方向一（本文件）：SDK 在首次连接前查询 Server 版本，不匹配就拒绝连接。
+ * 方向二（Server 侧）：Server 校验请求头 X-Blade-SDK，旧客户端收到结构化错误。
+ */
+/** 本 SDK 的名称与版本，随请求头与 Socket.IO 握手一并声明。 */
+export declare const SDK_NAME = "agent-client";
+export declare const SDK_VERSION = "2.0.0";
+/** REST 请求与 Socket 握手中声明 SDK 身份的标头名。 */
+export declare const SDK_HEADER = "X-Blade-SDK";
+/** 新协议起始的 Server 版本；低于此版本的正式版 Server 只能配 agent-kit 1.1.0。 */
+export declare const MIN_SERVER_VERSION = "1.1.1";
+export interface ServerVersionInfo {
+    /** Server 自身版本号，如 "1.1.1"。 */
+    version: string;
+    /**
+     * Server 要求的最低 SDK 版本。未来再出现协议不兼容时，Server 抬高本字段即可，
+     * SDK 侧无需改判断逻辑——这是避免下一次破坏性升级再痛一遍的关键。
+     */
+    min_sdk?: string;
+}
+export declare class VersionMismatchError extends Error {
+    readonly serverVersion: string | null;
+    readonly sdkVersion: string;
+    readonly hint: string;
+    constructor(options: {
+        serverVersion: string | null;
+        hint: string;
+    });
+}
+/** 预发布/开发版（如 1.1.1-dev.3、0.0.0+local）不参与拦截，避免卡住开发环境。 */
+export declare function isPrerelease(version: string): boolean;
+/** a < b 返回负数，相等返回 0，a > b 返回正数。无法解析时返回 0。 */
+export declare function compareVersions(a: string, b: string): number;
+/**
+ * 校验 Server 版本信息。不匹配抛 VersionMismatchError，匹配则正常返回。
+ *
+ * @param info Server /api/version 的响应；null 表示该接口不存在或不可达（旧 Server）。
+ */
+export declare function assertVersionCompatible(info: ServerVersionInfo | null): void;

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@blade-hq/agent-client",
+  "version": "1.1.1",
+  "description": "Blade Agent 框架无关客户端：会话实时状态机、REST 通道、弹窗登录、页面协作。浏览器与 Node.js 通用。",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "public-api.md"
+  ],
+  "sideEffects": [
+    "**/*.css"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "arktype": "^2.1.0",
+    "socket.io-client": "^4.8.0"
+  }
+}