@engineeros/connector 0.12.4 → 0.13.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. EngineerOS stores the source-cited findings in System State and promotes the highest-return corrective action in Steering. Assessment cannot modify the workspace.
+From **Project steering -> Workspace**, run the workspace assessment to use the connected agent subscription already authenticated on that computer. Select Architecture, Capabilities, Quality, or any combination when only part of the workspace needs reassessment. EngineerOS stores every completed assessment stage before starting the next one, resumes the unfinished stage after a connector restart or retry, and then synthesizes the selected results into System State. Capabilities are assessed one discovered capability at a time so a large repository does not depend on one unbounded agent turn. Assessment cannot modify the workspace.
 
 After onboarding, every project prompt is routed to this connection. Copilot, shaping, planning, architecture, and experience generation use the connected agent subscription and workspace context. Interactive prompts run independently from assessments and Goal scheduling. 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.
 

package/bin/engineeros-connector.mjs

@@ -31,7 +31,9 @@ import {
   registeredAgents,
 } from "../src/agent-registry.mjs";
 import {
+  describeRejectedResponse,
   describeWebSocketError,
+  protocolFailureMessage,
   startConnectionWatchdog,
 } from "../src/connection.mjs";
 import { advertisedCapabilities } from "../src/capabilities.mjs";
@@ -274,9 +276,12 @@ async function connect() {
     }
     if (message.type === "workspace.assessment") {
       if (
-        active?.runId !== message.assessment_id &&
+        (active?.runId !== message.assessment_id ||
+          active?.stage !== message.stage) &&
         !assessments.some(
-          (candidate) => candidate.assessment_id === message.assessment_id,
+          (candidate) =>
+            candidate.assessment_id === message.assessment_id &&
+            candidate.stage === message.stage,
         )
       ) {
         assessments.push(message);
@@ -387,7 +392,7 @@ async function submitWorkspaceSnapshot() {
     );
     if (!response.ok) {
       throw new Error(
-        `EngineerOS rejected the workspace (${response.status}): ${await response.text()}`,
+        await describeRejectedResponse(response, "the workspace"),
       );
     }
     const result = await response.json();
@@ -422,7 +427,7 @@ async function submitWorkspaceSnapshot() {
   } catch (error) {
     snapshotInFlight = false;
     console.error(
-      `Workspace assessment failed: ${error instanceof Error ? error.message : String(error)}`,
+      `Workspace assessment failed: ${protocolFailureMessage(error)}`,
     );
   }
 }
@@ -461,6 +466,7 @@ function pump() {
     active = {
       kind: "assessment",
       runId: assessment.assessment_id,
+      stage: assessment.stage,
       child: null,
     };
     void executeAssessment(assessment);
@@ -545,17 +551,18 @@ async function executePrompt(assignment) {
       }),
     );
   } catch (error) {
+    const message = protocolFailureMessage(error);
     if (!promptState.cancelled && socket.readyState === WebSocket.OPEN) {
       socket.send(
         JSON.stringify({
           type: "prompt.failed",
           prompt_id: promptId,
-          message: error instanceof Error ? error.message : String(error),
+          message,
         }),
       );
     }
     if (!promptState.cancelled) {
-      console.error(error instanceof Error ? error.message : String(error));
+      console.error(message);
     }
   } finally {
     if (activePrompts.get(promptId) === promptState)
@@ -574,14 +581,19 @@ async function cancelPrompt(promptState) {
 
 async function executeAssessment(assignment) {
   const assessmentId = assignment.assessment_id;
-  console.log(`Agent is assessing the workspace (${assessmentId}).`);
+  const stage = assignment.stage;
+  console.log(`Agent is running assessment stage ${stage} (${assessmentId}).`);
   let progress = 10;
   let outputBuffer = "";
   let outputLength = 0;
   let outputTimer;
   const reportedMilestones = new Set();
   const reportProgress = (message, { milestone = true } = {}) => {
-    if (socket.readyState !== WebSocket.OPEN || active?.runId !== assessmentId)
+    if (
+      socket.readyState !== WebSocket.OPEN ||
+      active?.runId !== assessmentId ||
+      active?.stage !== stage
+    )
       return;
     if (milestone && reportedMilestones.has(message)) return;
     if (milestone) reportedMilestones.add(message);
@@ -589,6 +601,7 @@ async function executeAssessment(assignment) {
       JSON.stringify({
         type: "workspace.assessment.progress",
         assessment_id: assessmentId,
+        stage,
         progress_percent: progress,
         message: String(message).slice(0, 500),
       }),
@@ -602,7 +615,8 @@ async function executeAssessment(assignment) {
     if (
       !output ||
       socket.readyState !== WebSocket.OPEN ||
-      active?.runId !== assessmentId
+      active?.runId !== assessmentId ||
+      active?.stage !== stage
     ) {
       return;
     }
@@ -611,6 +625,7 @@ async function executeAssessment(assignment) {
         JSON.stringify({
           type: "workspace.assessment.output",
           assessment_id: assessmentId,
+          stage,
           delta: output.slice(offset, offset + 50_000),
         }),
       );
@@ -628,7 +643,7 @@ async function executeAssessment(assignment) {
       outputTimer = setTimeout(flushOutput, 500);
     }
   };
-  reportProgress("Starting read-only repository assessment");
+  reportProgress(`Starting ${stage} assessment stage`);
   const heartbeat = setInterval(() => {
     progress = Math.min(90, progress + 5);
     reportProgress("Assessment in progress", { milestone: false });
@@ -640,7 +655,9 @@ async function executeAssessment(assignment) {
     }
     const result = await executeWorkspaceAssessment(assignment, config, {
       onProcess: (child) => {
-        if (active?.runId === assessmentId) active.child = child;
+        if (active?.runId === assessmentId && active?.stage === stage) {
+          active.child = child;
+        }
       },
       onEvent: (event) => {
         reportOutput(assessmentStreamDelta(event));
@@ -662,22 +679,24 @@ async function executeAssessment(assignment) {
     );
     if (!response.ok) {
       throw new Error(
-        `EngineerOS rejected the assessment (${response.status}): ${await response.text()}`,
+        await describeRejectedResponse(response, "the assessment"),
       );
     }
-    console.log("Workspace assessment is current in EngineerOS.");
+    console.log(`Workspace assessment stage ${stage} was accepted by EngineerOS.`);
   } catch (error) {
     flushOutput();
+    const message = protocolFailureMessage(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),
+          stage,
+          message,
         }),
       );
     }
-    console.error(error instanceof Error ? error.message : String(error));
+    console.error(message);
   } finally {
     if (outputTimer) clearTimeout(outputTimer);
     clearInterval(heartbeat);
@@ -735,10 +754,9 @@ async function execute(assignment) {
         body: JSON.stringify(result),
       },
     );
-    if (!response.ok)
-      throw new Error(
-        `EngineerOS rejected the result (${response.status}): ${await response.text()}`,
-      );
+    if (!response.ok) {
+      throw new Error(await describeRejectedResponse(response, "the result"));
+    }
     const integration = await applyAcceptedChange(
       config.workspace,
       assignment.base_revision,
@@ -757,17 +775,17 @@ async function execute(assignment) {
       );
     }
   } catch (error) {
+    const message = protocolFailureMessage(error);
     if (!active?.cancelled && socket.readyState === WebSocket.OPEN) {
       socket.send(
         JSON.stringify({
           type: "run.failed",
           run_id: runId,
-          message: error instanceof Error ? error.message : String(error),
+          message,
         }),
       );
     }
-    if (!active?.cancelled)
-      console.error(error instanceof Error ? error.message : String(error));
+    if (!active?.cancelled) console.error(message);
   } finally {
     clearInterval(heartbeat);
     active = null;

package/package.json

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

package/src/connection.mjs

@@ -1,3 +1,6 @@
+const PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH = 2_000;
+const TRUNCATED_FAILURE_SUFFIX = "\n… [truncated by EngineerOS connector]";
+
 export function describeWebSocketError(event) {
   return (
     event?.error?.message ||
@@ -6,6 +9,26 @@ export function describeWebSocketError(event) {
   );
 }
 
+export function protocolFailureMessage(error) {
+  const raw = error instanceof Error ? error.message : String(error ?? "");
+  const message =
+    raw.trim() || "The connector failed without providing an error detail.";
+  const characters = [...message];
+  if (characters.length <= PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH) return message;
+  const suffix = [...TRUNCATED_FAILURE_SUFFIX];
+  return `${characters
+    .slice(0, PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH - suffix.length)
+    .join("")}${TRUNCATED_FAILURE_SUFFIX}`;
+}
+
+export async function describeRejectedResponse(response, subject) {
+  const responseBody = await response.text();
+  const detail = responseDetail(responseBody);
+  return protocolFailureMessage(
+    `EngineerOS rejected ${subject} (${response.status})${detail ? `: ${detail}` : "."}`,
+  );
+}
+
 export function startConnectionWatchdog(
   socket,
   url,
@@ -24,3 +47,28 @@ export function startConnectionWatchdog(
 
   return () => clearTimeout(timer);
 }
+
+function responseDetail(responseBody) {
+  const body = String(responseBody || "").trim();
+  if (!body) return "";
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed?.detail === "string") return parsed.detail;
+    if (Array.isArray(parsed?.detail)) {
+      return parsed.detail.map(validationIssue).filter(Boolean).join("; ");
+    }
+  } catch {
+    // Plain-text server errors are already useful to the operator.
+  }
+  return body;
+}
+
+function validationIssue(issue) {
+  if (typeof issue === "string") return issue;
+  if (!issue || typeof issue !== "object") return "";
+  const location = Array.isArray(issue.loc) ? issue.loc.join(".") : "";
+  const message = typeof issue.msg === "string" ? issue.msg : "";
+  const type = typeof issue.type === "string" ? ` (${issue.type})` : "";
+  if (!location && !message) return "";
+  return `${location ? `${location}: ` : ""}${message}${type}`;
+}

package/src/runner.mjs

@@ -414,8 +414,9 @@ export async function executeWorkspaceAssessment(
       "The Git commit changed during assessment. Refresh the workspace inventory and assess the new commit.",
     );
   }
-  return {
-    report_markdown: report,
+  return {
+    stage: assignment.stage,
+    report_markdown: report,
     observed_head_revision: endingHead,
     changed_files: changeImpact.changedFiles,
     change_impact_markdown: changeImpact.markdown,
@@ -761,11 +762,22 @@ function assessmentCommandMilestone(command) {
   return "Tracing architecture and code relationships";
 }
 
-export function workspaceAssessmentExecution(assignment) {
-  const requiredOutputHeading =
-    assignment?.assessment_mode === "incremental"
-      ? "# Workspace Assessment Delta"
-      : "# Workspace Assessment";
+export function workspaceAssessmentExecution(assignment) {
+  const stage = assignment?.stage;
+  const requiredOutputHeading =
+    stage === "synthesis"
+      ? "# Assessment Stage: Synthesis"
+      : stage === "capability_catalog"
+        ? "# Assessment Stage: Capability Catalog"
+        : String(stage || "").startsWith("capability:")
+          ? "# Assessment Stage: Capabilities"
+          : `# Assessment Stage: ${String(stage || "").replace(/^./, (value) => value.toUpperCase())}`;
+  if (
+    !new Set(["architecture", "capability_catalog", "quality", "synthesis"]).has(stage) &&
+    !String(stage || "").startsWith("capability:")
+  ) {
+    throw new Error("EngineerOS assessment assignment has an unsupported stage.");
+  }
   return {
     ...connectorExecution(assignment, { requiredOutputHeading }),
     requiredOutputHeading,