@engineeros/connector 0.4.1 → 0.4.6

package/README.md

@@ -36,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 = [];
@@ -134,7 +147,9 @@ async function connect() {
     if (message.type === "workspace.assessment") {
       if (
         active?.runId !== message.assessment_id &&
-        !assessments.some((candidate) => candidate.assessment_id === message.assessment_id)
+        !assessments.some(
+          (candidate) => candidate.assessment_id === message.assessment_id,
+        )
       ) {
         assessments.push(message);
       }
@@ -314,7 +329,9 @@ function pump() {
 
 async function executePrompt(assignment) {
   const promptId = assignment.prompt_id;
-  console.log(`Answering ${assignment.purpose || "project"} prompt with Codex CLI.`);
+  console.log(
+    `Answering ${assignment.purpose || "project"} prompt with Codex CLI.`,
+  );
   try {
     const result = await executeConnectedPrompt(assignment, config, {
       onProcess: (child) => {
@@ -353,8 +370,12 @@ async function executeAssessment(assignment) {
   const assessmentId = assignment.assessment_id;
   console.log(`Assessing workspace with Codex CLI (${assessmentId}).`);
   let progress = 10;
-  const reportProgress = (message) => {
-    if (socket.readyState !== WebSocket.OPEN || active?.runId !== assessmentId) return;
+  const reportedMilestones = new Set();
+  const reportProgress = (message, { milestone = true } = {}) => {
+    if (socket.readyState !== WebSocket.OPEN || active?.runId !== assessmentId)
+      return;
+    if (milestone && reportedMilestones.has(message)) return;
+    if (milestone) reportedMilestones.add(message);
     socket.send(
       JSON.stringify({
         type: "workspace.assessment.progress",
@@ -364,20 +385,23 @@ async function executeAssessment(assignment) {
       }),
     );
   };
-  reportProgress("Codex is inspecting the workspace");
+  reportProgress("Starting read-only repository assessment");
   const heartbeat = setInterval(() => {
     progress = Math.min(90, progress + 5);
-    reportProgress("Codex is building the evidence-backed assessment");
+    reportProgress("Assessment in progress", { milestone: false });
   }, 15_000);
   try {
+    if (assignment.assessment_mode === "incremental") {
+      progress = 15;
+      reportProgress("Calculating changed files and affected evidence");
+    }
     const result = await executeWorkspaceAssessment(assignment, config, {
       onProcess: (child) => {
         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.1",
+  "version": "0.4.6",
   "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";
@@ -114,17 +121,47 @@ export async function executeAssignment(assignment, config, callbacks) {
   };
 }
 
-export async function executeWorkspaceAssessment(assignment, config, callbacks) {
+export async function executeWorkspaceAssessment(
+  assignment,
+  config,
+  callbacks,
+) {
   const execution = connectorExecution(assignment);
-  const revision = await run(
+  const startingRevision = await run(
     "git",
     ["rev-parse", "HEAD"],
     config.workspace,
     { allowFailure: true },
   );
+  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 changeImpact =
+    assignment.assessment_mode === "incremental"
+      ? await workspaceChangeImpact(
+          config.workspace,
+          assignment.base_head_revision,
+          assignment.target_head_revision,
+        )
+      : { changedFiles: [], markdown: null };
+  const prompt = changeImpact.markdown
+    ? execution.prompt.replace(
+        "<!-- ENGINEEROS_CHANGE_IMPACT -->",
+        changeImpact.markdown,
+      )
+    : execution.prompt;
   const controller = launchCodexProcess(
     config.workspace,
-    execution.prompt,
+    prompt,
     execution.sandboxMode,
     callbacks,
   );
@@ -132,13 +169,115 @@ export async function executeWorkspaceAssessment(assignment, config, callbacks)
   const completed = await controller.completed;
   const report = completed.finalMessage.trim();
   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(
+      "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,
+    changed_files: changeImpact.changedFiles,
+    change_impact_markdown: changeImpact.markdown,
   };
 }
 
+export async function workspaceChangeImpact(workspace, baseRevision, targetRevision) {
+  if (!baseRevision || !targetRevision) {
+    throw new Error(
+      "Incremental assessment requires both the previously assessed and current Git commits. Run a full assessment instead.",
+    );
+  }
+  const range = `${baseRevision}..${targetRevision}`;
+  const names = await run(
+    "git",
+    ["diff", "--name-status", "--find-renames", range],
+    workspace,
+    { allowFailure: true },
+  );
+  if (names.code !== 0) {
+    throw new Error(
+      "Codex could not compare the assessed and current commits. Fetch the missing Git history or run a full assessment.",
+    );
+  }
+  const committedFiles = await run(
+    "git",
+    ["-c", "core.quotepath=false", "diff", "--name-only", range],
+    workspace,
+    { allowFailure: true },
+  );
+  const workingFiles = await run(
+    "git",
+    ["-c", "core.quotepath=false", "ls-files", "--others", "--modified", "--deleted", "--exclude-standard"],
+    workspace,
+    { allowFailure: true },
+  );
+  const status = await run("git", ["status", "--short"], workspace, {
+    allowFailure: true,
+  });
+  const stat = await run(
+    "git",
+    ["diff", "--stat", "--compact-summary", range],
+    workspace,
+    { allowFailure: true },
+  );
+  const allChangedFiles = [...new Set([
+    ...pathLines(committedFiles.stdout),
+    ...pathLines(workingFiles.stdout),
+  ])];
+  if (allChangedFiles.length > 500) {
+    throw new Error(
+      `This change affects ${allChangedFiles.length} paths, above the 500-path incremental limit. Run a full reassessment instead.`,
+    );
+  }
+  const changedFiles = allChangedFiles;
+  if (!changedFiles.length) {
+    throw new Error(
+      "The inventoried repository changed but Git reports no assessable paths. Refresh inventory or run a full assessment.",
+    );
+  }
+  const lines = [
+    `Comparison: \`${range}\``,
+    `Changed paths: ${changedFiles.length}`,
+    "",
+    "### Name status",
+    "",
+    "```text",
+    boundedText(names.stdout, 12_000),
+    "```",
+  ];
+  if (status.stdout.trim()) {
+    lines.push("", "### Working tree", "", "```text", boundedText(status.stdout, 6_000), "```");
+  }
+  if (stat.stdout.trim()) {
+    lines.push("", "### Diff summary", "", "```text", boundedText(stat.stdout, 6_000), "```");
+  }
+  return { changedFiles, markdown: lines.join("\n") };
+}
+
+function pathLines(output) {
+  return String(output || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean)
+    .map((line) => line.replace(/^"|"$/g, ""));
+}
+
+function boundedText(value, maximum) {
+  const text = String(value || "").trim();
+  return text.length <= maximum ? text : `${text.slice(0, maximum)}\n... truncated by EngineerOS`;
+}
+
 export async function executeConnectedPrompt(assignment, config, callbacks) {
   const execution = connectorExecution(assignment);
   const controller = launchCodexProcess(
@@ -156,6 +295,83 @@ 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 "Reviewing repository structure and current Git state";
+  if (event.type === "item.started") {
+    if (event.item?.type === "command_execution") {
+      return assessmentCommandMilestone(event.item.command);
+    }
+    if (event.item?.type === "mcp_tool_call")
+      return "Tracing architecture and code relationships";
+    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 "Synthesizing findings and highest-return actions";
+  }
+  return null;
+}
+
+function assessmentCommandMilestone(command) {
+  const value = Array.isArray(command)
+    ? command.join(" ")
+    : String(command || "");
+  const normalized = value.replace(/\s+/g, " ").trim().toLowerCase();
+  if (!normalized) return "Inspecting repository evidence";
+  if (/\bgit\s+(status|log|diff|show|rev-parse)\b/.test(normalized)) {
+    return "Comparing Git history and workspace changes";
+  }
+  if (
+    /\b(test|pytest|vitest|jest|ruff|eslint|tsc|build|lint)\b/.test(normalized)
+  ) {
+    return "Checking verification and delivery signals";
+  }
+  if (
+    /\b(audit|dependency|dependencies|lockfile|package-lock|pnpm-lock|requirements)\b/.test(
+      normalized,
+    )
+  ) {
+    return "Reviewing dependencies and security signals";
+  }
+  return "Tracing architecture and code relationships";
+}
+
 export function connectorExecution(assignment) {
   const prompt = assignment?.prompt_markdown;
   if (typeof prompt !== "string" || !prompt.trim()) {
@@ -292,15 +508,7 @@ 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,
@@ -349,15 +557,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",
@@ -452,7 +676,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("/");
@@ -482,7 +711,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) {