@chenacc/agentbridge 0.0.0-stage → 0.1.1

package/src/adapters/dsh-desktop.js

@@ -0,0 +1,322 @@
+import { randomUUID } from "node:crypto";
+
+const MAX_QUESTIONS = 10;
+const MAX_OPTIONS = 25;
+
+function contentText(content) {
+  if (!Array.isArray(content)) return "";
+  return content
+    .filter((block) => block?.type === "text" || block?.type === "reasoning")
+    .map((block) => String(block.text ?? ""))
+    .join("");
+}
+
+function turnId(providerSessionId, turn) {
+  return `${providerSessionId}:${turn}`;
+}
+
+function text(value, limit) {
+  return typeof value === "string" ? value.slice(0, limit) : "";
+}
+
+/**
+ * Project DSH's `AskUserQuestionRequest` questions onto the phone's wire shape.
+ *
+ * The phone renders these directly, so every field is length-capped and rebuilt
+ * as a plain object: the request arrives from another process and must never be
+ * forwarded as an opaque live value.
+ */
+export function normalizeQuestions(value) {
+  if (!Array.isArray(value)) return [];
+  return value.slice(0, MAX_QUESTIONS).flatMap((question, index) => {
+    if (!question || typeof question !== "object") return [];
+    const questionText = text(question.question, 4_000);
+    if (!questionText) return [];
+    const options = Array.isArray(question.options)
+      ? question.options.slice(0, MAX_OPTIONS).flatMap((option) => {
+        const label = text(option?.label, 200);
+        if (!label) return [];
+        const description = text(option?.description, 500);
+        return [{ label, ...(description ? { description } : {}) }];
+      })
+      : [];
+    const header = text(question.header, 200);
+    return [{
+      id: text(question.id, 100) || `q${index + 1}`,
+      question: questionText,
+      ...(header ? { header } : {}),
+      ...(options.length ? { options } : {}),
+      ...(question.multiSelect === true ? { multiSelect: true } : {}),
+    }];
+  });
+}
+
+export async function dshEventToBridge(record, state, emit) {
+  const { event, origin } = record;
+  const data = event.data ?? {};
+  const extra = Number.isSafeInteger(data.turn) ? { turnId: turnId(state.providerSessionId, data.turn) } : {};
+
+  switch (event.type) {
+    case "turn/start":
+      return emit("turn.started", {
+        adapter: "deepseek-harness-desktop",
+        provider: state.provider,
+        model: state.model,
+        dshEventSeq: event.seq,
+      }, extra);
+    case "assistant/chunk":
+      if (data.chunk?.type === "text-delta" && data.chunk.text) {
+        return emit("message.delta", { role: "assistant", text: data.chunk.text, dshEventSeq: event.seq }, extra);
+      }
+      if (data.chunk?.type === "reasoning-delta" && data.chunk.text) {
+        return emit("adapter.output", { stream: "reasoning", text: data.chunk.text, dshEventSeq: event.seq }, extra);
+      }
+      return undefined;
+    case "assistant/message":
+      return emit("message.completed", {
+        role: "assistant",
+        text: contentText(data.message?.content),
+        provider: data.message?.source?.provider ?? state.provider,
+        model: data.message?.source?.model ?? state.model,
+        usage: data.usage,
+        dshEventSeq: event.seq,
+      }, extra);
+    case "user/message":
+      if (origin === "phone") return undefined;
+      return emit("message.completed", {
+        role: "user",
+        text: contentText(data.content),
+        source: "dsh-desktop",
+        dshEventSeq: event.seq,
+      }, extra);
+    case "tool/call":
+      return emit("tool.started", {
+        type: data.name,
+        command: data.arguments,
+        callId: data.callId,
+        dshEventSeq: event.seq,
+      }, extra);
+    case "tool/result":
+      return emit("tool.completed", {
+        type: data.message?.content?.[0]?.toolCallId ? "tool-result" : "tool",
+        callId: data.message?.content?.[0]?.toolCallId,
+        text: contentText(data.message?.content?.[0]?.content),
+        status: data.message?.content?.[0]?.isError || data.error ? "error" : "completed",
+        error: data.error,
+        dshEventSeq: event.seq,
+      }, extra);
+    case "turn/end": {
+      const kind = data.reason?.kind;
+      if (kind === "cancelled" || kind === "interrupted") {
+        return emit("turn.cancelled", { reason: data.reason, dshEventSeq: event.seq }, extra);
+      }
+      // A turn can end in an error — a dropped model connection, a provider failure, a
+      // broken transport. This used to fall through to `turn.completed`, so a turn that
+      // produced no answer at all was reported to the phone as "本轮已完成": the person
+      // saw their message, some tool rows, "completed", and no reply, with nothing
+      // anywhere saying the run had failed.
+      if (kind === "error") {
+        const failure = data.reason?.error;
+        const message = typeof failure === "string" ? failure : failure?.message;
+        const code = typeof failure === "object" && failure ? failure.code : undefined;
+        return emit("turn.failed", {
+          ...(message ? { error: code ? `${message}（${code}）` : message } : { error: "Agent 的回合异常结束，没有产出回复" }),
+          reason: data.reason,
+          dshEventSeq: event.seq,
+        }, extra);
+      }
+      return emit("turn.completed", { reason: data.reason, dshEventSeq: event.seq }, extra);
+    }
+    default:
+      return undefined;
+  }
+}
+
+export class DshDesktopAdapter {
+  id = "deepseek-harness-desktop";
+  label = "DeepSeek Harness Desktop";
+
+  constructor({ channels }) {
+    this.channels = channels;
+  }
+
+  /**
+   * A new conversation can only be opened inside the desktop app, so `create`
+   * is true exactly while a companion is paired: the bridge asks that companion
+   * to open one, and the companion registers it back. `createReason` explains
+   * the refusal in the phone's create sheet instead of a dead greyed row.
+   */
+  get capabilities() {
+    const online = this.channels.hasOnlineChannel();
+    return {
+      create: online,
+      ...(online ? {} : { createReason: "桌面端离线" }),
+      attach: true,
+      discover: false,
+      resume: true,
+      cancel: true,
+      approve: true,
+      answer: true,
+      selectModel: true,
+      streaming: true,
+      sameConversation: true,
+    };
+  }
+
+  async detect() {
+    return {
+      available: true,
+      supported: true,
+      mode: "desktop-companion",
+      note: "Run /phone inside a DSH Desktop conversation to attach it",
+    };
+  }
+
+  async attach(context, providerSessionId) {
+    return this.#handleFor(providerSessionId, context);
+  }
+
+  /**
+   * Create a conversation *in the desktop app* and hand it to the bridge.
+   *
+   * The phone cannot start a DSH process of its own here: the conversation has to
+   * exist inside the running desktop so both surfaces share it. So this asks the
+   * paired companion to open one and waits for it to register, then wires the
+   * usual bridge observability onto the new provider session.
+   */
+  async start(context) {
+    const created = await this.channels.requestSession({
+      cwd: context.cwd,
+      title: context.title,
+      bridgeSessionId: context.bridgeSessionId,
+    });
+    return this.#handleFor(created.providerSessionId, context);
+  }
+
+  #handleFor(providerSessionId, context) {
+    const handle = {
+      providerSessionId,
+      emit: context.emit,
+      // Pending human interactions, keyed by the id AgentBridge hands the phone
+      // and carrying the DSH rpc id that answers them. Kept on the runtime
+      // handle rather than persisted: a question dies with its turn.
+      inputs: new Map(),
+      approvals: new Map(),
+    };
+    this.channels.attachBridge(providerSessionId, {
+      onEvent: (record, state) => dshEventToBridge(record, state, context.emit),
+      onInteraction: (interaction) => this.#onInteraction(handle, interaction),
+    });
+    return handle;
+  }
+
+  async send(handle, { text: prompt, attachments = [], commandId }) {
+    // The companion forwards a single text frame, so attachments are handed over as
+    // absolute paths the DSH agent can read with its tools.
+    const lines = attachments.map((attachment) => `[附件] ${attachment.name} → ${attachment.path}`);
+    const composed = [prompt, ...lines].filter(Boolean).join("\n\n");
+    this.channels.enqueue(handle.providerSessionId, { kind: "message", text: composed, commandId });
+  }
+
+  async stop(handle) {
+    this.channels.enqueue(handle.providerSessionId, { kind: "cancel" });
+    return true;
+  }
+
+  // DSH Desktop asks the human in two different shapes: a question form
+  // (`ask_user_question`) and a one-off approval prompt. Both block the turn
+  // exactly like an approval does, so both must reach the phone; `selectModel`
+  // is the existing precedent for waiting on a real desktop confirmation.
+  async resolveInput(handle, requestId, { answers = [], cancel = false } = {}) {
+    const pending = handle.inputs.get(requestId);
+    if (!pending) throw Object.assign(new Error("This question is missing or already answered"), { statusCode: 409 });
+    handle.inputs.delete(requestId);
+    await this.channels.request(handle.providerSessionId, cancel
+      ? { kind: "cancel-question", rpcId: pending.rpcId }
+      : { kind: "answer-question", rpcId: pending.rpcId, answers });
+    return true;
+  }
+
+  async resolveApproval(handle, approvalId, decision) {
+    const pending = handle.approvals.get(approvalId);
+    if (!pending) throw Object.assign(new Error("Approval is missing or already resolved"), { statusCode: 409 });
+    handle.approvals.delete(approvalId);
+    await this.channels.request(handle.providerSessionId, {
+      kind: "answer-approval",
+      rpcId: pending.rpcId,
+      dshApprovalId: pending.dshApprovalId,
+      outcome: decision === "approve" ? "allowed-once" : "rejected",
+    });
+    return true;
+  }
+
+  modelDirectory(handle) {
+    return this.channels.metadata(handle.providerSessionId)?.modelDirectory ?? null;
+  }
+
+  async selectModel(handle, selection) {
+    const directory = this.modelDirectory(handle);
+    const provider = directory?.groups.find((group) => group.id === selection.provider);
+    const target = provider?.models.find((model) => model.id === selection.model);
+    if (!target) throw Object.assign(new Error("The selected model is not in the current DSH Desktop model directory"), { statusCode: 403 });
+    if (selection.reasoningEffort && !target.reasoning?.efforts.some((effort) => effort.id === selection.reasoningEffort)) {
+      throw Object.assign(new Error("The selected reasoning effort is not available for this model"), { statusCode: 400 });
+    }
+    return this.channels.request(handle.providerSessionId, { kind: "select-model", selection });
+  }
+
+  #onInteraction(handle, interaction) {
+    const emit = handle.emit;
+    if (!emit || !interaction) return;
+    if (interaction.kind === "question-requested") {
+      const questions = normalizeQuestions(interaction.questions);
+      if (!questions.length) return;
+      const requestId = randomUUID();
+      handle.inputs.set(requestId, { rpcId: interaction.requestId });
+      void emit("input.requested", {
+        requestId,
+        adapter: this.id,
+        questions,
+        expiresAt: Date.now() + 30 * 60_000,
+      });
+      return;
+    }
+    if (interaction.kind === "approval-requested") {
+      const approvalId = randomUUID();
+      const toolName = text(interaction.toolName, 200) || "tool";
+      const reason = text(interaction.reason, 2_000);
+      const callId = text(interaction.callId, 200);
+      handle.approvals.set(approvalId, { rpcId: interaction.requestId, dshApprovalId: text(interaction.dshApprovalId, 200) });
+      void emit("approval.requested", {
+        approvalId,
+        adapter: this.id,
+        method: toolName,
+        request: { toolName, ...(reason ? { reason } : {}), ...(callId ? { callId } : {}) },
+        expiresAt: Date.now() + 30 * 60_000,
+      });
+      return;
+    }
+    // The desktop window answered first: retire the phone's now-stale card
+    // instead of leaving a button that can only fail.
+    if (interaction.kind === "question-resolved") {
+      for (const [requestId, pending] of handle.inputs) {
+        if (pending.rpcId !== interaction.requestId) continue;
+        handle.inputs.delete(requestId);
+        void emit("input.resolved", { requestId, outcome: "desktop" });
+        return;
+      }
+      return;
+    }
+    if (interaction.kind === "approval-resolved") {
+      for (const [approvalId, pending] of handle.approvals) {
+        if (pending.dshApprovalId !== interaction.dshApprovalId) continue;
+        handle.approvals.delete(approvalId);
+        void emit("approval.resolved", {
+          approvalId,
+          decision: interaction.outcome === "allowed-once" ? "approve" : "deny",
+        });
+        return;
+      }
+    }
+  }
+}

