@engineeros/connector 0.8.8 → 0.8.9

package/README.md

@@ -1,6 +1,18 @@
 # 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.
+The connector uses an authenticated EngineerOS WebSocket for pairing, workspace identity, run lifecycle, and evidence. Coding work can run through any agent in the official ACP registry or a custom ACP v1-compatible command over stdio. Direct Codex CLI remains available as the compatibility path.
+
+## Connect an official ACP agent
+
+EngineerOS reads the curated [ACP agent registry](https://agentclientprotocol.com/registry), caches it for 24 hours, and uses the registry's pinned distribution for the current platform. The catalog includes Codex, Claude, Gemini, GitHub Copilot, Goose, OpenCode, Qwen Code, Cursor, and other compatible agents as they are published. List the current catalog, prepare the selected agent, then pair the workspace:
+
+```sh
+npx --yes @engineeros/connector@latest agents
+npx --yes @engineeros/connector@latest agent gemini install
+npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard --agent gemini
+```
+
+Registry `npx` and `uvx` packages are prepared with their native package runner. Registry binaries are downloaded into `~/.engineeros/agents`, checked against the published SHA-256 digest when present, and launched from that managed location. The connector checks the selected distribution before pairing. Agent processes stay alive while the connector is active, project conversations reuse their ACP sessions, and response chunks reach Copilot as the agent produces them.
 
 ## Pair an ACP coding agent
 
@@ -10,7 +22,7 @@ Run the command from the repository the agent should work in:
 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.
+`--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 `--agent` and the custom command options to use the installed Codex CLI directly.
 
 Connect a local Codex CLI workspace to EngineerOS through an outbound WebSocket.
 
@@ -29,9 +41,9 @@ npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engi
 
 The connector uploads a bounded ZIP snapshot for a safe file inventory, then stays online for deep assessments, rescans, and Goal Runs. Inventory never executes repository code. It excludes known secrets, dependency directories, build output, compiled binaries, files larger than 5 MB, agent-tool caches, Git metadata, and connector state before upload.
 
-From **Project steering -> Workspace**, choose **Assess with Codex** to run a read-only engineering assessment using the Codex CLI subscription already authenticated on that computer. EngineerOS stores the source-cited findings in System State and promotes the highest-return corrective action in Steering. Assessment cannot modify the workspace.
+From **Project steering -> Workspace**, run the workspace assessment to use the connected agent subscription already authenticated on that computer. EngineerOS stores the source-cited findings in System State and promotes the highest-return corrective action in Steering. Assessment cannot modify the workspace.
 
-After onboarding, every project prompt is routed to this connection. Copilot, shaping, planning, architecture, and experience generation use the Codex CLI subscription and connected workspace context. Prompt runs are read-only; only an explicitly registered Goal Run receives workspace-write access. If the connector is offline, EngineerOS asks the user to reconnect instead of silently switching models.
+After onboarding, every project prompt is routed to this connection. Copilot, shaping, planning, architecture, and experience generation use the connected agent subscription and workspace context. Interactive prompts run independently from assessments and Goal scheduling. Prompt runs are read-only; only an explicitly registered Goal Run receives workspace-write access. If the connector is offline, EngineerOS asks the user to reconnect instead of silently switching models.
 
 Project prompts use resumable, purpose-specific coding-agent sessions. The connector keeps the external session identifiers in its local configuration, so Copilot and artifact conversations survive connector restarts. Changing the purpose, model, or reasoning effort starts a separate session. Goal implementation and verification remain isolated runs.
 
@@ -48,11 +60,11 @@ If a new pairing command is accidentally run from the same folder against the sa
 
 ## Run Goals
 
-Keep the connector online to receive Goals assigned from EngineerOS. Each Goal runs in an isolated worktree below `~/.engineeros/runs`. Cancellation stops Codex. The connector returns changed paths, a bounded diff, and the exact repository ZIP; a human still performs independent attestation.
+Keep the connector online to receive Goals assigned from EngineerOS. Each Goal runs in an isolated worktree below `~/.engineeros/runs`. Cancellation stops the agent. The connector returns changed paths, a bounded diff, and the exact repository ZIP; a human still performs independent attestation.
 
 During the writable implementation phase, Codex receives an authenticated EngineerOS MCP server automatically. It can list, read, create, update, reclassify, soft-delete, and materialize project artifacts into canonical Product records through the same repository boundary used by Copilot. The backend accepts those calls only while the assigned Goal is running. Read-only project prompts and the independent verification phase do not receive mutation tools.
 
-Requirements: Node.js 22 or newer, Git, and an authenticated Codex CLI (`codex login`).
+Requirements: Node.js 22 or newer, Git, and an authenticated agent. `npx` distributions use npm, `uvx` distributions require uv, and binary archives require `tar` (`unzip` for ZIP files on Linux). Registry agents report their own authentication prerequisites when they start.
 
 ## Execution profiles
 

package/bin/engineeros-connector.mjs

@@ -18,11 +18,17 @@ import {
   executeConnectedPrompt,
   executeWorkspaceAssessment,
   inspectCodingAgent,
-  promptProgressMessage,
-  promptQueueMessage,
+  promptStreamEvent,
   stopProcess,
   workspaceSnapshot,
 } from "../src/runner.mjs";
+import { disposeAcpRuntimes } from "../src/acp-client.mjs";
+import {
+  installRegisteredAgent,
+  inspectRegisteredAgent,
+  registeredAgentConfig,
+  registeredAgents,
+} from "../src/agent-registry.mjs";
 import {
   describeWebSocketError,
   startConnectionWatchdog,
@@ -32,13 +38,60 @@ import { parseConnectorArgs } from "../src/cli-args.mjs";
 import { runMcpServer } from "../src/mcp-server.mjs";
 import packageJson from "../package.json" with { type: "json" };
 
-const { command, positional, flags } = parseConnectorArgs(process.argv.slice(2));
+const { command, positional, flags } = parseConnectorArgs(
+  process.argv.slice(2),
+);
+
+if (command === "agents") {
+  let agents;
+  try {
+    agents = await registeredAgents();
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  const statuses = await Promise.all(
+    agents.map(async (agent) => {
+      try {
+        await inspectRegisteredAgent(agent.id);
+        return `${agent.id}: ready (${agent.name} ${agent.version}, ${agent.distribution_type})`;
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return `${agent.id}: setup needed (${agent.name} ${agent.version}, ${agent.distribution_type}) - ${detail}`;
+      }
+    }),
+  );
+  for (const status of statuses) {
+    console.log(status);
+  }
+  process.exit(0);
+}
+
+if (command === "agent") {
+  const agentId = positional[0];
+  const action = positional[1] || "check";
+  if (!agentId || !["check", "install"].includes(action)) {
+    fail("Usage: engineeros-connector agent AGENT_ID [check|install]");
+  }
+  try {
+    const installed =
+      action === "install"
+        ? await installRegisteredAgent(agentId)
+        : await inspectRegisteredAgent(agentId);
+    console.log(
+      `${installed.name} is ready (${installed.version}, ${installed.distribution}).`,
+    );
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  process.exit(0);
+}
 
 if (command === "mcp") {
   const config = await loadConfig(flags.workspace || process.cwd());
   if (!config) fail("This workspace is not paired with EngineerOS.");
   const runId = flags["run-id"] || positional[0];
-  if (!runId) fail("Usage: engineeros-connector mcp --run-id RUN_ID [--workspace PATH]");
+  if (!runId)
+    fail("Usage: engineeros-connector mcp --run-id RUN_ID [--workspace PATH]");
   await runMcpServer({
     config,
     runId,
@@ -66,10 +119,22 @@ if (command === "pair") {
   const pairingCode = positional[0];
   if (!pairingCode)
     fail(
-      "Usage: engineeros-connector pair CODE --url URL [--name NAME] [--workspace PATH] [--skip-git-repo-check]",
+      "Usage: engineeros-connector pair CODE --url URL [--agent AGENT_ID] [--name NAME] [--workspace PATH] [--skip-git-repo-check]",
     );
   const url = flags.url;
   if (!url) fail("Pairing requires --url with the EngineerOS backend address.");
+  if (flags.agent && flags["agent-command"]) {
+    fail("Use either --agent or --agent-command, not both.");
+  }
+  let agentConfig = {};
+  try {
+    if (flags.agent) {
+      await inspectRegisteredAgent(flags.agent);
+      agentConfig = await registeredAgentConfig(flags.agent);
+    }
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
   config = {
     server_url: socketUrl(url),
     workspace: path.resolve(flags.workspace || process.cwd()),
@@ -79,6 +144,7 @@ if (command === "pair") {
     agent_command: flags["agent-command"] || null,
     agent_args: parseAgentArgs(flags["agent-args"]),
     agent_name: flags["agent-name"] || null,
+    ...agentConfig,
     skip_git_repo_check: flags["skip-git-repo-check"] === true,
     name:
       flags.name ||
@@ -104,7 +170,9 @@ if (command === "pair") {
     token: config.token,
   };
 } else {
-  fail("Use `engineeros-connector pair`, `start`, `status`, or `mcp`.");
+  fail(
+    "Use `engineeros-connector pair`, `start`, `status`, `agents`, `agent`, or `mcp`.",
+  );
 }
 
 let codingAgent;
@@ -113,7 +181,9 @@ try {
 } catch (error) {
   fail(error instanceof Error ? error.message : String(error));
 }
-console.log(`Using ${codingAgent.name} through ${codingAgent.protocol} (${codingAgent.version}).`);
+console.log(
+  `Using ${codingAgent.name} through ${codingAgent.protocol} (${codingAgent.version}).`,
+);
 const capabilities = advertisedCapabilities(config, codingAgent);
 firstMessage.capabilities = capabilities;
 
@@ -121,7 +191,7 @@ let stopped = false;
 let active = null;
 const available = [];
 const assessments = [];
-const prompts = [];
+const activePrompts = new Map();
 let socket;
 let pingTimer;
 let reconnectTimer;
@@ -137,6 +207,8 @@ process.on("SIGINT", async () => {
   clearTimeout(reconnectTimer);
   clearInterval(pingTimer);
   await stopProcess(active?.child);
+  await Promise.all([...activePrompts.values()].map(cancelPrompt));
+  await disposeAcpRuntimes();
   socket?.close();
   process.exit(0);
 });
@@ -212,29 +284,12 @@ async function connect() {
       return;
     }
     if (message.type === "prompt.execute") {
-      let added = false;
-      if (
-        active?.runId !== message.prompt_id &&
-        !prompts.some((candidate) => candidate.prompt_id === message.prompt_id)
-      ) {
-        prompts.push(message);
-        added = true;
-      }
-      if (added && active) {
-        sendPromptProgress(message.prompt_id, promptQueueMessage(active.kind));
-      }
-      pump();
+      if (!activePrompts.has(message.prompt_id)) void executePrompt(message);
       return;
     }
     if (message.type === "prompt.cancel") {
-      const queued = prompts.findIndex(
-        (candidate) => candidate.prompt_id === message.prompt_id,
-      );
-      if (queued >= 0) prompts.splice(queued, 1);
-      if (active?.kind === "prompt" && active.runId === message.prompt_id) {
-        active.cancelled = true;
-        await stopProcess(active.child);
-      }
+      const promptState = activePrompts.get(message.prompt_id);
+      if (promptState) await cancelPrompt(promptState);
       return;
     }
     if (message.type === "run.available") {
@@ -274,10 +329,8 @@ async function connect() {
   socket.addEventListener("close", (event) => {
     clearConnectionWatchdog?.();
     clearInterval(pingTimer);
-    if (active?.kind === "prompt") {
-      active.cancelled = true;
-      void stopProcess(active.child);
-    }
+    for (const promptState of activePrompts.values())
+      void cancelPrompt(promptState);
     if (event.code === 4001 && active?.kind === "assessment") {
       void stopProcess(active.child);
     }
@@ -301,7 +354,9 @@ async function connect() {
 
 function scheduleReconnect() {
   if (stopped || connectionRejected || reconnectTimer) return;
-  const detail = lastConnectionError ? ` Last error: ${lastConnectionError}` : "";
+  const detail = lastConnectionError
+    ? ` Last error: ${lastConnectionError}`
+    : "";
   console.error(
     `Connection unavailable.${detail} Retrying in ${Math.round(reconnectDelay / 1_000)}s.`,
   );
@@ -366,30 +421,21 @@ function startPings() {
   }, 10_000);
 }
 
-function sendPromptProgress(promptId, message) {
-  if (!message || socket.readyState !== WebSocket.OPEN) return;
-  socket.send(
-    JSON.stringify({
-      type: "prompt.progress",
-      prompt_id: promptId,
-      message: String(message).slice(0, 500),
-    }),
-  );
+function sendPromptEvent(promptId, event) {
+  if (!event || socket.readyState !== WebSocket.OPEN) return;
+  const payload = {
+    type: "prompt.event",
+    prompt_id: promptId,
+    kind: event.kind,
+  };
+  if (event.message) payload.message = String(event.message).slice(0, 500);
+  if (event.delta) payload.delta = String(event.delta).slice(0, 50_000);
+  if (event.status) payload.status = String(event.status).slice(0, 100);
+  socket.send(JSON.stringify(payload));
 }
 
 function pump() {
   if (active || socket.readyState !== WebSocket.OPEN) return;
-  const prompt = prompts.shift();
-  if (prompt) {
-    active = {
-      kind: "prompt",
-      runId: prompt.prompt_id,
-      child: null,
-      cancelled: false,
-    };
-    void executePrompt(prompt);
-    return;
-  }
   const assessment = assessments.shift();
   if (assessment) {
     active = {
@@ -418,36 +464,56 @@ function pump() {
 
 async function executePrompt(assignment) {
   const promptId = assignment.prompt_id;
-  let lastProgressMessage;
-  const reportProgress = (message) => {
+  const promptState = {
+    runId: promptId,
+    child: null,
+    controller: null,
+    cancelled: false,
+  };
+  activePrompts.set(promptId, promptState);
+  let lastEvent;
+  const reportEvent = (event) => {
+    const serialized = event ? JSON.stringify(event) : null;
     if (
-      !message ||
-      message === lastProgressMessage ||
+      !serialized ||
+      serialized === lastEvent ||
       socket.readyState !== WebSocket.OPEN ||
-      active?.runId !== promptId
+      activePrompts.get(promptId) !== promptState
     ) {
       return;
     }
-    lastProgressMessage = message;
-    sendPromptProgress(promptId, message);
+    lastEvent = serialized;
+    sendPromptEvent(promptId, event);
   };
-  sendPromptProgress(promptId, "Agent started this request");
+  sendPromptEvent(promptId, {
+    kind: "status",
+    message: "Agent started this request",
+  });
   console.log(
     `Answering ${assignment.purpose || "project"} prompt with ${codingAgent.name}.`,
   );
   try {
     const result = await executeConnectedPrompt(assignment, config, {
       onProcess: (child) => {
-        if (active?.runId === promptId) active.child = child;
+        if (activePrompts.get(promptId) === promptState)
+          promptState.child = child;
       },
-      onEvent: (event) => reportProgress(promptProgressMessage(event)),
+      onController: (controller) => {
+        if (activePrompts.get(promptId) === promptState) {
+          promptState.controller = controller;
+        }
+      },
+      onEvent: (event) => reportEvent(promptStreamEvent(event)),
     });
     config = {
       ...config,
-      sessions: { ...(config.sessions || {}), [result.sessionKey]: result.sessionId },
+      sessions: {
+        ...(config.sessions || {}),
+        [result.sessionKey]: result.sessionId,
+      },
     };
     await saveConfig(config);
-    if (active?.cancelled || socket.readyState !== WebSocket.OPEN) return;
+    if (promptState.cancelled || socket.readyState !== WebSocket.OPEN) return;
     socket.send(
       JSON.stringify({
         type: "prompt.completed",
@@ -458,7 +524,7 @@ async function executePrompt(assignment) {
       }),
     );
   } catch (error) {
-    if (!active?.cancelled && socket.readyState === WebSocket.OPEN) {
+    if (!promptState.cancelled && socket.readyState === WebSocket.OPEN) {
       socket.send(
         JSON.stringify({
           type: "prompt.failed",
@@ -467,18 +533,29 @@ async function executePrompt(assignment) {
         }),
       );
     }
-    if (!active?.cancelled) {
+    if (!promptState.cancelled) {
       console.error(error instanceof Error ? error.message : String(error));
     }
   } finally {
-    active = null;
-    pump();
+    if (activePrompts.get(promptId) === promptState)
+      activePrompts.delete(promptId);
+  }
+}
+
+async function cancelPrompt(promptState) {
+  promptState.cancelled = true;
+  if (typeof promptState.controller?.cancel === "function") {
+    await promptState.controller.cancel();
+    return;
   }
+  await stopProcess(promptState.child);
 }
 
 async function executeAssessment(assignment) {
   const assessmentId = assignment.assessment_id;
-  console.log(`Assessing workspace with ${codingAgent.name} (${assessmentId}).`);
+  console.log(
+    `Assessing workspace with ${codingAgent.name} (${assessmentId}).`,
+  );
   let progress = 10;
   const reportedMilestones = new Set();
   const reportProgress = (message, { milestone = true } = {}) => {
@@ -530,7 +607,9 @@ async function executeAssessment(assignment) {
         `EngineerOS rejected the assessment (${response.status}): ${await response.text()}`,
       );
     }
-    console.log(`${codingAgent.name} 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(
@@ -561,7 +640,7 @@ async function execute(assignment) {
           type: "run.progress",
           run_id: runId,
           progress_percent: progress,
-          message: `${codingAgent.name} is working`,
+          message: "Agent is working",
         }),
       );
     }
