@engineeros/connector 0.5.0 → 0.6.1

package/README.md

@@ -1,5 +1,17 @@
 # EngineerOS Connector
 
+The connector uses an authenticated EngineerOS WebSocket for pairing, workspace identity, run lifecycle, and evidence. Coding work can run through any ACP v1-compatible agent over stdio. Codex CLI remains available as the default built-in adapter.
+
+## Pair an ACP coding agent
+
+Run the command from the repository the agent should work in:
+
+```powershell
+npx --yes @engineeros/connector@latest pair PAIRING-CODE --url http://localhost:8000 --workspace . --onboard --agent-name "My ACP agent" --agent-command my-agent --agent-args '["--acp"]'
+```
+
+`--agent-command` must start an ACP v1 agent over NDJSON stdio. `--agent-args` is a JSON array so arguments are passed without invoking a shell. Omit both options to use the installed Codex CLI adapter.
+
 Connect a local Codex CLI workspace to EngineerOS through an outbound WebSocket.
 
 This package is only a connector. EngineerOS owns every prompt, Goal instruction, and

package/bin/engineeros-connector.mjs

@@ -11,13 +11,18 @@ import {
 } from "../src/config.mjs";
 import {
   assessmentProgressMessage,
+  applyAcceptedChange,
   executeAssignment,
   executeConnectedPrompt,
   executeWorkspaceAssessment,
-  inspectCodexCli,
+  inspectCodingAgent,
   stopProcess,
   workspaceSnapshot,
 } from "../src/runner.mjs";
+import {
+  describeWebSocketError,
+  startConnectionWatchdog,
+} from "../src/connection.mjs";
 
 const { command, positional, flags } = parseArgs(process.argv.slice(2));
 