package/src/adapters/echo.js

@@ -0,0 +1,57 @@
+import { randomUUID } from "node:crypto";
+
+export class EchoAdapter {
+  id = "echo";
+  label = "Echo Demo";
+  capabilities = {
+    create: true,
+    attach: false,
+    discover: false,
+    streaming: true,
+    approve: false,
+    resume: false,
+    cancel: true,
+    selectModel: false,
+    realAgent: false,
+  };
+  #runs = new Map();
+
+  async detect() {
+    return { available: true, version: "built-in" };
+  }
+
+  async start(context) {
+    return { providerSessionId: randomUUID(), context };
+  }
+
+  async send(handle, { text, emit }) {
+    const turnId = randomUUID();
+    const controller = new AbortController();
+    this.#runs.set(handle.providerSessionId, controller);
+    await emit("turn.started", { adapter: this.id }, { turnId });
+    await emit("message.started", { role: "assistant" }, { turnId });
+
+    const response = `已收到：${text}\n\n这是 Echo 适配器，用于验证微信扫码、实时同步和断线补拉。`;
+    for (const chunk of response.match(/.{1,5}/gs) ?? []) {
+      if (controller.signal.aborted) {
+        await emit("turn.cancelled", { reason: "user" }, { turnId });
+        this.#runs.delete(handle.providerSessionId);
+        return;
+      }
+      await new Promise((resolve) => setTimeout(resolve, 45));
+      await emit("message.delta", { role: "assistant", text: chunk }, { turnId });
+    }
+
+    await emit("message.completed", { role: "assistant", text: response }, { turnId });
+    await emit("turn.completed", { status: "completed" }, { turnId });
+    this.#runs.delete(handle.providerSessionId);
+  }
+
+  async stop(handle) {
+    return this.#runs.get(handle.providerSessionId)?.abort() ?? false;
+  }
+
+  async resolveApproval() {
+    throw Object.assign(new Error("Echo has no pending approval"), { statusCode: 409 });
+  }
+}

