@tunnelbox/core 0.1.27 → 0.1.29

package/src/acp/client.ts

@@ -0,0 +1,187 @@
+/**
+ * ACP 子进程的 stdio 客户端：JSON-RPC 2.0（NDJSON，每行一条消息）。
+ *
+ * 分发：
+ *  - `method` + `id`      → 服务端请求（需应答，交 `onServerRequest`）
+ *  - `method`（无 id）    → 通知（交 `onNotification`）
+ *  - `id` + result/error  → 我方请求的响应
+ */
+import { spawn, type ChildProcess, type SpawnOptions } from "node:child_process";
+import { cmdLineFor, resolveCliBinary } from "../cli";
+import type { JsonRpcError, RequestId } from "./protocol";
+
+export interface AcpHandlers {
+  onNotification?: (method: string, params: unknown) => void;
+  onServerRequest?: (id: RequestId, method: string, params: unknown) => void;
+  onStderr?: (line: string) => void;
+  onExit?: (code: number | null, signal: string | null) => void;
+}
+
+interface Pending {
+  resolve: (v: unknown) => void;
+  reject: (e: Error) => void;
+  timer: NodeJS.Timeout | null;
+}
+
+const DEFAULT_REQUEST_TIMEOUT_MS = 30_000;
+
+export class AcpClient {
+  private child: ChildProcess | null = null;
+  private buf = "";
+  private seq = 0;
+  private pending = new Map<RequestId, Pending>();
+  private exited = false;
+
+  constructor(
+    private bin: string,
+    private args: string[] = [],
+    private handlers: AcpHandlers = {},
+    private label = "acp",
+  ) {}
+
+  get alive(): boolean {
+    return !!this.child && !this.exited;
+  }
+
+  /** 启动 ACP 子进程（stdio 传输）。 */
+  start(cwd?: string): Promise<void> {
+    return new Promise<void>((resolve, reject) => {
+      const resolved = resolveCliBinary(this.bin);
+      const opts: SpawnOptions = { cwd, env: process.env, stdio: ["pipe", "pipe", "pipe"] };
+      let child: ChildProcess;
+      try {
+        child = resolved?.viaShell
+          ? spawn(cmdLineFor(resolved.path, this.args), [], { ...opts, shell: true })
+          : spawn(resolved?.path ?? this.bin, this.args, opts);
+      } catch (e) {
+        reject(e as Error);
+        return;
+      }
+      this.child = child;
+      this.exited = false;
+
+      child.stdout?.setEncoding("utf8");
+      child.stdout?.on("data", (chunk: string) => this.onChunk(chunk));
+      child.stderr?.setEncoding("utf8");
+      child.stderr?.on("data", (chunk: string) => {
+        for (const l of chunk.split("\n")) {
+          const s = l.trim();
+          if (s) this.handlers.onStderr?.(s);
+        }
+      });
+      child.on("error", (e) => {
+        this.failAll(e as Error);
+        reject(e as Error);
+      });
+      child.on("close", (code, signal) => {
+        this.exited = true;
+        this.child = null;
+        this.failAll(new Error(`${this.label} exited (code=${code ?? "null"} signal=${signal ?? "null"})`));
+        this.handlers.onExit?.(code, signal);
+      });
+      resolve();
+    });
+  }
+
+  /**
+   * 发送请求并等待响应。`timeoutMs <= 0` 表示不设超时（如 `session/prompt` 持续整轮）。
+   */
+  request<T = unknown>(method: string, params?: unknown, timeoutMs = DEFAULT_REQUEST_TIMEOUT_MS): Promise<T> {
+    if (!this.alive) return Promise.reject(new Error(`${this.label} not running`));
+    const id = ++this.seq;
+    return new Promise<T>((resolve, reject) => {
+      const timer =
+        timeoutMs > 0
+          ? setTimeout(() => {
+              this.pending.delete(id);
+              reject(new Error(`${this.label} request timeout: ${method}`));
+            }, timeoutMs)
+          : null;
+      this.pending.set(id, { resolve: resolve as (v: unknown) => void, reject, timer });
+      this.write({ jsonrpc: "2.0", id, method, ...(params === undefined ? {} : { params }) });
+    });
+  }
+
+  /** 应答服务端请求（成功）。 */
+  respond(id: RequestId, result: unknown): void {
+    this.write({ jsonrpc: "2.0", id, result });
+  }
+
+  /** 应答服务端请求（失败）。 */
+  respondError(id: RequestId, code: number, message: string): void {
+    this.write({ jsonrpc: "2.0", id, error: { code, message } });
+  }
+
+  /** 发送通知。 */
+  notify(method: string, params?: unknown): void {
+    this.write({ jsonrpc: "2.0", method, ...(params === undefined ? {} : { params }) });
+  }
+
+  stop(): void {
+    this.exited = true;
+    this.failAll(new Error(`${this.label} client stopped`));
+    try {
+      this.child?.kill();
+    } catch {
+      /* ignore */
+    }
+    this.child = null;
+  }
+
+  private write(obj: unknown): void {
+    try {
+      this.child?.stdin?.write(JSON.stringify(obj) + "\n");
+    } catch {
+      /* ignore */
+    }
+  }
+
+  private onChunk(chunk: string): void {
+    this.buf += chunk;
+    let idx: number;
+    while ((idx = this.buf.indexOf("\n")) >= 0) {
+      const line = this.buf.slice(0, idx).trim();
+      this.buf = this.buf.slice(idx + 1);
+      if (line) this.onLine(line);
+    }
+  }
+
+  private onLine(line: string): void {
+    let msg: Record<string, unknown>;
+    try {
+      msg = JSON.parse(line) as Record<string, unknown>;
+    } catch {
+      this.handlers.onStderr?.(`non-json line: ${line.slice(0, 200)}`);
+      return;
+    }
+    const method = typeof msg.method === "string" ? msg.method : "";
+    const id = msg.id as RequestId | undefined;
+    if (method && id !== undefined) {
+      this.handlers.onServerRequest?.(id, method, msg.params);
+      return;
+    }
+    if (method) {
+      this.handlers.onNotification?.(method, msg.params);
+      return;
+    }
+    if (id === undefined) return;
+    const p = this.pending.get(id);
+    if (!p) return;
+    this.pending.delete(id);
+    if (p.timer) clearTimeout(p.timer);
+    if (msg.error) {
+      const err = msg.error as JsonRpcError["error"];
+      p.reject(new Error(`${err?.message || `${this.label} error`}${err?.code !== undefined ? ` (${err.code})` : ""}`));
+    } else {
+      p.resolve(msg.result);
+    }
+  }
+
+  private failAll(e: Error): void {
+    for (const p of this.pending.values()) {
+      if (p.timer) clearTimeout(p.timer);
+      p.reject(e);
+    }
+    this.pending.clear();
+  }
+}

