@tunnelbox/core 0.1.27 → 0.1.29

package/src/acp/protocol.ts

@@ -0,0 +1,282 @@
+/**
+ * Agent Client Protocol (ACP) v1 的最小通用类型（JSON-RPC 2.0，NDJSON 帧）。
+ *
+ * 权威定义见 https://agentclientprotocol.com/ 。各 ACP 适配器（cursor/codebuddy/kimi/trae…）
+ * 复用本模块；只声明用到的子集，解析保持宽容。适配器专有扩展（如 Cursor 的 `cursor/*`）
+ * 由各适配器自行声明。
+ */
+
+export type RequestId = string | number;
+
+// ---- JSON-RPC 2.0 信封 ----
+
+export interface JsonRpcRequest {
+  jsonrpc: "2.0";
+  id: RequestId;
+  method: string;
+  params?: unknown;
+}
+export interface JsonRpcNotification {
+  jsonrpc: "2.0";
+  method: string;
+  params?: unknown;
+}
+export interface JsonRpcResponse {
+  jsonrpc: "2.0";
+  id: RequestId;
+  result: unknown;
+}
+export interface JsonRpcError {
+  jsonrpc: "2.0";
+  id: RequestId;
+  error: { code: number; message: string; data?: unknown };
+}
+
+// ---- Content ----
+
+export type ContentBlock =
+  | { type: "text"; text: string }
+  | { type: "image"; data: string; mimeType: string; uri?: string }
+  | { type: "audio"; data: string; mimeType: string }
+  | { type: "resource_link"; uri: string; name: string; mimeType?: string; title?: string; description?: string; size?: number }
+  | { type: "resource"; resource: { uri: string; text?: string; blob?: string; mimeType?: string } };
+
+// ---- initialize / authenticate ----
+
+export interface ClientCapabilities {
+  fs?: { readTextFile?: boolean; writeTextFile?: boolean };
+  terminal?: boolean;
+  /** 声明 `form` 后支持 elicitation 的 agent 才会下发 `elicitation/create` */
+  elicitation?: { form?: unknown; url?: unknown };
+  /** 部分 agent（CodeBuddy 等）用于把 AskUserQuestion 委派给客户端的扩展能力位 */
+  askUserQuestion?: boolean;
+}
+
+export interface InitializeParams {
+  protocolVersion: number;
+  clientCapabilities?: ClientCapabilities;
+  clientInfo?: { name: string; title?: string; version: string };
+}
+
+export interface AgentCapabilities {
+  loadSession?: boolean;
+  promptCapabilities?: { image?: boolean; audio?: boolean; embeddedContext?: boolean };
+  mcpCapabilities?: { http?: boolean; sse?: boolean };
+  /** CodeBuddy 扩展：multitaskSupport 等 */
+  multitaskSupport?: boolean;
+  sessionCapabilities?: {
+    list?: unknown;
+    resume?: unknown;
+    close?: unknown;
+    delete?: unknown;
+    fork?: unknown;
+    additionalDirectories?: unknown;
+  };
+}
+
+export interface AuthMethod {
+  id: string;
+  name?: string;
+  description?: string;
+  type?: string;
+}
+
+export interface InitializeResult {
+  protocolVersion: number;
+  agentCapabilities?: AgentCapabilities;
+  agentInfo?: { name?: string; title?: string; version?: string };
+  authMethods?: AuthMethod[];
+}
+
+export interface AuthenticateParams {
+  methodId: string;
+}
+export interface AuthenticateResult {
+  _meta?: Record<string, unknown>;
+}
+
+// ---- 会话 ----
+
+export interface SessionMode {
+  id: string;
+  name: string;
+  description?: string;
+}
+export interface SessionModeState {
+  currentModeId: string;
+  availableModes: SessionMode[];
+}
+
+/** `session/new|load|resume` 返回的会话级配置项（mode/model/context_window/multitask…）。 */
+export interface SessionConfigOption {
+  id: string;
+  name?: string;
+  type?: string;
+  description?: string;
+  currentValue?: unknown;
+  options?: { value: string; name?: string; description?: string }[];
+}
+
+export interface SessionNewParams {
+  cwd: string;
+  mcpServers?: unknown[];
+  additionalDirectories?: string[];
+}
+export interface SessionNewResult {
+  sessionId: string;
+  modes?: SessionModeState;
+  configOptions?: SessionConfigOption[];
+}
+
+export interface SessionLoadParams {
+  sessionId: string;
+  cwd: string;
+  mcpServers?: unknown[];
+}
+export interface SessionResumeParams {
+  sessionId: string;
+  cwd: string;
+  mcpServers?: unknown[];
+}
+
+export interface SessionPromptParams {
+  sessionId: string;
+  prompt: ContentBlock[];
+  /** 可选：本轮 conversationRequestId（部分 agent 支持） */
+  _meta?: Record<string, unknown>;
+}
+export type StopReason = "end_turn" | "max_tokens" | "max_turn_requests" | "refusal" | "cancelled" | string;
+export interface SessionPromptResult {
+  stopReason: StopReason;
+}
+
+export interface SessionSetModeParams {
+  sessionId: string;
+  modeId: string;
+}
+export interface SessionSetConfigOptionParams {
+  sessionId: string;
+  configId: string;
+  value: unknown;
+  type?: string;
+}
+export interface SessionCancelParams {
+  sessionId: string;
+}
+export interface SessionDeleteParams {
+  sessionId: string;
+}
+
+// ---- session/update ----
+
+export type ToolKind =
+  | "read"
+  | "edit"
+  | "delete"
+  | "move"
+  | "search"
+  | "execute"
+  | "think"
+  | "fetch"
+  | "switch_mode"
+  | "other";
+export type ToolCallStatus = "pending" | "in_progress" | "completed" | "failed";
+
+export interface ToolCall {
+  toolCallId: string;
+  title?: string;
+  kind?: ToolKind;
+  status?: ToolCallStatus;
+  content?: unknown[];
+  locations?: unknown[];
+  rawInput?: unknown;
+  rawOutput?: unknown;
+}
+
+export interface PlanEntry {
+  content?: string;
+  priority?: string;
+  status?: string;
+}
+
+export type SessionUpdate =
+  | { sessionUpdate: "user_message_chunk"; messageId?: string; content?: ContentBlock }
+  | { sessionUpdate: "agent_message_chunk"; messageId?: string; content?: ContentBlock }
+  | { sessionUpdate: "agent_thought_chunk"; messageId?: string; content?: ContentBlock }
+  | ({ sessionUpdate: "tool_call" } & ToolCall)
+  | ({ sessionUpdate: "tool_call_update" } & Partial<ToolCall>)
+  | { sessionUpdate: "plan"; entries?: PlanEntry[] }
+  | { sessionUpdate: "available_commands_update"; availableCommands?: { name: string; description?: string }[] }
+  | { sessionUpdate: "current_mode_update"; modeId?: string }
+  | { sessionUpdate: "config_option_update"; configOptions?: SessionConfigOption[] }
+  | { sessionUpdate: "usage_update"; used?: number; size?: number; cost?: unknown }
+  | { sessionUpdate: "session_info_update"; title?: string; _meta?: Record<string, unknown> }
+  | { sessionUpdate: string; [k: string]: unknown };
+
+export interface SessionUpdateNotification {
+  sessionId: string;
+  update: SessionUpdate;
+}
+
+// ---- session/request_permission ----
+
+/** ACP 标准 kind；各 agent 可能扩展 `allow_session` 等，故用宽松字符串。 */
+export type PermissionOptionKind = string;
+
+export interface PermissionOption {
+  optionId: string;
+  name: string;
+  kind: PermissionOptionKind;
+}
+
+export interface RequestPermissionParams {
+  sessionId?: string;
+  toolCall: ToolCall;
+  options: PermissionOption[];
+}
+
+export type RequestPermissionOutcome = { outcome: "selected"; optionId: string } | { outcome: "cancelled" };
+export interface RequestPermissionResult {
+  outcome: RequestPermissionOutcome;
+}
+
+// ---- elicitation/create（agent → client 请求，需应答） ----
+
+export interface ElicitationMeta {
+  [k: string]: unknown;
+}
+
+export interface ElicitationPropertySchema {
+  type?: string;
+  title?: string;
+  description?: string;
+  enum?: unknown[];
+  enumNames?: unknown[];
+  items?: unknown;
+}
+
+export interface ElicitationRequestedSchema {
+  type?: string;
+  properties?: Record<string, ElicitationPropertySchema>;
+  required?: string[];
+}
+
+export interface ElicitationCreateParams {
+  sessionId?: string;
+  toolCallId?: string;
+  mode?: string;
+  message?: string;
+  requestedSchema?: ElicitationRequestedSchema;
+  _meta?: ElicitationMeta;
+}
+
+export type ElicitationCreateResult =
+  | { action: "accept"; content?: Record<string, unknown>; _meta?: Record<string, unknown> }
+  | { action: "decline"; _meta?: Record<string, unknown> }
+  | { action: "cancel"; _meta?: Record<string, unknown> };
+
+/** `elicitation/complete`（agent → client 通知）：撤卡，按 elicitationId 关联。 */
+export interface ElicitationCompleteParams {
+  elicitationId?: string;
+  _meta?: ElicitationMeta;
+}