package/src/adapters/process-utils.js

@@ -0,0 +1,125 @@
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+// Codex App Server requires HOME even on Windows, where desktop-launched
+// processes commonly inherit only USERPROFILE.
+export function withHomeEnvironment(env = process.env, homeDirectory = os.homedir(), directoryExists = existsSync) {
+  const childEnv = { ...env };
+  if (!childEnv.HOME) childEnv.HOME = childEnv.USERPROFILE || homeDirectory;
+  if (!childEnv.USERPROFILE && childEnv.HOME) childEnv.USERPROFILE = childEnv.HOME;
+  const codexHome = childEnv.HOME ? path.join(childEnv.HOME, ".codex") : null;
+  if (!childEnv.CODEX_HOME && codexHome && directoryExists(codexHome)) childEnv.CODEX_HOME = codexHome;
+  return childEnv;
+}
+
+export function resolveCommand(name, {
+  env = process.env,
+  platform = process.platform,
+  homeDirectory = os.homedir(),
+  fileExists = existsSync,
+} = {}) {
+  if (platform !== "win32") return name;
+  const extensions = [".exe", ".com", ".ps1", ".cmd", ".bat"];
+  const pathDirectories = String(env.PATH ?? "").split(path.delimiter).filter(Boolean);
+  const userProfile = env.USERPROFILE || env.HOME || homeDirectory;
+  const appData = env.APPDATA || (userProfile ? path.join(userProfile, "AppData", "Roaming") : null);
+  const npmBin = appData ? path.join(appData, "npm") : null;
+  if (npmBin && !pathDirectories.some((directory) => directory.replace(/^"|"$/g, "").toLowerCase() === npmBin.toLowerCase())) {
+    pathDirectories.push(npmBin);
+  }
+
+  for (const directory of pathDirectories) {
+    if (!directory) continue;
+    for (const extension of extensions) {
+      const candidate = path.join(directory.replace(/^"|"$/g, ""), `${name}${extension}`);
+      if (fileExists(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+export function spawnCommand(name, args, options = {}) {
+  const resolved = resolveCommand(name);
+  if (!resolved) throw Object.assign(new Error(`Command not found: ${name}`), { code: "ENOENT" });
+  const childOptions = { ...options, env: withHomeEnvironment(options.env) };
+  if (process.platform === "win32" && resolved.toLowerCase().endsWith(".ps1")) {
+    const npmBin = path.dirname(resolved);
+    const directEntrypoints = {
+      codex: {
+        executable: process.execPath,
+        prefix: [path.join(npmBin, "node_modules", "@openai", "codex", "bin", "codex.js")],
+      },
+      claude: {
+        executable: path.join(npmBin, "node_modules", "@anthropic-ai", "claude-code", "bin", "claude.exe"),
+        prefix: [],
+      },
+      dsh: {
+        executable: process.execPath,
+        prefix: [path.join(npmBin, "node_modules", "@deepseek-ai", "dsh", "lib", "bin.js")],
+      },
+    };
+    const direct = directEntrypoints[name];
+    if (direct && existsSync(direct.executable) && direct.prefix.every(existsSync)) {
+      return spawn(direct.executable, [...direct.prefix, ...args], childOptions);
+    }
+    return spawn("powershell.exe", [
+      "-NoLogo",
+      "-NoProfile",
+      "-NonInteractive",
+      "-ExecutionPolicy",
+      "Bypass",
+      "-File",
+      resolved,
+      ...args,
+    ], childOptions);
+  }
+  if (process.platform === "win32" && /\.(cmd|bat)$/i.test(resolved)) {
+    throw Object.assign(new Error(`Unsafe command shim without PowerShell alternative: ${resolved}`), { code: "ENOTSUP" });
+  }
+  return spawn(resolved, args, childOptions);
+}
+
+export function probeCommand(name, args = ["--version"]) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawnCommand(name, args, { windowsHide: true, stdio: ["ignore", "pipe", "pipe"] });
+    } catch {
+      resolve({ available: false, version: null });
+      return;
+    }
+    let output = "";
+    const timer = setTimeout(() => child.kill(), 3000);
+    child.stdout.on("data", (chunk) => { output += chunk; });
+    child.stderr.on("data", (chunk) => { output += chunk; });
+    child.on("error", () => {
+      clearTimeout(timer);
+      resolve({ available: false, version: null });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timer);
+      resolve({ available: code === 0, version: output.trim().split(/\r?\n/).at(-1) || null });
+    });
+  });
+}
+
+export function lines(stream, onLine) {
+  let buffer = "";
+  stream.setEncoding("utf8");
+  stream.on("data", (chunk) => {
+    buffer += chunk;
+    while (true) {
+      const index = buffer.indexOf("\n");
+      if (index < 0) break;
+      const line = buffer.slice(0, index).replace(/\r$/, "");
+      buffer = buffer.slice(index + 1);
+      if (line) onLine(line);
+    }
+  });
+  stream.on("end", () => {
+    const line = buffer.trim();
+    if (line) onLine(line);
+  });
+}

