@engineeros/connector 0.15.3 → 0.16.0

package/README.md

@@ -47,7 +47,7 @@ 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**, run the workspace assessment to use the connected agent subscription already authenticated on that computer. Select any combination of fifteen brownfield assessment domains, collectively covering 133 baseline checks from product and architecture through security, privacy, project-specific compliance, delivery, reliability, governance, and modernization planning. Every domain uses a detailed structured-Markdown contract. Connector `0.15.3` starts assessments with three parallel workers and accepts the run's UI-selected limit from three through eight for every coding-agent provider. It atomically spools each completed Markdown report under `.engineeros/assessments/<run-id>` before delivery. ACP agents such as OpenCode use isolated stage sessions within one persistent coding-agent process. The connector owns the worker pool and sends one aggregate heartbeat containing every active worker's phase, progress, last activity, and event count; report content is no longer streamed over the WebSocket or written into backend assessment JSON. The backend validates stage checkpoints so dependency fan-out remains authoritative, while the connector retains the reports and reuses them after reconnect without rerunning completed agents. Capability detail and project-specific compliance controls fan out after their catalogs. Final synthesis reads the connector-local Markdown files, then one completed bundle is revalidated, persisted, and published as canonical artifacts. The connector removes its spool only after EngineerOS acknowledges the complete bundle. Compliance findings describe repository-verifiable engineering readiness and missing external context, never legal compliance or certification. The connector prints each worker's safe activity and elapsed time every 30 seconds, stops a worker that produces no agent activity for ten minutes instead of waiting indefinitely, and applies separate bounded structure, semantic, and corrected-response formatting repairs before failing a stage. Assessment cannot modify tracked workspace source.
+From **Project steering -> Workspace**, run the workspace assessment to use the connected agent subscription already authenticated on that computer. Select any combination of fifteen brownfield assessment domains, collectively covering 133 baseline checks from product and architecture through security, privacy, project-specific compliance, delivery, reliability, governance, and modernization planning. Every domain uses a detailed structured-Markdown contract. Connector `0.16.0` starts assessments with three parallel workers and accepts the run's UI-selected limit from three through eight for every coding-agent provider. It atomically spools each completed Markdown report and each active stage's resumable agent-session checkpoint under `.engineeros/assessments/<run-id>`. ACP agents such as OpenCode use isolated stage sessions within one persistent coding-agent process. The connector owns the worker pool and sends one aggregate heartbeat containing every active worker's phase, progress, last activity, and event count; report content is no longer streamed over the WebSocket or written into backend assessment JSON. The backend validates stage checkpoints so dependency fan-out remains authoritative, while the connector retains completed reports and reloads interrupted ACP or Codex sessions after reconnect when the coding agent supports session restoration. Capability detail and project-specific compliance controls fan out after their catalogs. Final synthesis reads the connector-local Markdown files, then one completed bundle is revalidated, persisted, and published as canonical artifacts. The connector removes its spool only after EngineerOS acknowledges the complete bundle. Compliance findings describe repository-verifiable engineering readiness and missing external context, never legal compliance or certification. The connector prints each worker's safe activity and elapsed time every 30 seconds, stops a worker that produces no agent activity for ten minutes instead of waiting indefinitely, and applies separate bounded structure, semantic, and corrected-response formatting repairs before failing a stage. Assessment cannot modify tracked workspace source.
 
 Every backend `422` content-validation response is returned to the stage agent with the exact failed item. Distinct validation failures continue through correction and resubmission until the complete stage is accepted. Three repetitions of the same unresolved validation error stop the automatic loop while preserving the latest local report for retry. Authentication, cancellation, source drift, and transport failures remain operational errors rather than agent-correction prompts.
 

package/bin/engineeros-connector.mjs

@@ -36,9 +36,11 @@ import {
 import {
   assessmentCheckpointPayload,
   assessmentCompletionBundle,
-  clearAssessmentSpool,
-  loadAssessmentStageResult,
-  persistAssessmentStageResult,
+  clearAssessmentSpool,
+  loadAssessmentStageSession,
+  loadAssessmentStageResult,
+  persistAssessmentStageResult,
+  persistAssessmentStageSession,
   prepareLocalAssessmentAssignment,
   removeAssessmentStageResult,
 } from "../src/assessment-spool.mjs";
@@ -50,11 +52,12 @@ import {
   registeredAgents,
 } from "../src/agent-registry.mjs";
 import {
-  describeRejectedResponse,
-  describeWebSocketError,
-  protocolFailureMessage,
-  startConnectionWatchdog,
-} from "../src/connection.mjs";
+  describeRejectedResponse,
+  describeWebSocketError,
+  protocolFailureMessage,
+  sendConnectionMessage,
+  startConnectionWatchdog,
+} from "../src/connection.mjs";
 import { advertisedCapabilities } from "../src/capabilities.mjs";
 import { parseConnectorArgs } from "../src/cli-args.mjs";
 import { runMcpServer } from "../src/mcp-server.mjs";