package/src/acp/supervisor.ts

@@ -0,0 +1,158 @@
+/**
+ * ACP 常驻子进程的生命周期管理：按需启动、`initialize` + 可选 `authenticate` 握手、
+ * 退出后清空句柄（下次请求自动重启并重新握手）。
+ *
+ * 全程只维护一个连接（stdio 单客户端）；会话恢复由各适配器用 `session/load`（或 `session/resume`）完成。
+ * 由各 ACP 适配器（cursor/codebuddy/kimi/trae…）复用；spawn 参数、clientInfo、能力位、认证策略由适配器注入。
+ */
+import { AcpClient, type AcpHandlers } from "./client";
+import type {
+  AgentCapabilities,
+  AuthMethod,
+  AuthenticateResult,
+  ClientCapabilities,
+  InitializeParams,
+  InitializeResult,
+} from "./protocol";
+
+const PROTOCOL_VERSION = 1;
+
+export interface AcpSupervisorConfig {
+  /** ACP CLI 可执行名/路径 */
+  bin: string;
+  /** bin 之后的完整参数（如 `["--acp"]` 或 `["acp","serve"]`） */
+  args: string[];
+  /** 子进程 cwd */
+  cwd?: string;
+  /** 错误/日志标签（如 `codebuddy acp`） */
+  label: string;
+  /** initialize.clientInfo */
+  clientInfo: { name: string; title?: string; version: string };
+  /** initialize.clientCapabilities（缺省：不代理 fs/terminal、声明 elicitation.form） */
+  clientCapabilities?: ClientCapabilities;
+  /**
+   * 可选：ACP `authenticate` 的 methodId。缺省不调用（用于交互式登录的 agent）；
+   * 非交互的 agent（如 Kimi 的 `login`）可传入以探测登录态。
+   */
+  authMethod?: string;
+  /** 未配置 authMethod 时回调（由适配器输出本地化提示） */
+  onAuthSkipped?: () => void;
+  /** authenticate 结果回调（成功/失败） */
+  onAuthResult?: (r: { ok: boolean; result?: AuthenticateResult; error?: string }) => void;
+  /** 日志（已本地化） */
+  log: (msg: string) => void;
+  /** 子进程退出回调（供适配器做 fail-closed 处理） */
+  onExit?: (code: number | null, signal: string | null) => void;
+}
+
+export class AcpSupervisor {
+  private client: AcpClient | null = null;
+  private starting: Promise<AcpClient> | null = null;
+  private caps: AgentCapabilities = {};
+  private auth: AuthenticateResult | null = null;
+
+  /** 由适配器注入：通知 / 服务端请求处理。 */
+  onNotification: (method: string, params: unknown) => void = () => {};
+  onServerRequest: (id: string | number, method: string, params: unknown) => void = () => {};
+
+  constructor(private cfg: AcpSupervisorConfig) {}
+
+  get running(): boolean {
+    return !!this.client?.alive;
+  }
+
+  /** 当前客户端（不触发启动）；用于应答来自该连接的服务端请求。 */
+  get current(): AcpClient | null {
+    return this.client?.alive ? this.client : null;
+  }
+
+  /** initialize 协商得到的 agent 能力位（loadSession / sessionCapabilities 等）。 */
+  get capabilities(): AgentCapabilities {
+    return this.caps;
+  }
+
+  /** `authenticate` 返回结果（未认证/未调用时为 null）。 */
+  get authResult(): AuthenticateResult | null {
+    return this.auth;
+  }
+
+  /** 取得可用客户端（必要时启动并握手）。 */
+  async ensure(): Promise<AcpClient> {
+    if (this.client?.alive) return this.client;
+    if (!this.starting) {
+      this.starting = this.launch().finally(() => {
+        this.starting = null;
+      });
+    }
+    return this.starting;
+  }
+
+  stop(): void {
+    this.client?.stop();
+    this.client = null;
+    this.caps = {};
+    this.auth = null;
+  }
+
+  private async launch(): Promise<AcpClient> {
+    const handlers: AcpHandlers = {
+      onNotification: (method, params) => this.onNotification(method, params),
+      onServerRequest: (id, method, params) => this.onServerRequest(id, method, params),
+      onStderr: (line) => {
+        if (/\b(error|failed|panic|denied|unauthorized|auth|login|mcp|tunnelbox)\b/i.test(line)) {
+          this.cfg.log(`acp: ${line.slice(0, 300)}`);
+        }
+      },
+      onExit: (code, signal) => {
+        this.client = null;
+        this.caps = {};
+        this.auth = null;
+        this.cfg.log(`${this.cfg.label} exited (code=${code ?? "null"} signal=${signal ?? "null"})`);
+        this.cfg.onExit?.(code, signal);
+      },
+    };
+    const client = new AcpClient(this.cfg.bin, this.cfg.args, handlers, this.cfg.label);
+    await client.start(this.cfg.cwd);
+    const params: InitializeParams = {
+      protocolVersion: PROTOCOL_VERSION,
+      clientCapabilities: this.cfg.clientCapabilities ?? {
+        // 不代理文件/终端工具（适配器只做远程 UI；工具在本机执行）
+        fs: { readTextFile: false, writeTextFile: false },
+        terminal: false,
+        // 声明 form 后支持 elicitation 的 agent 才会下发 elicitation/create
+        elicitation: { form: {} },
+      },
+      clientInfo: this.cfg.clientInfo,
+    };
+    const res = await client.request<InitializeResult>("initialize", params, 20_000);
+    this.caps = res?.agentCapabilities ?? {};
+    await this.authenticate(client, res?.authMethods);
+    this.client = client;
+    return client;
+  }
+
+  /**
+   * 完成登录握手。仅当配置了 `authMethod` 时调用（交互式登录的 agent 应缺省不调用，避免挂起/弹登录）；
+   * 非交互的 agent（如 Kimi `login`）可传入以探测登录态，失败不阻断启动。
+   */
+  private async authenticate(client: AcpClient, methods: AuthMethod[] | undefined): Promise<void> {
+    const wanted = (this.cfg.authMethod || "").trim();
+    if (!wanted) {
+      this.cfg.onAuthSkipped?.();
+      return;
+    }
+    const list = Array.isArray(methods) ? methods : [];
+    const preferred = list.find((m) => m.id === wanted) ?? list[0];
+    if (!preferred) {
+      this.cfg.onAuthResult?.({ ok: false, error: "no auth methods" });
+      return;
+    }
+    try {
+      const r = await client.request<AuthenticateResult>("authenticate", { methodId: preferred.id }, 120_000);
+      this.auth = r ?? {};
+      this.cfg.onAuthResult?.({ ok: true, result: r ?? {} });
+    } catch (e) {
+      this.cfg.onAuthResult?.({ ok: false, error: (e as Error).message });
+    }
+  }
+}

