@engineeros/connector 0.4.0 → 0.4.4

package/README.md

@@ -2,6 +2,11 @@
 
 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
+execution boundary. The connector validates the assignment envelope, passes the supplied
+Markdown to Codex CLI unchanged, streams lifecycle events, and returns bounded results.
+It contains no product, assessment, planning, architecture, or delivery prompt templates.
+
 ## Onboard a workspace
 
 Create a connection command from **Project steering -> Connect workspace**, then run it inside the local folder:
@@ -31,3 +36,14 @@ Credentials are stored per workspace under `~/.engineeros/connectors` with owner
 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.
 
 Requirements: Node.js 22 or newer, Git, and an authenticated Codex CLI (`codex login`).
+
+## Codex CLI compatibility
+
+The connector prints the exact Codex CLI version it will use before connecting. If the
+configured model requires a newer CLI, update Codex and restart the connector:
+
+```sh
+npm install -g @openai/codex@latest
+codex --version
+npx @engineeros/connector start --workspace .
+```

package/bin/engineeros-connector.mjs

@@ -10,9 +10,11 @@ import {
   workspaceUrl,
 } from "../src/config.mjs";
 import {
+  assessmentProgressMessage,
   executeAssignment,
   executeConnectedPrompt,
   executeWorkspaceAssessment,
+  inspectCodexCli,
   stopProcess,
   workspaceSnapshot,
 } from "../src/runner.mjs";
@@ -73,6 +75,17 @@ if (command === "pair") {
   fail("Use `engineeros-connector pair`, `start`, or `status`.");
 }
 
+let codexCli;
+try {
+  codexCli = await inspectCodexCli(config.workspace);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}
+console.log(`Using ${codexCli.version}.`);
+if (firstMessage.type === "pair") {
+  firstMessage.capabilities.codex_cli_version = codexCli.version;
+}
+
 let stopped = false;
 let active = null;
 const available = [];
