@dev.fast/whiteboard 0.0.0-stage → 0.2.1-preview.20261005.98

package/src/ask/agents.ts

@@ -0,0 +1,351 @@
+import { spawn } from "node:child_process";
+import { constants } from "node:fs";
+import { access, stat } from "node:fs/promises";
+import { createRequire } from "node:module";
+import { homedir } from "node:os";
+import path from "node:path";
+import { Readable, Writable } from "node:stream";
+
+import {
+  type ClientApp,
+  type ClientConnection,
+  type McpServer,
+  type NewSessionRequest,
+  ndJsonStream,
+} from "@agentclientprotocol/sdk";
+import { piTakesMcp, piWithMcp } from "@review/ask/pi-mcp.js";
+import { type AskAgentId, askAgentIds } from "@review/ask/thread-state.js";
+
+/** How Whiteboard runs an agent that speaks ACP on stdio. */
+type AskAgentLaunch =
+  /** An ACP adapter's executable entry, run with this server's Node, which
+   * drives the user's CLI with the user's login. */
+  | {
+      adapter: string;
+      /** How the adapter is told to use the user's CLI instead of a bundled one. */
+      executableEnv: string;
+    }
+  /** The user's CLI speaks ACP itself, given these arguments. */
+  | { args: string[] };
+
+interface AskAgentSpec {
+  name: string;
+  /** The user's own CLI: the names it goes by on PATH, most specific first. */
+  commands: string[];
+  /** Where its installer puts it when that is not on PATH, under home. */
+  installDirs?: string[];
+  launch: AskAgentLaunch;
+  /** The session mode Whiteboard starts the agent in, when it has one that
+   * keeps the checkout as it is. Read-only is best effort: an agent without
+   * one still answers. */
+  readOnlyMode?: string;
+  /** Adapter-specific session settings, sent as the session's `_meta`. */
+  sessionMeta?: NewSessionRequest["_meta"];
+  /** Settings for the agent's process. */
+  env?: Record<string, string>;
+  /** Signs the user's CLI in again, run in a terminal. */
+  signIn: string;
+  /** How its model gets the MCP servers a session is given, where its
+   * adapter keeps them; without it, the adapter passes them on. */
+  mcp?: AskAgentMcp;
+  /** How it edits and runs commands without asking, in place of its
+   * read-only mode and settings, when the reviewer bypasses permissions.
+   * Whiteboard also allows whatever it still asks. */
+  bypass?: AskAgentBypass;
+}
+
+interface AskAgentMcp {
+  /** Whether this install can take them. */
+  supported(executable: string): Promise<boolean>;
+  /** What the adapter runs in place of the user's CLI to give them, with
+   * what it needs in `env`. */
+  launch(
+    executable: string,
+    servers: McpServer[],
+    env: NodeJS.ProcessEnv,
+  ): Promise<string>;
+}
+
+export interface AskAgentBypass {
+  mode?: string;
+  sessionMeta?: NewSessionRequest["_meta"];
+  env?: Record<string, string>;
+}
+
+export const askAgents: Record<AskAgentId, AskAgentSpec> = {
+  claude: {
+    name: "Claude Code",
+    commands: ["claude"],
+    launch: {
+      adapter: "@agentclientprotocol/claude-agent-acp/dist/index.js",
+      executableEnv: "CLAUDE_CODE_EXECUTABLE",
+    },
+    signIn: "claude auth login",
+    // Plan mode would end each answer asking to leave it, and it blocks the
+    // Whiteboard tools that edit the review. Claude instead runs in its
+    // default mode without its file tools, and without bypass, so commands
+    // still ask; the review is edited through Whiteboard's MCP server.
+    readOnlyMode: "default",
+    sessionMeta: {
+      claudeCode: {
+        options: {
+          disallowedTools: [
+            "Edit",
+            "MultiEdit",
+            "Write",
+            "NotebookEdit",
+            "EnterPlanMode",
+            "ExitPlanMode",
+          ],
+          allowDangerouslySkipPermissions: false,
+        },
+      },
+    },
+    // Its file tools back, and its own bypass, where its settings allow it.
+    bypass: {
+      mode: "bypassPermissions",
+      sessionMeta: {
+        claudeCode: {
+          options: { disallowedTools: ["EnterPlanMode", "ExitPlanMode"] },
+        },
+      },
+    },
+  },
+  codex: {
+    name: "Codex",
+    commands: ["codex"],
+    launch: {
+      adapter: "@agentclientprotocol/codex-acp/dist/index.js",
+      executableEnv: "CODEX_PATH",
+    },
+    signIn: "codex login",
+    readOnlyMode: "read-only",
+    bypass: { mode: "agent-full-access" },
+  },
+  cursor: {
+    name: "Cursor",
+    // Its installer adds `agent` too, but Homebrew's has only this name,
+    // and `agent` alone could be anything.
+    commands: ["cursor-agent"],
+    installDirs: [".local/bin"],
+    launch: { args: ["acp"] },
+    signIn: "cursor-agent login",
+    // Ask mode answers without editing or running commands.
+    readOnlyMode: "ask",
+    // Agent mode asks before it edits or runs a command.
+    bypass: { mode: "agent" },
+  },
+  opencode: {
+    name: "OpenCode",
+    commands: ["opencode"],
+    installDirs: [".opencode/bin"],
+    launch: { args: ["acp"] },
+    signIn: "opencode auth login",
+    // Every OpenCode agent may edit and run commands without asking; its
+    // plan agent only stops edits. These permissions, over the user's own
+    // config, refuse edits and ask before commands in any of them. Its
+    // build agent then answers as usual, where plan's would plan.
+    readOnlyMode: "build",
+    env: {
+      OPENCODE_CONFIG_CONTENT: JSON.stringify({
+        permission: { edit: "deny", bash: "ask", webfetch: "ask" },
+      }),
+    },
+    bypass: {
+      mode: "build",
+      env: {
+        OPENCODE_CONFIG_CONTENT: JSON.stringify({
+          permission: { edit: "allow", bash: "allow", webfetch: "allow" },
+        }),
+      },
+    },
+  },
+  pi: {
+    name: "Pi",
+    commands: ["pi"],
+    launch: {
+      adapter: "pi-acp/dist/index.js",
+      executableEnv: "PI_ACP_PI_COMMAND",
+    },
+    // Pi signs in from its own prompt, with /login.
+    signIn: "pi",
+    mcp: { supported: piTakesMcp, launch: piWithMcp },
+    // Pi never asks before it edits or runs a command, and has no mode that
+    // stops it.
+  },
+};
+
+export interface AskAgentStatus {
+  id: AskAgentId;
+  name: string;
+  available: boolean;
+  /** Whether it has a mode that keeps the checkout as it is. */
+  readOnly: boolean;
+  /** Whether Whiteboard can have it edit and run commands without asking. */
+  bypass: boolean;
+}
+
+/** An Ask agent process, connected as the given ACP client. */
+export interface AskAgentProcess {
+  connect(client: ClientApp): ClientConnection;
+  /** Recent stderr, for explaining a failed start. */
+  diagnostics(): string;
+  stop(): void;
+}
+
+export type AskAgentLauncher = (
+  agent: AskAgentId,
+  cwd: string,
+  options?: {
+    bypass?: boolean;
+    /** The MCP servers its sessions are given. */
+    mcpServers?: McpServer[];
+  },
+) => Promise<AskAgentProcess>;
+
+/** Desktop inherits the login shell's PATH, so this sees what a terminal sees.
+ * Package-manager bin directories are skipped: the adapters' own dependencies
+ * put `codex` there, and that is not the user's install. */
+export async function findExecutable(
+  command: string,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<string | undefined> {
+  for (const directory of (env.PATH ?? "").split(path.delimiter)) {
+    if (!directory || directory.split(path.sep).includes("node_modules"))
+      continue;
+    const candidate = path.join(directory, command);
+
+    try {
+      if (!(await stat(candidate)).isFile()) continue;
+      await access(candidate, constants.X_OK);
+
+      return candidate;
+    } catch {
+      /* Not in this directory. */
+    }
+  }
+
+  return undefined;
+}
+
+/** The user's install of an agent's CLI: on PATH, else where its installer
+ * puts it. */
+async function findAgent(
+  spec: AskAgentSpec,
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<string | undefined> {
+  const installed = (spec.installDirs ?? []).map((directory) =>
+    path.join(homedir(), directory),
+  );
+
+  for (const command of spec.commands) {
+    const found =
+      (await findExecutable(command, env)) ??
+      (await findExecutable(command, { PATH: installed.join(path.delimiter) }));
+
+    if (found) return found;
+  }
+
+  return undefined;
+}
+
+/** Whether the agent's model gets the MCP servers its sessions are given. */
+export async function askAgentTakesMcp(agent: AskAgentId): Promise<boolean> {
+  const spec = askAgents[agent];
+
+  if (!spec.mcp) return true;
+  const executable = await findAgent(spec);
+
+  return executable !== undefined && spec.mcp.supported(executable);
+}
+
+export async function detectAskAgents(
+  env: NodeJS.ProcessEnv = process.env,
+): Promise<AskAgentStatus[]> {
+  return Promise.all(
+    askAgentIds.map(async (id) => ({
+      id,
+      name: askAgents[id].name,
+      available: (await findAgent(askAgents[id], env)) !== undefined,
+      readOnly: askAgents[id].readOnlyMode !== undefined,
+      bypass: askAgents[id].bypass !== undefined,
+    })),
+  );
+}
+
+const STDERR_LIMIT = 8_000;
+
+/** Runs an adapter with this server's runtime, Desktop's being Electron, or
+ * the user's CLI itself. */
+export const launchAskAgent: AskAgentLauncher = async (
+  agent,
+  cwd,
+  { bypass = false, mcpServers = [] } = {},
+) => {
+  const spec = askAgents[agent];
+  const executable = await findAgent(spec);
+
+  if (!executable) throw new Error(`${spec.name} is not installed.`);
+
+  const env: NodeJS.ProcessEnv = {
+    ...process.env,
+    ...((bypass && spec.bypass?.env) || spec.env),
+  };
+
+  // A server started from inside a Claude Code session must not look nested.
+  delete env.CLAUDECODE;
+  delete env.CLAUDE_CODE_ENTRYPOINT;
+
+  const { launch } = spec;
+
+  let command = executable;
+  let args: string[];
+
+  if ("adapter" in launch) {
+    env[launch.executableEnv] =
+      spec.mcp && mcpServers.length && (await spec.mcp.supported(executable))
+        ? await spec.mcp.launch(executable, mcpServers, env)
+        : executable;
+
+    if (process.versions.electron) env.ELECTRON_RUN_AS_NODE = "1";
+    command = process.execPath;
+    args = [createRequire(import.meta.url).resolve(launch.adapter)];
+  } else args = launch.args;
+
+  const child = spawn(command, args, {
+    cwd,
+    env,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  let stderr = "";
+
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk: string) => {
+    stderr = (stderr + chunk).slice(-STDERR_LIMIT);
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    child.once("spawn", resolve);
+    child.once("error", reject);
+  });
+
+  const stream = ndJsonStream(
+    Writable.toWeb(child.stdin),
+    // SAFETY: stdout has no encoding set, so it yields Buffers (Uint8Arrays).
+    Readable.toWeb(child.stdout) as ReadableStream<Uint8Array>,
+  );
+
+  return {
+    connect: (client) => {
+      const connection = client.connect(stream);
+      child.once("exit", () => connection.close());
+
+      return connection;
+    },
+    diagnostics: () => stderr,
+    stop: () => {
+      if (child.exitCode === null) child.kill();
+    },
+  };
+};

package/src/ask/checkout-files.ts

@@ -0,0 +1,47 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+/** The checkout's files relative to its root: tracked ones, and new ones git
+ * does not ignore. None where git cannot list them. */
+export async function checkoutFiles(root: string): Promise<string[]> {
+  try {
+    const { stdout } = await execFileAsync(
+      "git",
+      [
+        "-C",
+        root,
+        "ls-files",
+        "-z",
+        "--cached",
+        "--others",
+        "--exclude-standard",
+      ],
+      { maxBuffer: 64 * 1024 * 1024 },
+    );
+
+    return [...new Set(stdout.split("\0").filter(Boolean))];
+  } catch {
+    return [];
+  }
+}
+
+/** How long a listing serves mentions before git is asked again. */
+const LISTING_MS = 10_000;
+
+const listings = new Map<string, { at: number; files: Promise<string[]> }>();
+
+/** The checkout's files for a mention picker, which asks on each keystroke:
+ * listed again only once the last listing is a few seconds old. */
+export function mentionableFiles(root: string): Promise<string[]> {
+  const now = Date.now();
+  const listed = listings.get(root);
+
+  if (listed && now - listed.at < LISTING_MS) return listed.files;
+  const files = checkoutFiles(root);
+
+  listings.set(root, { at: now, files });
+
+  return files;
+}

package/src/ask/file-refs.ts

@@ -0,0 +1,111 @@
+/** A file an agent's answer names, as it wrote it: `src/app.ts`,
+ * `src/app.ts:42:7`, `/checkout/src/app.ts#L42`, `file:///checkout/app.ts`. */
+export interface AskFileRef {
+  path: string;
+  line?: number;
+}
+
+/** `:42`, `:42:7`, `:42-50`, `#L42`, `#L42C7`, `#L42-L50`. */
+const lineSuffix = /(?::(\d+)(?::\d+)?(?:-\d+)?|#L(\d+)(?:C\d+)?(?:-L?\d+)?)$/;
+
+/** A scheme, as in `https://`; a Windows drive letter is not one. */
+const urlScheme = /^[a-z][a-z\d+.-]+:/i;
+
+/** What a piece of inline code or a link target names, if it could be a
+ * file: a path with a directory or an extension, and no spaces. Whether the
+ * file exists is the checkout's to say. */
+export function parseFileRef(text: string): AskFileRef | undefined {
+  let value = text.trim();
+
+  if (value.startsWith("file://")) {
+    try {
+      value = decodeURIComponent(value.slice("file://".length));
+    } catch {
+      return undefined;
+    }
+  }
+
+  if (
+    !value ||
+    value.length > 400 ||
+    /[\s`'"<>|*?{}$]/.test(value) ||
+    urlScheme.test(value) ||
+    value.startsWith("-")
+  )
+    return undefined;
+
+  const match = lineSuffix.exec(value);
+
+  const path = (match ? value.slice(0, match.index) : value).replace(
+    /^\.\//,
+    "",
+  );
+
+  const name = path.split("/").at(-1) ?? "";
+
+  if (!name || !(path.includes("/") || /\.[a-z][a-z\d]*$/i.test(name)))
+    return undefined;
+
+  const line = Number(match?.[1] ?? match?.[2]);
+
+  return line > 0 ? { path, line } : { path };
+}
+
+/** Resolves the paths an answer names to files in the checkout, relative to
+ * its root. Agents write paths from the checkout root, as absolute paths, or
+ * relative to the package they are in; a path that could be several files
+ * resolves to the one the agent's tools touched, else to none. */
+export function resolveFileRefs(
+  root: string,
+  files: readonly string[],
+  paths: readonly string[],
+  /** Paths the agent's tool calls named. */
+  touched: readonly string[] = [],
+): Map<string, string> {
+  const known = new Set(files);
+
+  const inRoot = (path: string) =>
+    path.startsWith(`${root}/`) ? path.slice(root.length + 1) : path;
+
+  const named = (path: string) =>
+    known.has(path)
+      ? [path]
+      : files.filter((file) => file.endsWith(`/${path}`));
+
+  const touchedFiles = new Set(
+    touched.flatMap((path) => {
+      const relative = inRoot(path);
+
+      return relative.startsWith("/") ? [] : named(relative);
+    }),
+  );
+
+  const resolved = new Map<string, string>();
+
+  for (const asked of paths) {
+    const path = inRoot(asked);
+
+    // Absolute, but not in this checkout.
+    if (path.startsWith("/")) continue;
+
+    // `a/` and `b/` are a diff's prefixes, not directories.
+    for (const candidate of [path, path.replace(/^[ab]\//, "")]) {
+      const matches = named(candidate);
+      const touchedMatches = matches.filter((file) => touchedFiles.has(file));
+
+      const match =
+        matches.length === 1
+          ? matches[0]
+          : touchedMatches.length === 1
+            ? touchedMatches[0]
+            : undefined;
+
+      if (match) {
+        resolved.set(asked, match);
+        break;
+      }
+    }
+  }
+
+  return resolved;
+}

package/src/ask/pi-mcp.ts

@@ -0,0 +1,154 @@
+import { execFile } from "node:child_process";
+import { chmod, mkdir, readFile, rename, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { promisify } from "node:util";
+
+import type { McpServer } from "@agentclientprotocol/sdk";
+import { devReviewHome } from "@dev.fast/trace-core";
+
+/**
+ * pi-acp keeps the MCP servers a session is given without passing them to
+ * Pi. Pi 0.99.0 and later take them from an extension, so Ask starts Pi
+ * through a wrapper that loads one, registering the servers for that session
+ * only. Older Pi, and Windows, which would need a different wrapper, answer
+ * without them.
+ */
+
+/** The first Pi with `pi.registerMcpServer()`. */
+const PI_MCP_VERSION = [0, 99, 0] as const;
+
+/** How long a version read is trusted: a session's first prompt and its
+ * launch ask moments apart, and an update during a review is seen soon. */
+const VERSION_TTL_MS = 30_000;
+
+const SERVERS_ENV = "WHITEBOARD_ASK_MCP";
+
+const PI_ENV = "WHITEBOARD_ASK_PI";
+
+const EXTENSION_ENV = "WHITEBOARD_ASK_PI_EXTENSION";
+
+const EXTENSION = `// Managed by Whiteboard: gives a Pi session that Ask starts the MCP servers
+// Whiteboard hands it. Do not edit.
+export default function (pi: {
+  registerMcpServer(name: string, config: object): void;
+}) {
+  const servers = JSON.parse(process.env.${SERVERS_ENV} ?? "{}");
+
+  for (const [name, config] of Object.entries(servers))
+    pi.registerMcpServer(name, config as object);
+}
+`;
+
+const WRAPPER = `#!/bin/sh
+# Managed by Whiteboard: starts Pi for Ask with Whiteboard's extension.
+exec "$${PI_ENV}" -e "$${EXTENSION_ENV}" "$@"
+`;
+
+const versions = new Map<
+  string,
+  { read: number; version: Promise<number[] | undefined> }
+>();
+
+function piVersion(executable: string) {
+  const cached = versions.get(executable);
+
+  if (cached && Date.now() - cached.read < VERSION_TTL_MS)
+    return cached.version;
+
+  const version = promisify(execFile)(executable, ["--version"], {
+    timeout: 5_000,
+  })
+    .then(({ stdout }) =>
+      /(\d+)\.(\d+)\.(\d+)/u.exec(stdout)?.slice(1).map(Number),
+    )
+    .catch(() => undefined);
+
+  versions.set(executable, { read: Date.now(), version });
+
+  return version;
+}
+
+/** Whether this Pi can be given MCP servers. */
+export async function piTakesMcp(executable: string): Promise<boolean> {
+  if (process.platform === "win32") return false;
+  const version = await piVersion(executable);
+
+  if (!version) return false;
+
+  for (const [index, least] of PI_MCP_VERSION.entries()) {
+    const part = version[index] ?? 0;
+
+    if (part !== least) return part > least;
+  }
+
+  return true;
+}
+
+/** Writes a file only when it changed, replacing it whole, since another
+ * Ask session may be running it. */
+async function keep(file: string, content: string, mode: number) {
+  const current = await readFile(file, "utf8").catch(() => undefined);
+
+  if (current === content) return;
+  const staged = `${file}.${process.pid}.tmp`;
+
+  await writeFile(staged, content, { mode });
+  await chmod(staged, mode);
+  await rename(staged, file);
+}
+
+/** Pi's shape for each server, under its name; it reaches every tool
+ * without searching for it. */
+/** A server as Pi's `mcp.json` has it. */
+type PiMcpServer = { exposure: "direct" } & (
+  | { command: string; args: string[]; env: Record<string, string> }
+  | { url: string; headers: Record<string, string> }
+);
+
+function piServers(servers: McpServer[]) {
+  const piServers: Record<string, PiMcpServer> = {};
+
+  const record = (pairs: { name: string; value: string }[]) =>
+    Object.fromEntries(pairs.map(({ name, value }) => [name, value]));
+
+  for (const server of servers) {
+    if ("command" in server)
+      piServers[server.name] = {
+        command: server.command,
+        args: server.args,
+        env: record(server.env),
+        exposure: "direct",
+      };
+    // Pi speaks neither SSE nor MCP over ACP.
+    else if (server.type === "http")
+      piServers[server.name] = {
+        url: server.url,
+        headers: record(server.headers),
+        exposure: "direct",
+      };
+  }
+
+  return piServers;
+}
+
+/** The command pi-acp runs in place of Pi: Pi with the extension that
+ * registers `servers`, which go to it in `env`. */
+export async function piWithMcp(
+  executable: string,
+  servers: McpServer[],
+  env: NodeJS.ProcessEnv,
+): Promise<string> {
+  const directory = path.join(devReviewHome(), "ask", "pi");
+  const extension = path.join(directory, "whiteboard-mcp.ts");
+  const wrapper = path.join(directory, "pi");
+
+  await mkdir(directory, { recursive: true });
+  await keep(extension, EXTENSION, 0o644);
+  await keep(wrapper, WRAPPER, 0o755);
+
+  env[PI_ENV] = executable;
+  env[EXTENSION_ENV] = extension;
+  env[SERVERS_ENV] = JSON.stringify(piServers(servers));
+
+  return wrapper;
+}