@engineeros/connector 0.2.1 → 0.4.1

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:
@@ -10,7 +15,11 @@ Create a connection command from **Project steering -> Connect workspace**, then
 npx --yes @engineeros/connector@latest pair PAIRING-CODE --url https://your-engineeros.example --workspace . --onboard
 ```
 
-The connector uploads a bounded ZIP snapshot for assessment, then stays online for rescans and Goal Runs. Onboarding 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.
+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.
+
+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.
 
 An empty or document-only folder establishes a greenfield baseline. A code-bearing folder is assessed as brownfield. Use **Rescan** in Steering after the local workspace changes.
 

package/bin/engineeros-connector.mjs

@@ -2,6 +2,7 @@
 import os from "node:os";
 import path from "node:path";
 import {
+  assessmentResultUrl,
   loadConfig,
   resultUrl,
   saveConfig,
@@ -10,6 +11,8 @@ import {
 } from "../src/config.mjs";
 import {
   executeAssignment,
+  executeConnectedPrompt,
+  executeWorkspaceAssessment,
   stopProcess,
   workspaceSnapshot,
 } from "../src/runner.mjs";
@@ -73,6 +76,8 @@ if (command === "pair") {
 let stopped = false;
 let active = null;
 const available = [];
+const assessments = [];
+const prompts = [];
 let socket;
 let pingTimer;
 let reconnectDelay = 1_000;
@@ -126,6 +131,37 @@ async function connect() {
       void submitWorkspaceSnapshot();
       return;
     }
+    if (message.type === "workspace.assessment") {
+      if (
+        active?.runId !== message.assessment_id &&
+        !assessments.some((candidate) => candidate.assessment_id === message.assessment_id)
+      ) {
+        assessments.push(message);
+      }
+      pump();
+      return;
+    }
+    if (message.type === "prompt.execute") {
+      if (
+        active?.runId !== message.prompt_id &&
+        !prompts.some((candidate) => candidate.prompt_id === message.prompt_id)
+      ) {
+        prompts.push(message);
+      }
+      pump();
+      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);
+      }
+      return;
+    }
     if (message.type === "run.available") {
       if (!available.includes(message.run_id)) available.push(message.run_id);
       pump();
@@ -162,6 +198,10 @@ async function connect() {
   });
   socket.addEventListener("close", () => {
     clearInterval(pingTimer);
+    if (active?.kind === "prompt") {
+      active.cancelled = true;
+      void stopProcess(active.child);
+    }
     if (connectionRejected) {
       stopped = true;
       console.error(
@@ -226,7 +266,7 @@ function startPings() {
       socket.send(
         JSON.stringify({
           type: "ping",
-          active_run_id: active?.runId ?? null,
+          active_run_id: active?.kind === "goal" ? active.runId : null,
         }),
       );
     }
@@ -235,9 +275,30 @@ function startPings() {
 
 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 = {
+      kind: "assessment",
+      runId: assessment.assessment_id,
+      child: null,
+    };
+    void executeAssessment(assessment);
+    return;
+  }
   const runId = available.shift();
   if (!runId) return;
-  active = { runId, child: null, cancelled: false };
+  active = { kind: "goal", runId, child: null, cancelled: false };
   socket.send(
     JSON.stringify({
       type: "run.claim",
@@ -251,6 +312,109 @@ function pump() {
   );
 }
 
+async function executePrompt(assignment) {
+  const promptId = assignment.prompt_id;
+  console.log(`Answering ${assignment.purpose || "project"} prompt with Codex CLI.`);
+  try {
+    const result = await executeConnectedPrompt(assignment, config, {
+      onProcess: (child) => {
+        if (active?.runId === promptId) active.child = child;
+      },
+    });
+    if (active?.cancelled || socket.readyState !== WebSocket.OPEN) return;
+    socket.send(
+      JSON.stringify({
+        type: "prompt.completed",
+        prompt_id: promptId,
+        content: result.content,
+        model: result.model,
+      }),
+    );
+  } catch (error) {
+    if (!active?.cancelled && socket.readyState === WebSocket.OPEN) {
+      socket.send(
+        JSON.stringify({
+          type: "prompt.failed",
+          prompt_id: promptId,
+          message: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    }
+    if (!active?.cancelled) {
+      console.error(error instanceof Error ? error.message : String(error));
+    }
+  } finally {
+    active = null;
+    pump();
+  }
+}
+
+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;
+    socket.send(
+      JSON.stringify({
+        type: "workspace.assessment.progress",
+        assessment_id: assessmentId,
+        progress_percent: progress,
+        message: String(message).slice(0, 500),
+      }),
+    );
+  };
+  reportProgress("Codex is inspecting the workspace");
+  const heartbeat = setInterval(() => {
+    progress = Math.min(90, progress + 5);
+    reportProgress("Codex is building the evidence-backed assessment");
+  }, 15_000);
+  try {
+    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 response = await fetch(
+      assessmentResultUrl(config.server_url, config.connector_id, assessmentId),
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${config.token}`,
+        },
+        body: JSON.stringify(result),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(
+        `EngineerOS rejected the assessment (${response.status}): ${await response.text()}`,
+      );
+    }
+    console.log("Codex workspace assessment is current in EngineerOS.");
+  } catch (error) {
+    if (socket.readyState === WebSocket.OPEN) {
+      socket.send(
+        JSON.stringify({
+          type: "workspace.assessment.failed",
+          assessment_id: assessmentId,
+          message: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    }
+    console.error(error instanceof Error ? error.message : String(error));
+  } finally {
+    clearInterval(heartbeat);
+    active = null;
+    pump();
+  }
+}
+
 async function execute(assignment) {
   const runId = assignment.run_id;
   console.log(`Running Goal ${runId} with Codex CLI.`);

package/package.json

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

package/src/config.mjs

@@ -38,6 +38,13 @@ export function workspaceUrl(websocketUrl, connectorId) {
   return url.toString();
 }
 
+export function assessmentResultUrl(websocketUrl, connectorId, assessmentId) {
+  const url = new URL(websocketUrl);
+  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
+  url.pathname = `/api/v1/agent-connectors/${connectorId}/assessment/${assessmentId}/result`;
+  return url.toString();
+}
+
 export async function loadConfig(workspace = process.cwd()) {
   try {
     return JSON.parse(await readFile(configPath(workspace), "utf8"));

package/src/runner.mjs

@@ -82,14 +82,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,6 +114,60 @@ export async function executeAssignment(assignment, config, callbacks) {
   };
 }
 
+export async function executeWorkspaceAssessment(assignment, config, callbacks) {
+  const execution = connectorExecution(assignment);
+  const revision = await run(
+    "git",
+    ["rev-parse", "HEAD"],
+    config.workspace,
+    { allowFailure: true },
+  );
+  const controller = launchCodexProcess(
+    config.workspace,
+    execution.prompt,
+    execution.sandboxMode,
+    callbacks,
+  );
+  callbacks.onProcess?.(controller.child);
+  const completed = await controller.completed;
+  const report = completed.finalMessage.trim();
+  if (!report) throw new Error("Codex completed without returning a response.");
+  return {
+    report_markdown: report,
+    observed_head_revision:
+      revision.code === 0 ? revision.stdout.trim().slice(0, 128) : null,
+  };
+}
+
+export async function executeConnectedPrompt(assignment, config, callbacks) {
+  const execution = connectorExecution(assignment);
+  const controller = launchCodexProcess(
+    config.workspace,
+    execution.prompt,
+    execution.sandboxMode,
+    callbacks,
+  );
+  callbacks.onProcess?.(controller.child);
+  const completed = await controller.completed;
+  const content = completed.finalMessage.trim();
+  if (!content) {
+    throw new Error("Codex completed without returning a response.");
+  }
+  return { content, model: "codex-cli" };
+}
+
+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") {
@@ -232,7 +288,7 @@ async function prepareRunWorkspace(workspace, runId, baseRevision) {
   return target;
 }
 
-function launchCodex(workspace, packet, callbacks) {
+function launchCodexProcess(workspace, prompt, sandbox, callbacks) {
   const command =
     process.env.CODEX_BIN ||
     (process.platform === "win32" ? "codex.cmd" : "codex");
@@ -240,7 +296,7 @@ function launchCodex(workspace, packet, callbacks) {
     "exec",
     "--json",
     "--sandbox",
-    "workspace-write",
+    sandbox,
     "-C",
     workspace,
     "-",
@@ -251,10 +307,10 @@ function launchCodex(workspace, packet, callbacks) {
     shell: process.platform === "win32",
     stdio: ["pipe", "pipe", "pipe"],
   });
-  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`;
   child.stdin.end(prompt);
   let output = "";
   let buffer = "";
+  let finalMessage = "";
   child.stdout.setEncoding("utf8");
   child.stdout.on("data", (chunk) => {
     output += chunk;
@@ -265,6 +321,13 @@ function launchCodex(workspace, packet, callbacks) {
       if (!line.trim()) continue;
       try {
         const event = JSON.parse(line);
+        if (
+          event.type === "item.completed" &&
+          event.item?.type === "agent_message" &&
+          typeof event.item.text === "string"
+        ) {
+          finalMessage = event.item.text;
+        }
         callbacks.onEvent?.(event);
       } catch {
         callbacks.onEvent?.({
@@ -285,7 +348,7 @@ function launchCodex(workspace, packet, callbacks) {
   const completed = new Promise((resolve, reject) => {
     child.once("error", reject);
     child.once("close", (code) => {
-      if (code === 0) resolve(output.slice(-20_000));
+      if (code === 0) resolve({ output: output.slice(-20_000), finalMessage });
       else
         reject(
           new Error(`Codex exited with code ${code}. ${output.slice(-1_000)}`),