package/src/acp/index.ts

@@ -0,0 +1,11 @@
+/**
+ * @tunnelbox/core —— ACP（Agent Client Protocol）共享层。
+ * 供各 ACP 适配器（cursor/codebuddy/kimi/trae…）复用：协议类型、stdio 客户端、
+ * 常驻进程监督器、session/update 映射、权限选择辅助、会话镜像工厂。
+ */
+export * from "./protocol";
+export * from "./client";
+export * from "./map";
+export * from "./supervisor";
+export * from "./permissions";
+export * from "./mirror";

package/src/acp/map.ts

@@ -0,0 +1,45 @@
+/**
+ * ACP `session/update` → tunnelbox 协议（`Part` / `ChatMessage`）的映射辅助。
+ */
+import type { ChatMessage, Part } from "../types";
+import type { ContentBlock, PlanEntry, ToolCall } from "./protocol";
+
+/** 取 content block 的文本（仅 text 块）。 */
+export function textOf(content: ContentBlock | undefined): string {
+  if (content && typeof content === "object" && (content as { type?: string }).type === "text") {
+    return String((content as { text?: unknown }).text ?? "");
+  }
+  return "";
+}
+
+export function safeJson(v: unknown): string {
+  if (v === undefined || v === null) return "";
+  try {
+    return typeof v === "string" ? v : JSON.stringify(v, null, 2);
+  } catch {
+    return String(v);
+  }
+}
+
+/** 工具调用 → `Part`（messageID/part.id 均用 toolCallId，保证同一工具卡的流式更新归并）。 */
+export function toolPart(tc: ToolCall, complete: boolean): Part {
+  const name = tc.title || tc.kind || "tool";
+  return { id: tc.toolCallId, type: "tool", tool: name, args: safeJson(tc.rawInput), complete };
+}
+
+/** plan 条目 → 可读文本（用于 text 部件展示）。 */
+export function planText(entries: PlanEntry[] | undefined): string {
+  if (!Array.isArray(entries)) return "";
+  return entries
+    .map((e) => {
+      const mark = e.status === "completed" ? "x" : e.status === "in_progress" ? "~" : " ";
+      return `- [${mark}] ${e.content ?? ""}`.trim();
+    })
+    .filter(Boolean)
+    .join("\n");
+}
+
+/** 由 ACP 会话事件拼出的历史消息（本地镜像兜底时用）。 */
+export function partMessage(id: string, role: "user" | "assistant", part: Part, created = Date.now()): ChatMessage {
+  return { id, role, parts: [part], created };
+}

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