@agentgrader/agent-acp 2.0.0

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+import { AgentAdapter, SandboxHandle, AgentConfig, StepEvent, AgentResult } from '@agentgrader/core';
+
+declare class AcpAgentAdapter implements AgentAdapter {
+    readonly name = "acp";
+    solve(input: {
+        prompt: string;
+        sandbox: SandboxHandle;
+        config: AgentConfig;
+        onStep: (step: StepEvent) => void;
+    }): Promise<AgentResult>;
+}
+
+export { AcpAgentAdapter };

package/dist/index.js

@@ -0,0 +1,419 @@
+import { randomUUID } from 'crypto';
+import { spawn } from 'child_process';
+import { Writable, Readable } from 'stream';
+import { ndJsonStream, ClientSideConnection, PROTOCOL_VERSION, RequestError } from '@agentclientprotocol/sdk';
+
+// src/index.ts
+var DEFAULT_WORKSPACE_ROOT = "/app";
+function resolveAcpSpawn(config) {
+  if (!config.acp_command) {
+    throw new Error(
+      "acp_command is required in agent config when using AcpAgentAdapter (e.g. acp_command: cursor-agent)."
+    );
+  }
+  const explicitArgs = config.acp_args ?? [];
+  if (explicitArgs.length > 0) {
+    return { command: config.acp_command, args: explicitArgs };
+  }
+  const parts = config.acp_command.trim().split(/\s+/).filter(Boolean);
+  if (parts.length === 0) {
+    throw new Error("acp_command must not be empty.");
+  }
+  return { command: parts[0], args: parts.slice(1) };
+}
+function resolveSandboxPath(path, workspaceRoot) {
+  if (path.startsWith("/")) {
+    return path;
+  }
+  return `${workspaceRoot}/${path}`.replace(/\/+/g, "/");
+}
+function shellQuote(value) {
+  return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+function sliceFileContent(content, line, limit) {
+  if (line == null && limit == null) {
+    return content;
+  }
+  const lines = content.split("\n");
+  const start = Math.max((line ?? 1) - 1, 0);
+  const end = limit == null ? lines.length : start + limit;
+  return lines.slice(start, end).join("\n");
+}
+var SandboxAcpClient = class {
+  constructor(sandbox, workspaceRoot, onStep) {
+    this.sandbox = sandbox;
+    this.workspaceRoot = workspaceRoot;
+    this.onStep = onStep;
+  }
+  sandbox;
+  workspaceRoot;
+  onStep;
+  terminals = /* @__PURE__ */ new Map();
+  stepIndex = 0;
+  emitStep(partial) {
+    const step = {
+      index: this.stepIndex++,
+      timestamp: Date.now(),
+      tokensIn: partial.tokensIn ?? 0,
+      tokensOut: partial.tokensOut ?? 0,
+      cachedTokens: partial.cachedTokens ?? 0,
+      costUsd: partial.costUsd ?? 0,
+      kind: partial.kind,
+      tool: partial.tool,
+      content: partial.content
+    };
+    this.onStep(step);
+  }
+  async requestPermission(params) {
+    const allowOption = params.options.find((option) => option.kind === "allow_once" || option.kind === "allow_always") ?? params.options[0];
+    if (!allowOption) {
+      return { outcome: { outcome: "cancelled" } };
+    }
+    this.emitStep({
+      kind: "tool_call",
+      tool: "requestPermission",
+      content: params.toolCall.title ?? params.toolCall.toolCallId
+    });
+    return {
+      outcome: {
+        outcome: "selected",
+        optionId: allowOption.optionId
+      }
+    };
+  }
+  async sessionUpdate(params) {
+    const update = params.update;
+    switch (update.sessionUpdate) {
+      case "agent_message_chunk":
+        this.emitStep({
+          kind: "message",
+          content: extractTextContent(update)
+        });
+        break;
+      case "agent_thought_chunk":
+        this.emitStep({
+          kind: "thinking",
+          content: extractTextContent(update)
+        });
+        break;
+      case "tool_call":
+        this.emitStep({
+          kind: "tool_call",
+          tool: update.title ?? update.toolCallId,
+          content: update.kind ?? String(update.status ?? "")
+        });
+        break;
+      case "tool_call_update":
+        this.emitStep({
+          kind: "tool_result",
+          tool: update.title ?? update.toolCallId,
+          content: String(update.status ?? "")
+        });
+        break;
+    }
+  }
+  async readTextFile(params) {
+    const path = resolveSandboxPath(params.path, this.workspaceRoot);
+    this.emitStep({
+      kind: "tool_call",
+      tool: "fs/read_text_file",
+      content: path
+    });
+    try {
+      const raw = await this.sandbox.readFile(path);
+      const content = sliceFileContent(raw, params.line, params.limit);
+      this.emitStep({
+        kind: "tool_result",
+        tool: "fs/read_text_file",
+        content: `${content.length} bytes`
+      });
+      return { content };
+    } catch {
+      throw RequestError.resourceNotFound(path);
+    }
+  }
+  async writeTextFile(params) {
+    const path = resolveSandboxPath(params.path, this.workspaceRoot);
+    this.emitStep({
+      kind: "tool_call",
+      tool: "fs/write_text_file",
+      content: path
+    });
+    try {
+      await this.sandbox.writeFile(path, params.content);
+      this.emitStep({
+        kind: "tool_result",
+        tool: "fs/write_text_file",
+        content: "ok"
+      });
+      return {};
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      throw RequestError.internalError({ path }, message);
+    }
+  }
+  async createTerminal(params) {
+    const terminalId = randomUUID();
+    const outputFile = `/tmp/acp-term-${terminalId}.out`;
+    const exitFile = `/tmp/acp-term-${terminalId}.exit`;
+    const pidFile = `/tmp/acp-term-${terminalId}.pid`;
+    const cwd = params.cwd ?? this.workspaceRoot;
+    const args = (params.args ?? []).map(shellQuote).join(" ");
+    const envPrefix = params.env && params.env.length > 0 ? `${params.env.map((entry) => `${entry.name}=${shellQuote(entry.value)}`).join(" ")} ` : "";
+    const command = `${envPrefix}${shellQuote(params.command)}${args ? ` ${args}` : ""}`;
+    const shellCmd = [
+      `cd ${shellQuote(cwd)}`,
+      `(${command}) > ${shellQuote(outputFile)} 2>&1; echo $? > ${shellQuote(exitFile)} & echo $! > ${shellQuote(pidFile)}`
+    ].join(" && ");
+    this.emitStep({
+      kind: "tool_call",
+      tool: "terminal/create",
+      content: params.command
+    });
+    const spawnResult = await this.sandbox.exec(shellCmd);
+    if (spawnResult.exitCode !== 0) {
+      throw RequestError.internalError(
+        { command: params.command, stderr: spawnResult.stderr },
+        `Failed to start terminal command: ${spawnResult.stderr || spawnResult.stdout}`
+      );
+    }
+    this.terminals.set(terminalId, {
+      outputFile,
+      exitFile,
+      pidFile,
+      released: false
+    });
+    this.emitStep({
+      kind: "tool_result",
+      tool: "terminal/create",
+      content: terminalId
+    });
+    return { terminalId };
+  }
+  async terminalOutput(params) {
+    const terminal = this.getTerminal(params.terminalId);
+    const output = await this.readOptionalFile(terminal.outputFile);
+    const exitStatus = await this.readExitStatus(terminal);
+    this.emitStep({
+      kind: "tool_call",
+      tool: "terminal/output",
+      content: params.terminalId
+    });
+    return {
+      output,
+      truncated: false,
+      exitStatus
+    };
+  }
+  async waitForTerminalExit(params) {
+    const terminal = this.getTerminal(params.terminalId);
+    const deadline = Date.now() + 18e4;
+    while (Date.now() < deadline) {
+      const exitStatus = await this.readExitStatus(terminal);
+      if (exitStatus) {
+        this.emitStep({
+          kind: "tool_result",
+          tool: "terminal/wait_for_exit",
+          content: String(exitStatus.exitCode ?? "signal")
+        });
+        return {
+          exitCode: exitStatus.exitCode ?? null,
+          signal: exitStatus.signal ?? null
+        };
+      }
+      await sleep(100);
+    }
+    throw RequestError.internalError(
+      { terminalId: params.terminalId },
+      "Timed out waiting for terminal command to exit."
+    );
+  }
+  async killTerminal(params) {
+    const terminal = this.getTerminal(params.terminalId);
+    const pid = (await this.readOptionalFile(terminal.pidFile)).trim();
+    if (pid) {
+      await this.sandbox.exec(`kill -TERM ${shellQuote(pid)} 2>/dev/null || kill -KILL ${shellQuote(pid)} 2>/dev/null || true`);
+    }
+    this.emitStep({
+      kind: "tool_call",
+      tool: "terminal/kill",
+      content: params.terminalId
+    });
+  }
+  async releaseTerminal(params) {
+    const terminal = this.getTerminal(params.terminalId);
+    if (terminal.released) {
+      return;
+    }
+    const pid = (await this.readOptionalFile(terminal.pidFile)).trim();
+    if (pid) {
+      await this.sandbox.exec(`kill -TERM ${shellQuote(pid)} 2>/dev/null || true`);
+    }
+    terminal.released = true;
+    this.terminals.delete(params.terminalId);
+    await this.sandbox.exec(
+      `rm -f ${shellQuote(terminal.outputFile)} ${shellQuote(terminal.exitFile)} ${shellQuote(terminal.pidFile)}`
+    );
+    this.emitStep({
+      kind: "tool_result",
+      tool: "terminal/release",
+      content: params.terminalId
+    });
+  }
+  getTerminal(terminalId) {
+    const terminal = this.terminals.get(terminalId);
+    if (!terminal || terminal.released) {
+      throw RequestError.invalidParams({ terminalId }, `Unknown or released terminal: ${terminalId}`);
+    }
+    return terminal;
+  }
+  async readOptionalFile(path) {
+    try {
+      return await this.sandbox.readFile(path);
+    } catch {
+      return "";
+    }
+  }
+  async readExitStatus(terminal) {
+    const exitRaw = (await this.readOptionalFile(terminal.exitFile)).trim();
+    if (!exitRaw) {
+      return null;
+    }
+    const exitCode = Number.parseInt(exitRaw, 10);
+    return {
+      exitCode: Number.isNaN(exitCode) ? null : exitCode,
+      signal: null
+    };
+  }
+};
+function extractTextContent(chunk) {
+  if (chunk.content.type === "text") {
+    return chunk.content.text;
+  }
+  return void 0;
+}
+function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function killProcess(proc) {
+  if (proc.exitCode != null || proc.signalCode != null) {
+    return;
+  }
+  proc.kill("SIGTERM");
+  setTimeout(() => {
+    if (proc.exitCode == null && proc.signalCode == null) {
+      proc.kill("SIGKILL");
+    }
+  }, 2e3).unref();
+}
+var AcpAgentAdapter = class {
+  name = "acp";
+  async solve(input) {
+    const { prompt, sandbox, config, onStep } = input;
+    const { command, args } = resolveAcpSpawn(config);
+    const workspaceRoot = config.acp_cwd ?? DEFAULT_WORKSPACE_ROOT;
+    const client = new SandboxAcpClient(sandbox, workspaceRoot, onStep);
+    let proc;
+    let connection;
+    try {
+      proc = spawn(command, args, {
+        stdio: ["pipe", "pipe", "pipe"],
+        env: {
+          ...process.env,
+          ...config.acp_env ?? {}
+        }
+      });
+      const stdin = proc.stdin;
+      const stdout = proc.stdout;
+      if (!stdin || !stdout) {
+        throw new Error(`Failed to open stdio pipes for ACP agent: ${command}`);
+      }
+      proc.on("error", (err) => {
+        onStep({
+          index: 0,
+          kind: "message",
+          timestamp: Date.now(),
+          tokensIn: 0,
+          tokensOut: 0,
+          cachedTokens: 0,
+          costUsd: 0,
+          content: `ACP subprocess error: ${err.message}`
+        });
+      });
+      const stream = ndJsonStream(
+        Writable.toWeb(stdin),
+        Readable.toWeb(stdout)
+      );
+      connection = new ClientSideConnection(() => client, stream);
+      await connection.initialize({
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: {
+          fs: {
+            readTextFile: true,
+            writeTextFile: true
+          },
+          terminal: true
+        },
+        clientInfo: {
+          name: "Agentgrader",
+          version: "1.0.0"
+        }
+      });
+      const session = await connection.newSession({
+        cwd: workspaceRoot,
+        mcpServers: []
+      });
+      const stepTimeoutMs = config.step_timeout_ms ?? 12e4;
+      let timedOut = false;
+      let promptResponse;
+      try {
+        promptResponse = await Promise.race([
+          connection.prompt({
+            sessionId: session.sessionId,
+            prompt: [{ type: "text", text: prompt }]
+          }),
+          new Promise((_, reject) => {
+            setTimeout(() => {
+              timedOut = true;
+              void connection?.cancel({ sessionId: session.sessionId }).catch(() => void 0);
+              reject(new Error(`ACP prompt timed out after ${stepTimeoutMs}ms (step_timeout_ms).`));
+            }, stepTimeoutMs);
+          })
+        ]);
+      } catch (err) {
+        if (timedOut) {
+          const finalDiff2 = await sandbox.gitDiff().catch(() => "");
+          return {
+            finished: false,
+            finalDiff: finalDiff2,
+            error: err instanceof Error ? err.message : `ACP prompt timed out after ${stepTimeoutMs}ms (step_timeout_ms).`
+          };
+        }
+        throw err;
+      }
+      const finalDiff = await sandbox.gitDiff();
+      const finished = promptResponse.stopReason === "end_turn";
+      return {
+        finished,
+        finalDiff,
+        error: finished ? void 0 : `ACP agent stopped with reason: ${promptResponse.stopReason}`
+      };
+    } catch (err) {
+      const finalDiff = await sandbox.gitDiff().catch(() => "");
+      return {
+        finished: false,
+        finalDiff,
+        error: err instanceof Error ? err.message : String(err)
+      };
+    } finally {
+      if (connection) {
+        await Promise.race([connection.closed, sleep(2e3)]);
+      }
+      if (proc) {
+        killProcess(proc);
+      }
+    }
+  }
+};
+
+export { AcpAgentAdapter };

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@agentgrader/agent-acp",
+  "version": "2.0.0",
+  "description": "Agent Client Protocol (ACP) adapter for the Agentgrader framework",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup src/index.ts --format esm --dts --clean --treeshake",
+    "build:watch": "tsup src/index.ts --format esm --dts --watch"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "^0.25.1",
+    "@agentgrader/core": "^1.3.0",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "tsup": "^8.5.1"
+  },
+  "peerDependencies": {
+    "@agentgrader/core": "^1.3.0"
+  }
+}