@@ -573,7 +652,7 @@ async function execute(assignment) {
       },
       onEvent: (event) => {
         const message =
-          event.message || event.item?.text || event.type || `${codingAgent.name} is working`;
+          event.message || event.item?.text || event.type || "Agent is working";
         if (socket.readyState === WebSocket.OPEN) {
           socket.send(
             JSON.stringify({
@@ -608,10 +687,16 @@ async function execute(assignment) {
       result.head_revision,
     );
     if (integration.applied) {
-      console.log(`Run accepted and applied to the connected repository at ${integration.revision}.`);
+      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}.`);
+      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) {
@@ -636,12 +721,17 @@ function parseAgentArgs(value) {
   if (!value) return [];
   try {
     const parsed = JSON.parse(value);
-    if (!Array.isArray(parsed) || parsed.some((item) => typeof item !== "string")) {
+    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\\"]"');
+    fail(
+      '--agent-args must be a JSON array, for example: --agent-args "[\\"acp\\"]"',
+    );
   }
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineeros/connector",
-  "version": "0.8.8",
+  "version": "0.8.9",
   "description": "Connect a local coding agent to EngineerOS, using ACP when supported.",
   "private": false,
   "type": "module",
@@ -16,7 +16,7 @@
   "scripts": {
     "start": "node ./bin/engineeros-connector.mjs",
     "test": "node --test --test-concurrency=1",
-    "type-check": "node --check ./bin/engineeros-connector.mjs && node --check ./src/capabilities.mjs && node --check ./src/cli-args.mjs && node --check ./src/connection.mjs && node --check ./src/mcp-server.mjs && node --check ./src/runner.mjs"
+    "type-check": "node --check ./bin/engineeros-connector.mjs && node --check ./src/acp-client.mjs && node --check ./src/agent-registry.mjs && node --check ./src/capabilities.mjs && node --check ./src/cli-args.mjs && node --check ./src/config.mjs && node --check ./src/connection.mjs && node --check ./src/mcp-server.mjs && node --check ./src/runner.mjs"
   },
   "engines": {
     "node": ">=22"