package/src/index.ts

@@ -1,6 +1,6 @@
 /**
  * @tunnelbox/core —— 共享核心。
- * 供各智能体适配器（opencode 插件 / dsh / claude-code / codex / …）复用：
+ * 供各智能体适配器（opencode 插件 / dsh / claude-code / codex / cursor / codebuddy / kimi / trae / …）复用：
  * 统一协议类型、中继客户端（静默重连）、状态持久化、二维码配对。
  */
 export * from "./types";
@@ -12,3 +12,4 @@ export * from "./i18n";
 export * from "./messages";
 export * from "./cli";
 export * from "./terminal";
+export * from "./acp";

package/src/types.ts

@@ -23,7 +23,7 @@ export interface AgentInfo {
   version: string;
   platform?: string;
   directory?: string;
-  /** 智能体类型：opencode | claude-code | codex | dsh | openclaw | hermes | cursor */
+  /** 智能体类型：opencode | claude-code | codex | dsh | openclaw | hermes | cursor | codebuddy | kimi | trae */
   type?: string;
   /** IANA 时区名（如 Asia/Shanghai），仅用于"电脑本地时间"展示 */
   timezone?: string;
@@ -104,6 +104,12 @@ export interface PermissionRequest {
   kind?: PermissionKind;
   /** choice 类型的可选项（显示为按钮列表） */
   options?: string[];
+  /**
+   * 宿主允许的"允许"作用域（缺省=全部：once/session/always）。
+   * 手机端据此渲染允许按钮，避免提供宿主会拒绝的作用域
+   * （如 OpenClaw exec 的 `unavailableDecisions:["allow-always"]`）。
+   */
+  allowed?: PermissionScope[];
 }
 
 /** 手机端对权限请求的应答（permission.reply）。status=allow 时可携带 scope 表达允许作用域。 */