@tunnelbox/core 0.1.27 → 0.1.28

package/src/acp/mirror.ts

@@ -0,0 +1,210 @@
+/**
+ * 会话本地镜像存储工厂（各 ACP 适配器共享）。
+ *
+ * 会话内容以适配器为权威镜像（每次流式部件/用户消息都即时落一行），
+ * 供 session.list / session.messages / session.delete 使用；模型上下文续聊依赖采集到的
+ * ACP sessionId（meta.resumeId）经 `session/load` / `session/resume` 恢复。
+ *
+ * 每个适配器传入独立根目录（如 `~/.tunnelbox/kimi-sessions`），互不干扰。
+ */
+import {
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { join } from "node:path";
+import type { ChatMessage, Part, SessionInfo } from "../types";
+
+export interface SessionMeta {
+  title: string;
+  cwd?: string;
+  resumeId?: string;
+  /** 标题是否为自动占位（新建时的本地化默认标题）：为 true 时允许首条用户文本/宿主标题覆盖 */
+  titleAuto?: boolean;
+  created: number;
+  updated: number;
+}
+
+export interface SessionMirror {
+  /** 读取会话元数据（title/cwd/resumeId 等）。 */
+  getMeta(sessionID: string): SessionMeta | null;
+  /** 生成新的稳定会话 id（UUID）。 */
+  newSessionId(): string;
+  /** 记录会话元数据变更（title/resumeId/cwd 等）。 */
+  saveMeta(sessionID: string, patch: Partial<SessionMeta>): SessionMeta;
+  /** 追加一条部件/消息（history 按 id 归并成 ChatMessage）。 */
+  appendPart(sessionID: string, msgId: string, role: "user" | "assistant", part: Part, created?: number): void;
+  /** 会话镜像是否存在。 */
+  exists(sessionID: string): boolean;
+  /** 会话列表（镜像目录），按最近更新倒序。 */
+  listSessions(): Promise<SessionInfo[]>;
+  /** 读取会话历史（按 append 行 id 归并 parts）。 */
+  readHistory(sessionID: string): Promise<ChatMessage[]>;
+  /** 删除会话目录。 */
+  removeSession(sessionID: string): Promise<void>;
+  /** 文件大小（粗略）。 */
+  dirSize(sessionID: string): number;
+}
+
+const FILE = "session.jsonl";
+const META = "meta.json";
+
+/** 创建某个根目录下的会话镜像存储。 */
+export function createSessionMirror(rootDir: string): SessionMirror {
+  const dirOf = (sessionID: string): string => join(rootDir, sessionID);
+
+  function readMeta(sessionID: string): SessionMeta | null {
+    try {
+      const p = join(dirOf(sessionID), META);
+      if (existsSync(p)) return JSON.parse(readFileSync(p, "utf8")) as SessionMeta;
+    } catch {
+      /* ignore */
+    }
+    return null;
+  }
+
+  function writeMeta(sessionID: string, meta: SessionMeta): void {
+    try {
+      mkdirSync(dirOf(sessionID), { recursive: true });
+      writeFileSync(join(dirOf(sessionID), META), JSON.stringify(meta, null, 2), "utf8");
+    } catch {
+      /* ignore */
+    }
+  }
+
+  function saveMeta(sessionID: string, patch: Partial<SessionMeta>): SessionMeta {
+    const prev =
+      readMeta(sessionID) ||
+      ({ title: "", titleAuto: true, created: Date.now(), updated: Date.now() } as SessionMeta);
+    const meta = { ...prev, ...patch, updated: Date.now() };
+    writeMeta(sessionID, meta);
+    return meta;
+  }
+
+  function appendPart(sessionID: string, msgId: string, role: "user" | "assistant", part: Part, created = Date.now()): void {
+    try {
+      const d = dirOf(sessionID);
+      mkdirSync(d, { recursive: true });
+      const line = JSON.stringify({ id: msgId, role, parts: [part], created });
+      writeFileSync(join(d, FILE), line + "\n", { encoding: "utf8", flag: "a" });
+      // 首条用户文本作为标题（仅当标题仍为自动占位；与语言无关）
+      if (role === "user" && part.type === "text" && part.text) {
+        const meta = readMeta(sessionID);
+        if (!meta || meta.titleAuto) {
+          const t = part.text.trim();
+          saveMeta(sessionID, { title: t.length > 30 ? `${t.slice(0, 30)}…` : t, titleAuto: false });
+        }
+      }
+      saveMeta(sessionID, {});
+    } catch {
+      /* ignore */
+    }
+  }
+
+  function exists(sessionID: string): boolean {
+    return existsSync(join(dirOf(sessionID), FILE));
+  }
+
+  function walkDirs(): string[] {
+    try {
+      return readdirSync(rootDir).filter((n) => existsSync(join(rootDir, n, FILE)));
+    } catch {
+      return [];
+    }
+  }
+
+  async function listSessions(): Promise<SessionInfo[]> {
+    const out: SessionInfo[] = [];
+    for (const id of walkDirs()) {
+      const meta = readMeta(id);
+      if (!meta) continue;
+      out.push({ id, title: meta.title, created: meta.created, updated: meta.updated, status: "idle", workspace: meta.cwd });
+    }
+    return out.sort((a, b) => b.updated - a.updated);
+  }
+
+  async function readHistory(sessionID: string): Promise<ChatMessage[]> {
+    let lines: string[];
+    try {
+      lines = readFileSync(join(dirOf(sessionID), FILE), "utf8").split("\n");
+    } catch {
+      return [];
+    }
+    const byId = new Map<string, ChatMessage>();
+    const order: string[] = [];
+    for (const line of lines) {
+      const s = line.trim();
+      if (!s) continue;
+      try {
+        const o = JSON.parse(s) as { id: string; role: "user" | "assistant"; parts: Part[]; created: number };
+        if (!o.id || !Array.isArray(o.parts)) continue;
+        const hit = byId.get(o.id);
+        if (hit) {
+          hit.parts.push(...o.parts);
+        } else {
+          order.push(o.id);
+          byId.set(o.id, { id: o.id, role: o.role, parts: [...o.parts], created: o.created ?? Date.now() });
+        }
+      } catch {
+        /* ignore */
+      }
+    }
+    return order.map((id) => byId.get(id)!).filter((m) => m.parts.length).map((m) => ({ ...m, parts: mergeParts(m.parts) }));
+  }
+
+  async function removeSession(sessionID: string): Promise<void> {
+    try {
+      rmSync(dirOf(sessionID), { recursive: true, force: true });
+    } catch {
+      /* ignore */
+    }
+  }
+
+  function dirSize(sessionID: string): number {
+    try {
+      const st = statSync(join(dirOf(sessionID), FILE));
+      return st.size;
+    } catch {
+      return 0;
+    }
+  }
+
+  return {
+    getMeta: readMeta,
+    newSessionId,
+    saveMeta,
+    appendPart,
+    exists,
+    listSessions,
+    readHistory,
+    removeSession,
+    dirSize,
+  };
+}
+
+/** 生成新的稳定会话 id（UUID）。 */
+export function newSessionId(): string {
+  if (typeof globalThis.crypto?.randomUUID === "function") return globalThis.crypto.randomUUID();
+  return `s-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+}
+
+/** 归并同一部件 id 的流式增量：delta 追加、text 替换（与手机端 mergePart 语义一致）。 */
+function mergeParts(parts: Part[]): Part[] {
+  const byId = new Map<string, Part>();
+  const order: string[] = [];
+  for (const p of parts) {
+    const cur = byId.get(p.id);
+    if (!cur) {
+      order.push(p.id);
+      byId.set(p.id, { ...p });
+      continue;
+    }
+    const text = p.delta != null ? (cur.text || "") + p.delta : p.text != null ? p.text : cur.text;
+    byId.set(p.id, { ...cur, ...p, text });
+  }
+  return order.map((id) => byId.get(id)!);
+}

package/src/acp/permissions.ts

@@ -0,0 +1,47 @@
+/**
+ * ACP 权限/选择应答辅助（各 ACP 适配器共享）。
+ */
+import type { PermissionScope } from "../types";
+import type { PermissionOption } from "./protocol";
+
+/** ACP 标准审批 kind（其余视为选项型 → 选择卡）。 */
+export const STANDARD_PERMISSION_KINDS: ReadonlySet<string> = new Set([
+  "allow_once",
+  "allow_always",
+  "allow_session",
+  "reject_once",
+  "reject_always",
+]);
+
+/**
+ * 是否为「选项型」权限请求（应渲染为选择卡而非审批卡）：
+ * 存在非标准 kind，或出现多个 `allow_once`（如 AskUserQuestion 的选项列表）。
+ */
+export function isChoiceOptions(options: PermissionOption[]): boolean {
+  if (!options.length) return false;
+  const allowOnceCount = options.filter((o) => o.kind === "allow_once").length;
+  return options.some((o) => !STANDARD_PERMISSION_KINDS.has(o.kind)) || allowOnceCount > 1;
+}
+
+/** 依 ACP 选项 kind 选择与手机作答最匹配的 optionId（无匹配则退化为同类，最后退化为首项）。 */
+export function chooseOption(
+  options: PermissionOption[],
+  status: "allow" | "deny",
+  scope: PermissionScope,
+): PermissionOption | undefined {
+  if (!options.length) return undefined;
+  const prefer =
+    status === "deny"
+      ? scope === "always"
+        ? "reject_always"
+        : "reject_once"
+      : scope === "once"
+        ? "allow_once"
+        : scope === "session"
+          ? "allow_session"
+          : "allow_always";
+  const exact = options.find((o) => o.kind === prefer);
+  if (exact) return exact;
+  const prefix = status === "deny" ? "reject" : "allow";
+  return options.find((o) => String(o.kind ?? "").startsWith(prefix)) ?? options[0];
+}

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 });
+    }
+  }
+}