@@ -250,25 +253,47 @@ process.on("SIGINT", async () => {
 
 await connect();
 
-async function connect() {
-  console.log(`Connecting ${config.name} to ${config.server_url}`);
-  connectionRejected = false;
-  lastConnectionError = undefined;
-  socket = new WebSocket(config.server_url);
-  clearConnectionWatchdog = startConnectionWatchdog(socket, config.server_url, {
-    onTimeout: (message) => {
-      lastConnectionError = message;
-      console.error(message);
-      scheduleReconnect();
-    },
-  });
-  socket.addEventListener("open", () =>
-    socket.send(JSON.stringify(firstMessage)),
-  );
-  socket.addEventListener("message", async (event) => {
-    const message = JSON.parse(String(event.data));
-    if (message.type === "paired") {
-      clearConnectionWatchdog?.();
+async function connect() {
+  console.log(`Connecting ${config.name} to ${config.server_url}`);
+  connectionRejected = false;
+  lastConnectionError = undefined;
+  const connection = new WebSocket(config.server_url);
+  socket = connection;
+  const clearWatchdog = startConnectionWatchdog(connection, config.server_url, {
+    onTimeout: (message) => {
+      if (socket !== connection) return;
+      lastConnectionError = message;
+      console.error(message);
+      scheduleReconnect();
+    },
+  });
+  clearConnectionWatchdog = clearWatchdog;
+  connection.addEventListener("open", () => {
+    if (socket !== connection) {
+      connection.close();
+      return;
+    }
+    try {
+      if (sendConnectionMessage(socket, connection, firstMessage)) return;
+      throw new Error("The WebSocket was not open when authentication started.");
+    } catch (error) {
+      lastConnectionError = protocolFailureMessage(error);
+      console.error(
+        `Could not authenticate the WebSocket connection: ${lastConnectionError}`,
+      );
+      try {
+        connection.close();
+      } catch {
+        // The reconnect timer below owns recovery.
+      }
+      scheduleReconnect();
+    }
+  });
+  connection.addEventListener("message", async (event) => {
+    if (socket !== connection) return;
+    const message = JSON.parse(String(event.data));
+    if (message.type === "paired") {
+      clearWatchdog();
       const reusedConnector =
         existingConfig?.connector_id === message.connector.id;
       config = mergePairedConfig(
@@ -294,8 +319,8 @@ async function connect() {
       if (config.onboarding_pending) void submitWorkspaceSnapshot();
       return;
     }
-    if (message.type === "authenticated") {
-      clearConnectionWatchdog?.();
+    if (message.type === "authenticated") {
+      clearWatchdog();
       console.log("Connected and waiting for EngineerOS runs.");
       reconnectDelay = 1_000;
       startPings();
@@ -345,10 +370,10 @@ async function connect() {
       await stopProcess(active.child);
       return;
     }
-    if (message.type === "connector.revoked") {
-      stopped = true;
-      console.error("This connector was revoked in EngineerOS.");
-      socket.close();
+    if (message.type === "connector.revoked") {
+      stopped = true;
+      console.error("This connector was revoked in EngineerOS.");
+      connection.close();
       return;
     }
     if (message.type === "run.error") {
@@ -364,9 +389,10 @@ async function connect() {
       console.error(`EngineerOS: ${message.message}`);
     }
   });
-  socket.addEventListener("close", (event) => {
-    clearConnectionWatchdog?.();
-    clearInterval(pingTimer);
+  connection.addEventListener("close", (event) => {
+    clearWatchdog();
+    if (socket !== connection) return;
+    clearInterval(pingTimer);
     for (const promptState of activePrompts.values())
       void cancelPrompt(promptState);
     for (const assessmentState of activeAssessments.values()) {
@@ -382,8 +408,9 @@ async function connect() {
     if (stopped) return;
     scheduleReconnect();
   });
-  socket.addEventListener("error", (event) => {
-    lastConnectionError = describeWebSocketError(event);
+  connection.addEventListener("error", (event) => {
+    if (socket !== connection) return;
+    lastConnectionError = describeWebSocketError(event);
     console.error(
       `WebSocket connection to ${config.server_url} failed: ${lastConnectionError}`,
     );
@@ -724,7 +751,16 @@ async function executeAssessment(assignment, assessmentState) {
       );
     }
   }, 15_000);
-  const assessmentAgentCallbacks = {
+  const assessmentAgentCallbacks = {
+    onSession: async (sessionId) => {
+      if (!isActiveAssessment()) return;
+      await persistAssessmentStageSession(
+        config.workspace,
+        assessmentId,
+        stage,
+        sessionId,
+      );
+    },
     onController: (controller) => {
       if (isActiveAssessment()) assessmentState.controller = controller;
     },
@@ -773,20 +809,29 @@ async function executeAssessment(assignment, assessmentState) {
       config.workspace,
       assignment,
     );
-    let result = await loadAssessmentStageResult(
+    let result = await loadAssessmentStageResult(
       config.workspace,
       assessmentId,
       stage,
     );
-    if (result) {
+    if (result) {
       attachStoredCorrection(result, preparedAssignment);
       reportProgress("Recovered completed stage report from connector storage");
-    } else {
-      result = await executeWorkspaceAssessment(
-        preparedAssignment,
-        config,
-        assessmentAgentCallbacks,
-      );
+    } else {
+      const previousSessionId = await loadAssessmentStageSession(
+        config.workspace,
+        assessmentId,
+        stage,
+      );
+      if (previousSessionId) {
+        reportProgress("Restoring interrupted agent session");
+      }
+      result = await executeWorkspaceAssessment(
+        preparedAssignment,
+        config,
+        assessmentAgentCallbacks,
+        { previousSessionId },
+      );
       await persistAssessmentStageResult(
         config.workspace,
         assessmentId,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineeros/connector",
-  "version": "0.15.3",
+  "version": "0.16.0",
   "description": "Connect a local coding agent to EngineerOS, using ACP when supported.",
   "private": false,
   "type": "module",

package/src/acp-client.mjs

@@ -201,19 +201,20 @@ class AcpRuntime {
     this.clearIdleTimer();
     const initialized = await this.ready;
     let session = this.sessions.get(sessionKey);
-    if (!session) {
-      session = await this.openSession(
+    if (!session) {
+      session = await this.openSession(
         sessionKey,
         previousSessionId,
         sandbox,
         profile,
       );
-      callbacks.onEvent?.({
-        type: "agent.connected",
-        message: `Agent connected with protocol ${initialized.protocolVersion}`,
-      });
-    }
-    if (this.turns.has(session.sessionId)) {
+      callbacks.onEvent?.({
+        type: "agent.connected",
+        message: `Agent connected with protocol ${initialized.protocolVersion}`,
+      });
+    }
+    await callbacks.onSession?.(session.sessionId);
+    if (this.turns.has(session.sessionId)) {
       throw new Error(
         "The agent is already answering another prompt in this session.",
       );

package/src/assessment-spool.mjs

@@ -53,7 +53,7 @@ export async function persistAssessmentStageResult(
   return { ...metadata, report_markdown: report };
 }
 
-export async function loadAssessmentStageResult(
+export async function loadAssessmentStageResult(
   workspace,
   assessmentId,
   stage,
@@ -89,7 +89,58 @@ export async function loadAssessmentStageResult(
     if (error?.code === "ENOENT") return null;
     throw error;
   }
-}
+}
+
+export async function persistAssessmentStageSession(
+  workspace,
+  assessmentId,
+  stage,
+  sessionId,
+) {
+  const normalizedSessionId = String(sessionId || "").trim();
+  if (!normalizedSessionId) {
+    throw new Error(`Assessment stage '${stage}' returned an empty session id.`);
+  }
+  const directory = assessmentRunDirectory(workspace, assessmentId);
+  await mkdir(directory, { recursive: true, mode: 0o700 });
+  const checkpoint = {
+    stage,
+    agent_session_id: normalizedSessionId,
+  };
+  await atomicWrite(
+    assessmentStageSessionPath(directory, stage),
+    `${JSON.stringify(checkpoint, null, 2)}\n`,
+  );
+  return checkpoint;
+}
+
+export async function loadAssessmentStageSession(
+  workspace,
+  assessmentId,
+  stage,
+) {
+  const directory = assessmentRunDirectory(workspace, assessmentId);
+  try {
+    const checkpoint = JSON.parse(
+      await readFile(assessmentStageSessionPath(directory, stage), "utf8"),
+    );
+    if (checkpoint.stage !== stage) {
+      throw new Error(
+        `Assessment session checkpoint does not match stage '${stage}'.`,
+      );
+    }
+    const sessionId = String(checkpoint.agent_session_id || "").trim();
+    if (!sessionId) {
+      throw new Error(
+        `Assessment session checkpoint for '${stage}' has no session id.`,
+      );
+    }
+    return sessionId;
+  } catch (error) {
+    if (error?.code === "ENOENT") return null;
+    throw error;
+  }
+}
 
 export async function removeAssessmentStageResult(
   workspace,
@@ -226,14 +277,18 @@ function validateLocalAssessmentResult(assignment, result) {
   }
 }
 
-function assessmentStageBasename(stage) {
+function assessmentStageBasename(stage) {
   const slug =
     String(stage)
       .replace(/[^a-zA-Z0-9_-]+/g, "-")
       .replace(/^-+|-+$/g, "")
       .slice(0, 64) || "stage";
   return `${slug}-${sha256(String(stage)).slice(0, 12)}`;
-}
+}
+
+function assessmentStageSessionPath(directory, stage) {
+  return path.join(directory, `${assessmentStageBasename(stage)}.session.json`);
+}
 
 function sha256(value) {
   return createHash("sha256").update(value).digest("hex");

package/src/codex-app-server.mjs

@@ -217,8 +217,9 @@ export function launchCodexAppServer({
               model: profile.model || null,
               ephemeral: false,
             });
-        threadId = threadResult.thread.id;
-        callbacks.onEvent?.({ type: "thread.started", thread_id: threadId });
+        threadId = threadResult.thread.id;
+        await callbacks.onSession?.(threadId);
+        callbacks.onEvent?.({ type: "thread.started", thread_id: threadId });
         const turnResult = await request("turn/start", {
           threadId,
           input: [{ type: "text", text: prompt }],

package/src/connection.mjs

@@ -1,13 +1,19 @@
 const PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH = 2_000;
 const TRUNCATED_FAILURE_SUFFIX = "\n… [truncated by EngineerOS connector]";
 
-export function describeWebSocketError(event) {
+export function describeWebSocketError(event) {
   return (
     event?.error?.message ||
     event?.message ||
     "The WebSocket connection failed without providing an error detail."
   );
-}
+}
+
+export function sendConnectionMessage(activeSocket, connection, message) {
+  if (activeSocket !== connection || connection.readyState !== 1) return false;
+  connection.send(JSON.stringify(message));
+  return true;
+}
 
 export function protocolFailureMessage(error) {
   const raw = error instanceof Error ? error.message : String(error ?? "");

package/src/runner.mjs

@@ -361,11 +361,12 @@ export function parseVerificationReport(
   });
 }
 
-export async function executeWorkspaceAssessment(
-  assignment,
-  config,
-  callbacks,
-) {
+export async function executeWorkspaceAssessment(
+  assignment,
+  config,
+  callbacks,
+  { previousSessionId } = {},
+) {
   const execution = workspaceAssessmentExecution(assignment);
   const assessmentAcpContext =
     config.agent_protocol === "acp"
@@ -421,7 +422,7 @@ export async function executeWorkspaceAssessment(
         changeImpact.markdown,
       )
     : execution.prompt;
-  const controller = launchAssessmentAgent(prompt);
+  const controller = launchAssessmentAgent(prompt, previousSessionId);
   let completed = await controller.completed;
   const recovered = await recoverAssessmentStageOutput({
     completed,
@@ -1674,8 +1675,10 @@ function launchCodexProcess(
   child.stdin.end(prompt);
   let output = "";
   let buffer = "";
-  let finalMessage = "";
-  let sessionId = previousSessionId || "";
+  let finalMessage = "";
+  let sessionId = previousSessionId || "";
+  let sessionCheckpoint = Promise.resolve();
+  let sessionCheckpointError;
   child.stdout.setEncoding("utf8");
   child.stdout.on("data", (chunk) => {
     output += chunk;
@@ -1686,12 +1689,17 @@ function launchCodexProcess(
       if (!line.trim()) continue;
       try {
         const event = JSON.parse(line);
-        if (
-          event.type === "thread.started" &&
-          typeof event.thread_id === "string"
-        ) {
-          sessionId = event.thread_id;
-        }
+        if (
+          event.type === "thread.started" &&
+          typeof event.thread_id === "string"
+        ) {
+          sessionId = event.thread_id;
+          sessionCheckpoint = Promise.resolve()
+            .then(() => callbacks.onSession?.(sessionId))
+            .catch((error) => {
+              sessionCheckpointError = error;
+            });
+        }
         if (
           event.type === "item.completed" &&
           event.item?.type === "agent_message" &&
@@ -1718,17 +1726,20 @@ function launchCodexProcess(
   });
   const completed = new Promise((resolve, reject) => {
     child.once("error", reject);
-    child.once("close", (code) => {
-      if (code === 0 && sessionId)
-        resolve({ output: output.slice(-20_000), finalMessage, sessionId });
-      else if (code === 0)
-        reject(
-          new Error(
-            "Agent completed without announcing a resumable session id.",
-          ),
-        );
-      else reject(new Error(codexFailureMessage(output, code)));
-    });
+    child.once("close", (code) => {
+      void sessionCheckpoint.then(() => {
+        if (sessionCheckpointError) reject(sessionCheckpointError);
+        else if (code === 0 && sessionId)
+          resolve({ output: output.slice(-20_000), finalMessage, sessionId });
+        else if (code === 0)
+          reject(
+            new Error(
+              "Agent completed without announcing a resumable session id.",
+            ),
+          );
+        else reject(new Error(codexFailureMessage(output, code)));
+      });
+    });
   });
   return { child, completed };
 }