@@ -46,6 +51,10 @@ if (command === "pair") {
     workspace: path.resolve(flags.workspace || process.cwd()),
     onboard: flags.onboard === true,
     onboarding_pending: flags.onboard === true,
+    agent_protocol: flags["agent-command"] ? "acp" : "codex",
+    agent_command: flags["agent-command"] || null,
+    agent_args: parseAgentArgs(flags["agent-args"]),
+    agent_name: flags["agent-name"] || null,
     name:
       flags.name ||
       `${os.hostname()} - ${path.basename(path.resolve(flags.workspace || process.cwd()))}`,
@@ -55,7 +64,9 @@ if (command === "pair") {
     pairing_code: pairingCode,
     name: config.name,
     capabilities: {
-      codex_cli: true,
+      agent_protocols: flags["agent-command"] ? ["acp"] : ["codex"],
+      coding_agent: true,
+      codex_cli: !flags["agent-command"],
       platform: process.platform,
       workspace_name: path.basename(config.workspace),
     },
@@ -75,15 +86,16 @@ if (command === "pair") {
   fail("Use `engineeros-connector pair`, `start`, or `status`.");
 }
 
-let codexCli;
+let codingAgent;
 try {
-  codexCli = await inspectCodexCli(config.workspace);
+  codingAgent = await inspectCodingAgent(config, config.workspace);
 } catch (error) {
   fail(error instanceof Error ? error.message : String(error));
 }
-console.log(`Using ${codexCli.version}.`);
+console.log(`Using ${codingAgent.name} through ${codingAgent.protocol} (${codingAgent.version}).`);
 if (firstMessage.type === "pair") {
-  firstMessage.capabilities.codex_cli_version = codexCli.version;
+  firstMessage.capabilities.agent_name = codingAgent.name;
+  firstMessage.capabilities.agent_version = codingAgent.version;
 }
 
 let stopped = false;
@@ -93,12 +105,18 @@ const assessments = [];
 const prompts = [];
 let socket;
 let pingTimer;
+let reconnectTimer;
+let clearConnectionWatchdog;
 let reconnectDelay = 1_000;
 let connectionRejected = false;
+let lastConnectionError;
 let snapshotInFlight = false;
 
 process.on("SIGINT", async () => {
   stopped = true;
+  clearConnectionWatchdog?.();
+  clearTimeout(reconnectTimer);
+  clearInterval(pingTimer);
   await stopProcess(active?.child);
   socket?.close();
   process.exit(0);
@@ -109,13 +127,22 @@ await connect();
 async function connect() {
   console.log(`Connecting ${config.name} to ${config.server_url}`);
   connectionRejected = false;
+  lastConnectionError = undefined;
   socket = new WebSocket(config.server_url);
+  clearConnectionWatchdog = startConnectionWatchdog(socket, config.server_url, {
+    onTimeout: (message) => {
+      lastConnectionError = message;
+      console.error(message);
+      scheduleReconnect();
+    },
+  });
   socket.addEventListener("open", () =>
     socket.send(JSON.stringify(firstMessage)),
   );
   socket.addEventListener("message", async (event) => {
     const message = JSON.parse(String(event.data));
     if (message.type === "paired") {
+      clearConnectionWatchdog?.();
       config = {
         ...config,
         connector_id: message.connector.id,
@@ -134,6 +161,7 @@ async function connect() {
       return;
     }
     if (message.type === "authenticated") {
+      clearConnectionWatchdog?.();
       console.log("Connected and waiting for EngineerOS runs.");
       reconnectDelay = 1_000;
       startPings();
@@ -212,6 +240,7 @@ async function connect() {
     }
   });
   socket.addEventListener("close", () => {
+    clearConnectionWatchdog?.();
     clearInterval(pingTimer);
     if (active?.kind === "prompt") {
       active.cancelled = true;
@@ -225,13 +254,27 @@ async function connect() {
       return;
     }
     if (stopped) return;
+    scheduleReconnect();
+  });
+  socket.addEventListener("error", (event) => {
+    lastConnectionError = describeWebSocketError(event);
     console.error(
-      `Connection lost. Retrying in ${Math.round(reconnectDelay / 1_000)}s.`,
+      `WebSocket connection to ${config.server_url} failed: ${lastConnectionError}`,
     );
-    setTimeout(connect, reconnectDelay);
-    reconnectDelay = Math.min(30_000, reconnectDelay * 2);
   });
-  socket.addEventListener("error", () => {});
+}
+
+function scheduleReconnect() {
+  if (stopped || connectionRejected || reconnectTimer) return;
+  const detail = lastConnectionError ? ` Last error: ${lastConnectionError}` : "";
+  console.error(
+    `Connection unavailable.${detail} Retrying in ${Math.round(reconnectDelay / 1_000)}s.`,
+  );
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = undefined;
+    void connect();
+  }, reconnectDelay);
+  reconnectDelay = Math.min(30_000, reconnectDelay * 2);
 }
 
 async function submitWorkspaceSnapshot() {
@@ -318,7 +361,7 @@ function pump() {
     JSON.stringify({
       type: "run.claim",
       run_id: runId,
-      runner_name: "Codex CLI",
+      runner_name: codingAgent.name,
       metadata: {
         hostname: os.hostname(),
         workspace_name: path.basename(config.workspace),
@@ -330,7 +373,7 @@ function pump() {
 async function executePrompt(assignment) {
   const promptId = assignment.prompt_id;
   console.log(
-    `Answering ${assignment.purpose || "project"} prompt with Codex CLI.`,
+    `Answering ${assignment.purpose || "project"} prompt with ${codingAgent.name}.`,
   );
   try {
     const result = await executeConnectedPrompt(assignment, config, {
@@ -368,7 +411,7 @@ async function executePrompt(assignment) {
 
 async function executeAssessment(assignment) {
   const assessmentId = assignment.assessment_id;
-  console.log(`Assessing workspace with Codex CLI (${assessmentId}).`);
+  console.log(`Assessing workspace with ${codingAgent.name} (${assessmentId}).`);
   let progress = 10;
   const reportedMilestones = new Set();
   const reportProgress = (message, { milestone = true } = {}) => {
@@ -420,7 +463,7 @@ async function executeAssessment(assignment) {
         `EngineerOS rejected the assessment (${response.status}): ${await response.text()}`,
       );
     }
-    console.log("Codex workspace assessment is current in EngineerOS.");
+    console.log(`${codingAgent.name} workspace assessment is current in EngineerOS.`);
   } catch (error) {
     if (socket.readyState === WebSocket.OPEN) {
       socket.send(
@@ -441,7 +484,7 @@ async function executeAssessment(assignment) {
 
 async function execute(assignment) {
   const runId = assignment.run_id;
-  console.log(`Running Goal ${runId} with Codex CLI.`);
+  console.log(`Running Goal ${runId} with ${codingAgent.name}.`);
   let progress = 10;
   const heartbeat = setInterval(() => {
     if (socket.readyState === WebSocket.OPEN && active?.runId === runId) {
@@ -451,7 +494,7 @@ async function execute(assignment) {
           type: "run.progress",
           run_id: runId,
           progress_percent: progress,
-          message: "Codex is working",
+          message: `${codingAgent.name} is working`,
         }),
       );
     }
@@ -463,7 +506,7 @@ async function execute(assignment) {
       },
       onEvent: (event) => {
         const message =
-          event.message || event.item?.text || event.type || "Codex is working";
+          event.message || event.item?.text || event.type || `${codingAgent.name} is working`;
         if (socket.readyState === WebSocket.OPEN) {
           socket.send(
             JSON.stringify({
@@ -492,7 +535,17 @@ async function execute(assignment) {
       throw new Error(
         `EngineerOS rejected the result (${response.status}): ${await response.text()}`,
       );
-    console.log(`Run submitted. Review workspace: ${result.run_workspace}`);
+    const integration = await applyAcceptedChange(
+      config.workspace,
+      assignment.base_revision,
+      result.head_revision,
+    );
+    if (integration.applied) {
+      console.log(`Run accepted and applied to the connected repository at ${integration.revision}.`);
+    } else {
+      console.warn(`Run accepted but not applied locally. ${integration.reason}`);
+      console.warn(`The verified run workspace remains at ${result.run_workspace}.`);
+    }
   } catch (error) {
     if (!active?.cancelled && socket.readyState === WebSocket.OPEN) {
       socket.send(
@@ -525,6 +578,19 @@ function parseArgs(args) {
   return { command, positional, flags };
 }
 
+function parseAgentArgs(value) {
+  if (!value) return [];
+  try {
+    const parsed = JSON.parse(value);
+    if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) {
+      throw new Error();
+    }
+    return parsed;
+  } catch {
+    fail('--agent-args must be a JSON array, for example: --agent-args "[\\"acp\\"]"');
+  }
+}
+
 function fail(message) {
   console.error(message);
   process.exit(1);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@engineeros/connector",
-  "version": "0.5.0",
-  "description": "Connect a local Codex CLI workspace to EngineerOS over an outbound WebSocket.",
+  "version": "0.6.1",
+  "description": "Connect a local coding agent to EngineerOS, using ACP when supported.",
   "private": false,
   "type": "module",
   "license": "UNLICENSED",
@@ -15,8 +15,8 @@
   },
   "scripts": {
     "start": "node ./bin/engineeros-connector.mjs",
-    "test": "node --test",
-    "type-check": "node --check ./bin/engineeros-connector.mjs && node --check ./src/runner.mjs"
+    "test": "node --test --test-concurrency=1",
+    "type-check": "node --check ./bin/engineeros-connector.mjs && node --check ./src/connection.mjs && node --check ./src/runner.mjs"
   },
   "engines": {
     "node": ">=22"
@@ -31,5 +31,8 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.3.0"
   }
 }

package/src/acp-client.mjs

@@ -0,0 +1,105 @@
+import { spawn } from "node:child_process";
+import { Readable, Writable } from "node:stream";
+import * as acp from "@agentclientprotocol/sdk";
+
+function permissionOutcome(options = []) {
+  const selected =
+    options.find((option) => option.kind === "allow_once") ??
+    options.find((option) => option.kind === "allow_always");
+  return selected
+    ? { outcome: { outcome: "selected", optionId: selected.optionId } }
+    : { outcome: { outcome: "cancelled" } };
+}
+
+export function launchAcpAgent(workspace, prompt, config, callbacks = {}) {
+  if (!config.agent_command) {
+    throw new Error(
+      "No ACP coding agent is configured. Pair again with --agent-command and optional --agent-args JSON.",
+    );
+  }
+  const child = spawn(
+    config.agent_command,
+    Array.isArray(config.agent_args) ? config.agent_args : [],
+    {
+      cwd: workspace,
+      env: process.env,
+      shell: false,
+      stdio: ["pipe", "pipe", "pipe"],
+    },
+  );
+  let stderr = "";
+  child.stderr.setEncoding("utf8");
+  child.stderr.on("data", (chunk) => {
+    stderr += chunk;
+    callbacks.onEvent?.({
+      type: "agent.stderr",
+      message: String(chunk).trim().slice(0, 500),
+    });
+  });
+
+  const stream = acp.ndJsonStream(
+    Writable.toWeb(child.stdin),
+    Readable.toWeb(child.stdout),
+  );
+  let finalMessage = "";
+  const completed = acp
+    .client({ name: "EngineerOS" })
+    .onRequest(acp.methods.client.session.requestPermission, (ctx) =>
+      permissionOutcome(ctx.params.options),
+    )
+    .connectWith(stream, async (ctx) => {
+      const initialized = await ctx.request(acp.methods.agent.initialize, {
+        protocolVersion: acp.PROTOCOL_VERSION,
+        clientCapabilities: {},
+      });
+      callbacks.onEvent?.({
+        type: "agent.connected",
+        message: `ACP agent connected with protocol ${initialized.protocolVersion}`,
+      });
+      return ctx.buildSession(workspace).withSession(async (session) => {
+        child.engineerOsCancel = () =>
+          ctx.notify(acp.methods.agent.session.cancel, {
+            sessionId: session.sessionId,
+          });
+        void session.prompt(prompt);
+        for (;;) {
+          const message = await session.nextUpdate();
+          if (message.kind === "stop") {
+            if (message.stopReason === "error") {
+              throw new Error("The ACP agent ended the task with an error.");
+            }
+            return { finalMessage, model: "acp-agent" };
+          }
+          const update = message.update;
+          if (
+            update.sessionUpdate === "agent_message_chunk" &&
+            update.content?.type === "text"
+          ) {
+            finalMessage += update.content.text;
+          }
+          callbacks.onEvent?.({
+            type: `acp.${update.sessionUpdate}`,
+            message:
+              update.title ??
+              update.content?.text ??
+              update.status ??
+              update.sessionUpdate,
+          });
+        }
+      });
+    })
+    .catch((error) => {
+      const detail = stderr.trim().slice(-1_000);
+      throw new Error(
+        `ACP agent failed: ${error instanceof Error ? error.message : String(error)}${detail ? ` ${detail}` : ""}`,
+      );
+    })
+    .finally(() => {
+      child.kill("SIGKILL");
+      child.stdin.destroy();
+      child.stdout.destroy();
+      child.stderr.destroy();
+      child.unref();
+    });
+  return { child, completed };
+}

package/src/connection.mjs

@@ -0,0 +1,26 @@
+export function describeWebSocketError(event) {
+  return (
+    event?.error?.message ||
+    event?.message ||
+    "The WebSocket connection failed without providing an error detail."
+  );
+}
+
+export function startConnectionWatchdog(
+  socket,
+  url,
+  { timeoutMs = 15_000, onTimeout = console.error } = {},
+) {
+  const timer = setTimeout(() => {
+    onTimeout(
+      `EngineerOS did not complete the WebSocket handshake at ${url} within ${Math.round(timeoutMs / 1_000)} seconds. Check that the backend is running and the URL is reachable from this machine.`,
+    );
+    try {
+      socket.close();
+    } catch {
+      // Reconnect scheduling is owned by the caller.
+    }
+  }, timeoutMs);
+
+  return () => clearTimeout(timer);
+}

package/src/runner.mjs

@@ -11,6 +11,7 @@ import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
 import { deflateRaw } from "node:zlib";
+import { launchAcpAgent } from "./acp-client.mjs";
 
 const deflate = promisify(deflateRaw);
 const MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
@@ -94,10 +95,11 @@ export async function executeAssignment(assignment, config, callbacks) {
     assignment.run_id,
     assignment.base_revision,
   );
-  const controller = launchCodexProcess(
+  const controller = launchAgentProcess(
     runWorkspace,
     execution.prompt,
     execution.sandboxMode,
+    config,
     callbacks,
   );
   callbacks.onProcess?.(controller.child);
@@ -110,10 +112,11 @@ export async function executeAssignment(assignment, config, callbacks) {
     assignment.base_revision,
     assignment.run_id,
   );
-  const verifier = launchCodexProcess(
+  const verifier = launchAgentProcess(
     runWorkspace,
     verificationPrompt(assignment, committed.revision, committed.changedFiles),
     "read-only",
+    config,
     callbacks,
   );
   callbacks.onProcess?.(verifier.child);
@@ -135,6 +138,50 @@ export async function executeAssignment(assignment, config, callbacks) {
   };
 }
 
+export async function applyAcceptedChange(workspace, baseRevision, headRevision) {
+  const current = await run("git", ["rev-parse", "HEAD"], workspace, {
+    allowFailure: true,
+  });
+  if (current.code !== 0) {
+    return { applied: false, reason: "The connected workspace is not a Git repository." };
+  }
+  const currentHead = current.stdout.trim();
+  const alreadyApplied = await run(
+    "git",
+    ["merge-base", "--is-ancestor", headRevision, currentHead],
+    workspace,
+    { allowFailure: true },
+  );
+  if (alreadyApplied.code === 0) return { applied: true, revision: currentHead };
+  const status = await run("git", ["status", "--porcelain"], workspace);
+  if (status.stdout.trim()) {
+    return {
+      applied: false,
+      reason: `The connected workspace has uncommitted changes. Apply accepted commit ${headRevision} after preserving them.`,
+    };
+  }
+  if (currentHead !== baseRevision) {
+    return {
+      applied: false,
+      reason: `The connected branch moved from frozen base ${baseRevision} to ${currentHead}. Apply accepted commit ${headRevision} with git cherry-pick.`,
+    };
+  }
+  const applied = await run("git", ["cherry-pick", headRevision], workspace, {
+    allowFailure: true,
+  });
+  if (applied.code !== 0) {
+    await run("git", ["cherry-pick", "--abort"], workspace, {
+      allowFailure: true,
+    });
+    return {
+      applied: false,
+      reason: `The accepted commit ${headRevision} could not be applied cleanly. Apply it manually with git cherry-pick.`,
+    };
+  }
+  const integrated = await run("git", ["rev-parse", "HEAD"], workspace);
+  return { applied: true, revision: integrated.stdout.trim() };
+}
+
 async function commitRunChange(workspace, baseRevision, runId) {
   await run("git", ["add", "-A"], workspace);
   await run(
@@ -254,10 +301,11 @@ export async function executeWorkspaceAssessment(
         changeImpact.markdown,
       )
     : execution.prompt;
-  const controller = launchCodexProcess(
+  const controller = launchAgentProcess(
     config.workspace,
     prompt,
     execution.sandboxMode,
+    config,
     callbacks,
   );
   callbacks.onProcess?.(controller.child);
@@ -375,10 +423,11 @@ function boundedText(value, maximum) {
 
 export async function executeConnectedPrompt(assignment, config, callbacks) {
   const execution = connectorExecution(assignment);
-  const controller = launchCodexProcess(
+  const controller = launchAgentProcess(
     config.workspace,
     execution.prompt,
     execution.sandboxMode,
+    config,
     callbacks,
   );
   callbacks.onProcess?.(controller.child);
@@ -387,7 +436,22 @@ export async function executeConnectedPrompt(assignment, config, callbacks) {
   if (!content) {
     throw new Error("Codex completed without returning a response.");
   }
-  return { content, model: "codex-cli" };
+  return { content, model: completed.model ?? config.agent_protocol ?? "coding-agent" };
+}
+
+export async function inspectCodingAgent(config, workspace = process.cwd()) {
+  if (config.agent_protocol === "acp") {
+    if (!config.agent_command) {
+      throw new Error("ACP requires --agent-command when pairing the connector.");
+    }
+    return {
+      protocol: "acp",
+      name: config.agent_name || path.basename(config.agent_command),
+      version: "ACP v1",
+    };
+  }
+  const codex = await inspectCodexCli(workspace);
+  return { protocol: "codex", name: "Codex CLI", version: codex.version };
 }
 
 export async function inspectCodexCli(workspace = process.cwd()) {
@@ -481,6 +545,7 @@ export function connectorExecution(assignment) {
 
 export async function stopProcess(child) {
   if (!child || child.exitCode !== null) return;
+  await child.engineerOsCancel?.();
   if (process.platform === "win32") {
     await run(
       "taskkill",
@@ -658,6 +723,13 @@ function launchCodexProcess(workspace, prompt, sandbox, callbacks) {
   return { child, completed };
 }
 
+function launchAgentProcess(workspace, prompt, sandbox, config, callbacks) {
+  if (config.agent_protocol === "acp") {
+    return launchAcpAgent(workspace, prompt, config, callbacks);
+  }
+  return launchCodexProcess(workspace, prompt, sandbox, callbacks);
+}
+
 function runCodexCommand(command, args, cwd) {
   return new Promise((resolve, reject) => {
     const child = spawn(command, args, {