package/src/adapters/unavailable.js

@@ -0,0 +1,30 @@
+import { probeCommand } from "./process-utils.js";
+
+export class UnavailableAdapter {
+  constructor({ id, label, command, note }) {
+    this.id = id;
+    this.label = label;
+    this.command = command;
+    this.note = note;
+    this.capabilities = {
+      create: false,
+      attach: false,
+      discover: false,
+      streaming: false,
+      approve: false,
+      resume: false,
+      cancel: false,
+      selectModel: false,
+      realAgent: true,
+    };
+  }
+
+  async detect() {
+    const result = await probeCommand(this.command);
+    return { ...result, supported: false, note: this.note };
+  }
+
+  async start() {
+    throw Object.assign(new Error(`${this.label} adapter is not implemented in this MVP`), { statusCode: 501 });
+  }
+}

package/src/adapters/zcode-native.js

@@ -0,0 +1,40 @@
+import { probeCommand } from "./process-utils.js";
+
+const REMOTE_CONTROL_URL = "https://zcode.z.ai/en/docs/remote-control";
+
+export class ZCodeNativeAdapter {
+  id = "zcode";
+  label = "ZCode（原生远控）";
+  capabilities = {
+    create: false,
+    attach: false,
+    discover: false,
+    streaming: false,
+    approve: false,
+    resume: false,
+    cancel: false,
+    selectModel: false,
+    realAgent: true,
+    nativeRemoteControl: true,
+  };
+  #probe;
+
+  constructor({ probe = probeCommand } = {}) {
+    this.#probe = probe;
+  }
+
+  async detect() {
+    const command = await this.#probe("zcode");
+    return {
+      ...command,
+      supported: false,
+      native: true,
+      docsUrl: REMOTE_CONTROL_URL,
+      note: "ZCode 的官方手机远控和微信 Bot 控制已打开的桌面工作区；它未公开可供 AgentBridge 创建或附着会话的本机 API。请在 ZCode 桌面端使用原生远控入口。",
+    };
+  }
+
+  async start() {
+    throw Object.assign(new Error("ZCode currently exposes native Remote Control/Bot Channel, not a third-party local session API"), { statusCode: 501 });
+  }
+}