@engineeros/connector 0.2.0 → 0.4.0

package/README.md

@@ -10,7 +10,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, 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.0",
+  "version": "0.4.0",
   "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

@@ -8,9 +8,15 @@ import { deflateRaw } from "node:zlib";
 
 const deflate = promisify(deflateRaw);
 const MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
+const MAX_SHAREABLE_FILE_BYTES = 5 * 1024 * 1024;
 const MAX_WORKSPACE_FILES = 5_000;
 const EXCLUDED_DIRECTORIES = new Set([
+  ".agents",
+  ".claude",
+  ".codex",
   ".engineeros",
+  ".forge",
+  ".gemini",
   ".git",
   ".next",
   ".pytest_cache",
@@ -24,6 +30,29 @@ const EXCLUDED_DIRECTORIES = new Set([
   "target",
   "vendor",
 ]);
+const EXCLUDED_PATH_PREFIXES = [".github/skills/"];
+const EXCLUDED_FILE_EXTENSIONS = new Set([
+  ".7z",
+  ".a",
+  ".bin",
+  ".class",
+  ".dll",
+  ".dylib",
+  ".exe",
+  ".gz",
+  ".jar",
+  ".lib",
+  ".o",
+  ".obj",
+  ".pyc",
+  ".pyo",
+  ".rar",
+  ".so",
+  ".tar",
+  ".tgz",
+  ".war",
+  ".zip",
+]);
 const CODE_EXTENSIONS = new Set([
   ".c",
   ".cpp",
@@ -83,6 +112,52 @@ export async function executeAssignment(assignment, config, callbacks) {
   };
 }
 
+export async function executeWorkspaceAssessment(assignment, config, callbacks) {
+  const revision = 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 controller = launchCodexProcess(
+    config.workspace,
+    instruction,
+    "read-only",
+    callbacks,
+  );
+  callbacks.onProcess?.(controller.child);
+  const completed = await controller.completed;
+  const report = completed.finalMessage.trim();
+  if (!report.startsWith("# Workspace Assessment")) {
+    throw new Error(
+      "Codex completed without returning the required structured Workspace Assessment.",
+    );
+  }
+  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 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 controller = launchCodexProcess(
+    config.workspace,
+    instruction,
+    "read-only",
+    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 async function stopProcess(child) {
   if (!child || child.exitCode !== null) return;
   if (process.platform === "win32") {
@@ -123,6 +198,10 @@ export async function workspaceSnapshot(workspace) {
       excludedFileCount += 1;
       continue;
     }
+    if (details.size > MAX_SHAREABLE_FILE_BYTES) {
+      excludedFileCount += 1;
+      continue;
+    }
     totalBytes += details.size;
     if (totalBytes > MAX_ARCHIVE_BYTES) {
       throw new Error(
@@ -200,6 +279,11 @@ async function prepareRunWorkspace(workspace, runId, baseRevision) {
 }
 
 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");
@@ -207,7 +291,7 @@ function launchCodex(workspace, packet, callbacks) {
     "exec",
     "--json",
     "--sandbox",
-    "workspace-write",
+    sandbox,
     "-C",
     workspace,
     "-",
@@ -218,10 +302,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;
@@ -232,6 +316,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?.({
@@ -252,7 +343,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)}`),
@@ -363,7 +454,15 @@ function isShareablePath(relative) {
   if (parts.some((part) => EXCLUDED_DIRECTORIES.has(part.toLowerCase()))) {
     return false;
   }
+  if (
+    EXCLUDED_PATH_PREFIXES.some((prefix) =>
+      normalized.toLowerCase().startsWith(prefix),
+    )
+  ) {
+    return false;
+  }
   const name = parts.at(-1)?.toLowerCase() ?? "";
+  if (EXCLUDED_FILE_EXTENSIONS.has(path.posix.extname(name))) return false;
   if (name === ".env.example" || name === ".env.sample") return true;
   if (
     name === ".env" ||