@@ -375,9 +388,8 @@ async function executeAssessment(assignment) {
         if (active?.runId === assessmentId) active.child = child;
       },
       onEvent: (event) => {
-        const message =
-          event.message || event.item?.text || event.type || "Codex is assessing the workspace";
-        reportProgress(message);
+        const message = assessmentProgressMessage(event);
+        if (message) reportProgress(message);
       },
     });
     const response = await fetch(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineeros/connector",
-  "version": "0.4.0",
+  "version": "0.4.4",
   "description": "Connect a local Codex CLI workspace to EngineerOS over an outbound WebSocket.",
   "private": false,
   "type": "module",

package/src/runner.mjs

@@ -1,6 +1,13 @@
 import { createHash } from "node:crypto";
 import { spawn } from "node:child_process";
-import { lstat, mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import {
+  lstat,
+  mkdir,
+  readFile,
+  readdir,
+  stat,
+  writeFile,
+} from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { promisify } from "node:util";
@@ -82,14 +89,16 @@ const CODE_MARKERS = new Set([
 ]);
 
 export async function executeAssignment(assignment, config, callbacks) {
+  const execution = connectorExecution(assignment);
   const runWorkspace = await prepareRunWorkspace(
     config.workspace,
     assignment.run_id,
     assignment.base_revision,
   );
-  const controller = launchCodex(
+  const controller = launchCodexProcess(
     runWorkspace,
-    assignment.packet_markdown,
+    execution.prompt,
+    execution.sandboxMode,
     callbacks,
   );
   callbacks.onProcess?.(controller.child);
@@ -112,41 +121,67 @@ export async function executeAssignment(assignment, config, callbacks) {
   };
 }
 
-export async function executeWorkspaceAssessment(assignment, config, callbacks) {
-  const revision = await run(
+export async function executeWorkspaceAssessment(
+  assignment,
+  config,
+  callbacks,
+) {
+  const execution = connectorExecution(assignment);
+  const startingRevision = await run(
     "git",
     ["rev-parse", "HEAD"],
     config.workspace,
     { allowFailure: true },
   );
-  const instruction = `${assignment.prompt_markdown}\n\n## EngineerOS execution instruction\n\nAssess the current workspace at the requested inventory revision ${assignment.source_revision}. Remain read-only. Return only the required structured Markdown assessment as your final answer.\n`;
+  const startingHead =
+    startingRevision.code === 0
+      ? startingRevision.stdout.trim().slice(0, 128)
+      : null;
+  if (
+    assignment.target_head_revision &&
+    startingHead !== assignment.target_head_revision
+  ) {
+    throw new Error(
+      "This workspace is no longer at the commit inventoried by EngineerOS. Refresh the workspace inventory before assessing it.",
+    );
+  }
   const controller = launchCodexProcess(
     config.workspace,
-    instruction,
-    "read-only",
+    execution.prompt,
+    execution.sandboxMode,
     callbacks,
   );
   callbacks.onProcess?.(controller.child);
   const completed = await controller.completed;
   const report = completed.finalMessage.trim();
-  if (!report.startsWith("# Workspace Assessment")) {
+  if (!report) throw new Error("Codex completed without returning a response.");
+  const endingRevision = await run(
+    "git",
+    ["rev-parse", "HEAD"],
+    config.workspace,
+    { allowFailure: true },
+  );
+  const endingHead =
+    endingRevision.code === 0
+      ? endingRevision.stdout.trim().slice(0, 128)
+      : null;
+  if (startingHead !== endingHead) {
     throw new Error(
-      "Codex completed without returning the required structured Workspace Assessment.",
+      "The Git commit changed during assessment. Refresh the workspace inventory and assess the new commit.",
     );
   }
   return {
     report_markdown: report,
-    observed_head_revision:
-      revision.code === 0 ? revision.stdout.trim().slice(0, 128) : null,
+    observed_head_revision: endingHead,
   };
 }
 
 export async function executeConnectedPrompt(assignment, config, callbacks) {
-  const instruction = `${assignment.prompt_markdown}\n\n## EngineerOS connector instruction\n\nAnswer this project prompt from the connected workspace. Remain read-only and return only the requested response as your final answer.\n`;
+  const execution = connectorExecution(assignment);
   const controller = launchCodexProcess(
     config.workspace,
-    instruction,
-    "read-only",
+    execution.prompt,
+    execution.sandboxMode,
     callbacks,
   );
   callbacks.onProcess?.(controller.child);
@@ -158,6 +193,82 @@ export async function executeConnectedPrompt(assignment, config, callbacks) {
   return { content, model: "codex-cli" };
 }
 
+export async function inspectCodexCli(workspace = process.cwd()) {
+  const command =
+    process.env.CODEX_BIN ||
+    (process.platform === "win32" ? "codex.cmd" : "codex");
+  const result = await runCodexCommand(command, ["--version"], workspace);
+  if (result.code !== 0) {
+    throw new Error(
+      "Codex CLI is unavailable. Install it with `npm install -g @openai/codex@latest`, run `codex login`, then restart this connector.",
+    );
+  }
+  const version = result.stdout.trim().slice(0, 100);
+  if (!version) {
+    throw new Error(
+      "Codex CLI returned no version. Reinstall @openai/codex, then restart this connector.",
+    );
+  }
+  return { command, version };
+}
+
+export function codexFailureMessage(output, code) {
+  if (/requires a newer version of Codex/i.test(output)) {
+    return (
+      "The configured model requires a newer Codex CLI. " +
+      "Run `npm install -g @openai/codex@latest`, verify with `codex --version`, " +
+      "then restart the EngineerOS connector and retry the assessment."
+    );
+  }
+  if (/not logged in|login required|authentication required/i.test(output)) {
+    return "Codex CLI is not authenticated. Run `codex login`, then restart the EngineerOS connector.";
+  }
+  return `Codex exited with code ${code}. ${output.slice(-1_000)}`;
+}
+
+export function assessmentProgressMessage(event) {
+  if (!event || typeof event !== "object") return null;
+  if (event.type === "turn.started")
+    return "Codex started analyzing repository evidence";
+  if (event.type === "item.started") {
+    if (event.item?.type === "command_execution") {
+      const command = compactCommand(event.item.command);
+      return command
+        ? `Inspecting with ${command}`
+        : "Inspecting repository files";
+    }
+    if (event.item?.type === "mcp_tool_call")
+      return "Consulting a connected analysis tool";
+    if (event.item?.type === "web_search")
+      return "Checking an external technical reference";
+    return null;
+  }
+  if (event.type === "item.completed" && event.item?.type === "agent_message") {
+    return "Assessment report prepared";
+  }
+  return null;
+}
+
+function compactCommand(command) {
+  const value = Array.isArray(command)
+    ? command.join(" ")
+    : String(command || "");
+  const compact = value.replace(/\s+/g, " ").trim();
+  return compact.length > 96 ? `${compact.slice(0, 93)}...` : compact;
+}
+
+export function connectorExecution(assignment) {
+  const prompt = assignment?.prompt_markdown;
+  if (typeof prompt !== "string" || !prompt.trim()) {
+    throw new Error("EngineerOS assignment is missing prompt_markdown.");
+  }
+  const sandboxMode = assignment?.sandbox_mode;
+  if (!new Set(["read-only", "workspace-write"]).has(sandboxMode)) {
+    throw new Error("EngineerOS assignment has an unsupported sandbox_mode.");
+  }
+  return { prompt, sandboxMode };
+}
+
 export async function stopProcess(child) {
   if (!child || child.exitCode !== null) return;
   if (process.platform === "win32") {
@@ -278,24 +389,11 @@ async function prepareRunWorkspace(workspace, runId, baseRevision) {
   return target;
 }
 
-function launchCodex(workspace, packet, callbacks) {
-  const prompt = `${packet}\n\n## EngineerOS execution instruction\n\nImplement this frozen Goal completely in the current run workspace. Run the required verification. Do not commit, push, or modify files outside this workspace. End with a concise result and verification summary.\n`;
-  return launchCodexProcess(workspace, prompt, "workspace-write", callbacks);
-}
-
 function launchCodexProcess(workspace, prompt, sandbox, callbacks) {
   const command =
     process.env.CODEX_BIN ||
     (process.platform === "win32" ? "codex.cmd" : "codex");
-  const args = [
-    "exec",
-    "--json",
-    "--sandbox",
-    sandbox,
-    "-C",
-    workspace,
-    "-",
-  ];
+  const args = ["exec", "--json", "--sandbox", sandbox, "-C", workspace, "-"];
   const child = spawn(command, args, {
     cwd: workspace,
     env: process.env,
@@ -344,15 +442,31 @@ function launchCodexProcess(workspace, prompt, sandbox, callbacks) {
     child.once("error", reject);
     child.once("close", (code) => {
       if (code === 0) resolve({ output: output.slice(-20_000), finalMessage });
-      else
-        reject(
-          new Error(`Codex exited with code ${code}. ${output.slice(-1_000)}`),
-        );
+      else reject(new Error(codexFailureMessage(output, code)));
     });
   });
   return { child, completed };
 }
 
+function runCodexCommand(command, args, cwd) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+      cwd,
+      env: process.env,
+      shell: process.platform === "win32",
+      windowsHide: true,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => (stdout += chunk));
+    child.stderr.on("data", (chunk) => (stderr += chunk));
+    child.once("error", reject);
+    child.once("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+  });
+}
+
 async function changedFilePaths(workspace) {
   const tracked = await run(
     "git",
@@ -447,7 +561,12 @@ async function workspaceFiles(root, current = root) {
 
 function isShareablePath(relative) {
   const normalized = normalizePath(relative);
-  if (!normalized || normalized === ".." || normalized.startsWith("../") || path.isAbsolute(normalized)) {
+  if (
+    !normalized ||
+    normalized === ".." ||
+    normalized.startsWith("../") ||
+    path.isAbsolute(normalized)
+  ) {
     return false;
   }
   const parts = normalized.split("/");
@@ -477,7 +596,9 @@ function isShareablePath(relative) {
 
 function isCodeBearing(relative) {
   const name = path.posix.basename(relative).toLowerCase();
-  return CODE_MARKERS.has(name) || CODE_EXTENSIONS.has(path.posix.extname(name));
+  return (
+    CODE_MARKERS.has(name) || CODE_EXTENSIONS.has(path.posix.extname(name))
+  );
 }
 
 async function worktreeBase(workspace, requested) {