@engineeros/connector 0.13.0 → 0.13.2

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 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.
+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, retry, or temporary connection loss, and then synthesizes the selected results into System State. The connector prints the current safe activity and elapsed time every 30 seconds, stops a stage that produces no agent activity for ten minutes instead of waiting indefinitely, and gives an incomplete final report one bounded correction turn instead of repeatedly restarting the stage. 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

@@ -12,14 +12,17 @@ import {
   workspaceUrl,
 } from "../src/config.mjs";
 import {
+  assessmentInactivityFailure,
   assessmentProgressMessage,
   assessmentStreamDelta,
   applyAcceptedChange,
+  enqueueWorkspaceAssessment,
   executeAssignment,
   executeConnectedPrompt,
   executeWorkspaceAssessment,
   inspectCodingAgent,
   promptStreamEvent,
+  requeueInterruptedAssessment,
   stopProcess,
   workspaceSnapshot,
 } from "../src/runner.mjs";
@@ -275,16 +278,15 @@ async function connect() {
       return;
     }
     if (message.type === "workspace.assessment") {
-      if (
-        (active?.runId !== message.assessment_id ||
-          active?.stage !== message.stage) &&
-        !assessments.some(
-          (candidate) =>
-            candidate.assessment_id === message.assessment_id &&
-            candidate.stage === message.stage,
-        )
-      ) {
-        assessments.push(message);
+      const disposition = enqueueWorkspaceAssessment(
+        assessments,
+        active,
+        message,
+      );
+      if (disposition === "deferred") {
+        console.log(
+          `Assessment stage ${message.stage} is still active after reconnect; preserving the replay until it finishes.`,
+        );
       }
       pump();
       return;
@@ -337,8 +339,9 @@ async function connect() {
     clearInterval(pingTimer);
     for (const promptState of activePrompts.values())
       void cancelPrompt(promptState);
-    if (event.code === 4001 && active?.kind === "assessment") {
-      void stopProcess(active.child);
+    if (active?.kind === "assessment") {
+      active.transportInterrupted = true;
+      if (event.code === 4001) void stopProcess(active.child);
     }
     if (connectionRejected) {
       stopped = true;
@@ -463,13 +466,16 @@ function pump() {
   if (active || socket.readyState !== WebSocket.OPEN) return;
   const assessment = assessments.shift();
   if (assessment) {
-    active = {
+    const assessmentState = {
       kind: "assessment",
       runId: assessment.assessment_id,
       stage: assessment.stage,
       child: null,
+      resumeAssignment: null,
+      transportInterrupted: false,
     };
-    void executeAssessment(assessment);
+    active = assessmentState;
+    void executeAssessment(assessment, assessmentState);
     return;
   }
   const runId = available.shift();
@@ -579,24 +585,38 @@ async function cancelPrompt(promptState) {
   await stopProcess(promptState.child);
 }
 
-async function executeAssessment(assignment) {
+async function executeAssessment(assignment, assessmentState) {
   const assessmentId = assignment.assessment_id;
   const stage = assignment.stage;
   console.log(`Agent is running assessment stage ${stage} (${assessmentId}).`);
-  let progress = 10;
+  const stageStartedAt = Date.now();
+  let lastAgentActivityAt = stageStartedAt;
+  let lastAgentStatus = "Starting the connected agent";
+  let agentEventCount = 0;
+  let agentProcessStarted = false;
+  let statusTicks = 0;
+  let progress = 5;
   let outputBuffer = "";
   let outputLength = 0;
   let outputTimer;
-  const reportedMilestones = new Set();
+  let accepted = false;
+  let failureReported = false;
+  let inactivityFailure = null;
+  let lastReportedMilestone = null;
+  const creditedMilestones = new Set();
   const reportProgress = (message, { milestone = true } = {}) => {
-    if (
-      socket.readyState !== WebSocket.OPEN ||
-      active?.runId !== assessmentId ||
-      active?.stage !== stage
-    )
-      return;
-    if (milestone && reportedMilestones.has(message)) return;
-    if (milestone) reportedMilestones.add(message);
+    if (active !== assessmentState) return;
+    if (milestone && lastReportedMilestone === message) return;
+    if (milestone) {
+      lastReportedMilestone = message;
+      if (!creditedMilestones.has(message)) {
+        creditedMilestones.add(message);
+        progress = Math.min(90, progress + 10);
+      }
+      lastAgentStatus = message;
+      console.log(`[assessment:${stage}] ${message}.`);
+    }
+    if (socket.readyState !== WebSocket.OPEN) return;
     socket.send(
       JSON.stringify({
         type: "workspace.assessment.progress",
@@ -615,8 +635,7 @@ async function executeAssessment(assignment) {
     if (
       !output ||
       socket.readyState !== WebSocket.OPEN ||
-      active?.runId !== assessmentId ||
-      active?.stage !== stage
+      active !== assessmentState
     ) {
       return;
     }
@@ -645,8 +664,27 @@ async function executeAssessment(assignment) {
   };
   reportProgress(`Starting ${stage} assessment stage`);
   const heartbeat = setInterval(() => {
-    progress = Math.min(90, progress + 5);
+    const now = Date.now();
+    const inactiveMs = now - lastAgentActivityAt;
+    const nextInactivityFailure = agentProcessStarted
+      ? assessmentInactivityFailure(stage, inactiveMs)
+      : null;
+    if (!inactivityFailure && nextInactivityFailure) {
+      inactivityFailure = nextInactivityFailure;
+      console.error(`[assessment:${stage}] ${inactivityFailure}`);
+      void stopProcess(assessmentState.child);
+      return;
+    }
+    if (inactivityFailure) return;
     reportProgress("Assessment in progress", { milestone: false });
+    statusTicks += 1;
+    if (statusTicks % 2 === 0) {
+      console.log(
+        `[assessment:${stage}] ${formatAssessmentDuration(now - stageStartedAt)} elapsed · ` +
+          `${lastAgentStatus} · last agent activity ${formatAssessmentDuration(inactiveMs)} ago ` +
+          `(${agentEventCount.toLocaleString()} events).`,
+      );
+    }
   }, 15_000);
   try {
     if (assignment.assessment_mode === "incremental") {
@@ -655,11 +693,16 @@ async function executeAssessment(assignment) {
     }
     const result = await executeWorkspaceAssessment(assignment, config, {
       onProcess: (child) => {
-        if (active?.runId === assessmentId && active?.stage === stage) {
-          active.child = child;
+        if (active === assessmentState) {
+          assessmentState.child = child;
+          agentProcessStarted = true;
+          lastAgentActivityAt = Date.now();
+          reportProgress("Connected agent process started");
         }
       },
       onEvent: (event) => {
+        lastAgentActivityAt = Date.now();
+        agentEventCount += 1;
         reportOutput(assessmentStreamDelta(event));
         const message = assessmentProgressMessage(event);
         if (message) reportProgress(message);
@@ -682,11 +725,16 @@ async function executeAssessment(assignment) {
         await describeRejectedResponse(response, "the assessment"),
       );
     }
+    accepted = true;
     console.log(`Workspace assessment stage ${stage} was accepted by EngineerOS.`);
   } catch (error) {
     flushOutput();
-    const message = protocolFailureMessage(error);
-    if (socket.readyState === WebSocket.OPEN) {
+    const message = inactivityFailure || protocolFailureMessage(error);
+    if (
+      !assessmentState.transportInterrupted &&
+      active === assessmentState &&
+      socket.readyState === WebSocket.OPEN
+    ) {
       socket.send(
         JSON.stringify({
           type: "workspace.assessment.failed",
@@ -695,16 +743,34 @@ async function executeAssessment(assignment) {
           message,
         }),
       );
+      failureReported = true;
     }
     console.error(message);
   } finally {
     if (outputTimer) clearTimeout(outputTimer);
     clearInterval(heartbeat);
-    active = null;
-    pump();
+    if (active === assessmentState) {
+      active = null;
+      const replayQueued = requeueInterruptedAssessment(
+        assessments,
+        assessmentState,
+        { accepted, failureReported },
+      );
+      if (replayQueued) {
+        console.log(`Restarting interrupted assessment stage ${stage}.`);
+      }
+      pump();
+    }
   }
 }
 
+function formatAssessmentDuration(milliseconds) {
+  const totalSeconds = Math.max(0, Math.floor(milliseconds / 1_000));
+  const minutes = Math.floor(totalSeconds / 60);
+  const seconds = totalSeconds % 60;
+  return minutes ? `${minutes}m ${seconds}s` : `${seconds}s`;
+}
+
 async function execute(assignment) {
   const runId = assignment.run_id;
   console.log(`Running Goal ${runId} with ${codingAgent.name}.`);

package/package.json

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

package/src/acp-client.mjs

@@ -5,7 +5,7 @@ import * as acp from "@agentclientprotocol/sdk";
 const RUNTIME_IDLE_MS = 30 * 60 * 1_000;
 const runtimes = new Map();
 
-export function permissionOutcome(options = [], allow = false) {
+export function permissionOutcome(options = [], allow = false) {
   if (!allow) return { outcome: { outcome: "cancelled" } };
   const selected =
     options.find((option) => option.kind === "allow_once") ??
@@ -13,9 +13,9 @@ export function permissionOutcome(options = [], allow = false) {
   return selected
     ? { outcome: { outcome: "selected", optionId: selected.optionId } }
     : { outcome: { outcome: "cancelled" } };
-}
-
-export function launchAcpAgent(
+}
+
+export function launchAcpAgent(
   workspace,
   prompt,
   config,
@@ -39,7 +39,7 @@ export function launchAcpAgent(
     if (runtimeKey) runtimes.set(runtimeKey, runtime);
   }
   const sessionKey = options.sessionKey || `isolated-${crypto.randomUUID()}`;
-  const completed = runtime
+  const completed = runtime
     .prompt({
       sessionKey,
       prompt,
@@ -49,9 +49,10 @@ export function launchAcpAgent(
       callbacks,
     })
     .finally(async () => {
-      if (!persistent) await runtime.dispose();
-    });
-  return {
+      if (!persistent) await runtime.dispose();
+    });
+  runtime.child.engineerOsCancel = () => runtime.dispose();
+  return {
     child: runtime.child,
     completed,
     cancel: () => runtime.cancel(sessionKey),
@@ -117,18 +118,19 @@ class AcpRuntime {
     this.stderr = "";
     this.disposed = false;
     this.idleTimer = null;
-    this.child = spawn(
-      config.agent_command,
-      Array.isArray(config.agent_args) ? config.agent_args : [],
-      {
-        cwd: workspace,
-        env: { ...process.env, ...(config.agent_env || {}) },
-        shell:
-          process.platform === "win32" &&
-          /\.(cmd|bat)$/i.test(config.agent_command),
-        stdio: ["pipe", "pipe", "pipe"],
-      },
-    );
+    this.child = spawn(
+      config.agent_command,
+      Array.isArray(config.agent_args) ? config.agent_args : [],
+      {
+        cwd: workspace,
+        env: { ...process.env, ...(config.agent_env || {}) },
+        windowsHide: true,
+        shell:
+          process.platform === "win32" &&
+          /\.(cmd|bat)$/i.test(config.agent_command),
+        stdio: ["pipe", "pipe", "pipe"],
+      },
+    );
     this.child.stderr.setEncoding("utf8");
     this.child.stderr.on("data", (chunk) => {
       this.stderr = `${this.stderr}${chunk}`.slice(-4_000);

package/src/agent-harness.mjs

@@ -141,10 +141,15 @@ export function normalizeAgentStructuredOutput(
   if (!content) {
     throw new Error("Agent completed without returning a response.");
   }
-  const firstSection = {
-    "# Workspace Assessment": "## Executive Summary",
-    "# Workspace Assessment Delta": "## Updated Executive Summary",
-  }[outputHeading];
+  const firstSection = {
+    "# Workspace Assessment": "## Executive Summary",
+    "# Workspace Assessment Delta": "## Updated Executive Summary",
+    "# Assessment Stage: Architecture": "## Architecture Summary",
+    "# Assessment Stage: Capability Catalog": "## Capability Catalog",
+    "# Assessment Stage: Capabilities": "## Observed Capabilities",
+    "# Assessment Stage: Quality": "## Quality Summary",
+    "# Assessment Stage: Synthesis": "## Executive Summary",
+  }[outputHeading];
   if (
     firstSection &&
     (content.startsWith(firstSection) ||
@@ -152,12 +157,34 @@ export function normalizeAgentStructuredOutput(
   ) {
     return `${outputHeading}\n\n${content}`;
   }
-  const lines = content.split(/\r?\n/);
-  const headingIndex = lines.findIndex(
-    (line) => line.trim() === outputHeading,
-  );
-  const preamble =
-    headingIndex >= 0 ? lines.slice(0, headingIndex).join("\n") : content;
+  const lines = content.split(/\r?\n/);
+  const headingIndex = lines.findIndex(
+    (line) => line.trim() === outputHeading,
+  );
+  const firstSectionIndex = firstSection
+    ? lines.findIndex((line) => line.trim() === firstSection)
+    : -1;
+  if (
+    headingIndex < 0 &&
+    outputHeading.startsWith("# Assessment Stage:") &&
+    firstSectionIndex >= 0
+  ) {
+    const preamble = lines.slice(0, firstSectionIndex).join("\n");
+    if (preamble.length > 2_000) {
+      throw new Error(
+        `Agent response contains too much text before the required section '${firstSection}'.`,
+      );
+    }
+    const normalized = lines.slice(firstSectionIndex).join("\n").trim();
+    if (/```/.test(preamble) || /(?:^|\n)```\s*$/.test(normalized)) {
+      throw new Error(
+        `Agent response must return '${outputHeading}' as plain Markdown, without a code fence.`,
+      );
+    }
+    return `${outputHeading}\n\n${normalized}`;
+  }
+  const preamble =
+    headingIndex >= 0 ? lines.slice(0, headingIndex).join("\n") : content;
   if (headingIndex < 0) {
     throw new Error(
       `Agent response is missing the required heading '${outputHeading}'.`,

package/src/runner.mjs

@@ -28,9 +28,10 @@ const MAX_ARCHIVE_BYTES = 25_000_000;
 const MAX_EVIDENCE_BYTES = 24_000_000;
 const MAX_SHAREABLE_FILE_BYTES = 5 * 1024 * 1024;
 const MAX_EVIDENCE_FILES = 5_000;
-const MAX_INVENTORY_FILES = 100_000;
-const MAX_COMPRESSED_INVENTORY_BYTES = 10_000_000;
-const EVIDENCE_POLICY_VERSION = "workspace-evidence-v1";
+const MAX_INVENTORY_FILES = 100_000;
+const MAX_COMPRESSED_INVENTORY_BYTES = 10_000_000;
+const EVIDENCE_POLICY_VERSION = "workspace-evidence-v1";
+export const ASSESSMENT_INACTIVITY_TIMEOUT_MS = 10 * 60 * 1_000;
 const EXCLUDED_DIRECTORIES = new Set([
   ".agents",
   ".claude",
@@ -394,11 +395,31 @@ export async function executeWorkspaceAssessment(
     execution.profile,
   );
   callbacks.onProcess?.(controller.child);
-  const completed = await controller.completed;
-  const report = normalizeAgentStructuredOutput(
-    completed.finalMessage,
-    execution.requiredOutputHeading,
-  );
+  let completed = await controller.completed;
+  const recovered = await recoverAssessmentStageOutput({
+    completed,
+    prompt,
+    requiredOutputHeading: execution.requiredOutputHeading,
+    retry: async (correctionPrompt, previousSessionId) => {
+      callbacks.onEvent?.({
+        type: "assessment.output_correction",
+        message: "The Agent is completing the required stage report structure",
+      });
+      const correction = launchAgentProcess(
+        config.workspace,
+        correctionPrompt,
+        execution.sandboxMode,
+        config,
+        callbacks,
+        execution.profile,
+        previousSessionId,
+      );
+      callbacks.onProcess?.(correction.child);
+      return correction.completed;
+    },
+  });
+  completed = recovered.completed;
+  const report = recovered.report;
   const endingRevision = await run(
     "git",
     ["rev-parse", "HEAD"],
@@ -635,10 +656,23 @@ export function codexFailureMessage(output, code) {
   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";
+export function assessmentProgressMessage(event) {
+  if (!event || typeof event !== "object") return null;
+  if (event.type === "assessment.output_correction")
+    return "Completing the required stage report structure";
+  if (event.type === "agent.connected")
+    return "Connected agent is ready to inspect repository evidence";
+  if (event.type === "acp.plan")
+    return "Organizing the repository assessment plan";
+  if (event.type === "acp.agent_thought_chunk")
+    return "Reasoning through repository evidence";
+  if (event.type === "acp.agent_message_chunk")
+    return "Drafting the evidence-backed stage report";
+  if (event.type === "acp.tool_call" || event.type === "acp.tool_call_update") {
+    return assessmentCommandMilestone(event.update?.title);
+  }
+  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);
@@ -652,8 +686,16 @@ export function assessmentProgressMessage(event) {
   if (event.type === "item.completed" && event.item?.type === "agent_message") {
     return "Synthesizing findings and highest-return actions";
   }
-  return null;
-}
+  return null;
+}
+
+export function assessmentInactivityFailure(stage, inactiveMs) {
+  if (inactiveMs < ASSESSMENT_INACTIVITY_TIMEOUT_MS) return null;
+  return (
+    `The connected agent produced no activity for 10 minutes during ${stage}. ` +
+    "The stage was stopped instead of waiting indefinitely. Retry it after checking the agent terminal."
+  );
+}
 
 export function promptProgressMessage(event) {
   if (!event || typeof event !== "object") return null;
@@ -781,10 +823,141 @@ export function workspaceAssessmentExecution(assignment) {
   return {
     ...connectorExecution(assignment, { requiredOutputHeading }),
     requiredOutputHeading,
-  };
-}
-
-export function connectorExecution(assignment, options = {}) {
+  };
+}
+
+export async function recoverAssessmentStageOutput({
+  completed,
+  prompt,
+  requiredOutputHeading,
+  retry,
+}) {
+  try {
+    return {
+      completed,
+      report: normalizeAgentStructuredOutput(
+        completed.finalMessage,
+        requiredOutputHeading,
+      ),
+    };
+  } catch (error) {
+    if (!recoverableStructuredOutputFailure(error)) throw error;
+  }
+
+  const corrected = await retry(
+    assessmentStageCorrectionPrompt(prompt, requiredOutputHeading),
+    completed.sessionId,
+  );
+  try {
+    return {
+      completed: {
+        ...corrected,
+        usage: mergeTokenUsage(completed.usage, corrected.usage),
+      },
+      report: normalizeAgentStructuredOutput(
+        corrected.finalMessage,
+        requiredOutputHeading,
+      ),
+    };
+  } catch (error) {
+    throw new Error(
+      `Agent did not return the required stage report after one automatic correction attempt. ${error.message}`,
+      { cause: error },
+    );
+  }
+}
+
+export function assessmentStageCorrectionPrompt(
+  originalPrompt,
+  requiredOutputHeading,
+) {
+  return [
+    String(originalPrompt || "").trim(),
+    "",
+    "## Incomplete Stage Output Recovery",
+    "",
+    "The previous turn ended without a complete stage deliverable. Return the entire structured Markdown stage report now.",
+    "Use repository evidence already inspected in the previous turn when it is available; inspect only what remains necessary.",
+    `The first non-whitespace line of the final answer must be exactly: ${requiredOutputHeading}`,
+    "Follow every section, evidence, and completeness rule in the Assignment.",
+    "Do not return progress commentary, an explanation of the correction, or a code fence.",
+  ].join("\n");
+}
+
+function recoverableStructuredOutputFailure(error) {
+  const message = error instanceof Error ? error.message : "";
+  return (
+    message.startsWith("Agent completed") ||
+    message.startsWith("Agent response")
+  );
+}
+
+function mergeTokenUsage(first, second) {
+  const usages = [first, second].filter(
+    (usage) => usage && typeof usage === "object",
+  );
+  if (!usages.length) return null;
+  return Object.fromEntries(
+    [
+      "input_tokens",
+      "output_tokens",
+      "cache_read_tokens",
+      "cache_write_tokens",
+      "reasoning_tokens",
+      "total_tokens",
+    ].map((field) => [
+      field,
+      usages.reduce(
+        (total, usage) =>
+          total + (Number.isFinite(usage[field]) ? usage[field] : 0),
+        0,
+      ),
+    ]),
+  );
+}
+
+export function enqueueWorkspaceAssessment(
+  queue,
+  activeAssessment,
+  assignment,
+  { front = false } = {},
+) {
+  const matches = (candidate) =>
+    candidate?.assessment_id === assignment?.assessment_id &&
+    candidate?.stage === assignment?.stage;
+  if (
+    activeAssessment?.kind === "assessment" &&
+    activeAssessment.runId === assignment?.assessment_id &&
+    activeAssessment.stage === assignment?.stage
+  ) {
+    activeAssessment.resumeAssignment = assignment;
+    return "deferred";
+  }
+  if (queue.some(matches)) return "duplicate";
+  if (front) queue.unshift(assignment);
+  else queue.push(assignment);
+  return "queued";
+}
+
+export function requeueInterruptedAssessment(
+  queue,
+  assessmentState,
+  { accepted, failureReported },
+) {
+  if (accepted || failureReported || !assessmentState?.resumeAssignment) {
+    return false;
+  }
+  return (
+    enqueueWorkspaceAssessment(
+      queue,
+      null,
+      assessmentState.resumeAssignment,
+      { front: true },
+    ) === "queued"
+  );
+}
+
+export function connectorExecution(assignment, options = {}) {
   const rawPrompt = assignment?.prompt_markdown;
   if (typeof rawPrompt !== "string" || !rawPrompt.trim()) {
     throw new Error("EngineerOS assignment is missing prompt_markdown.");
@@ -834,10 +1007,13 @@ export function connectorExecution(assignment, options = {}) {
   };
 }
 
-export async function stopProcess(child) {
-  if (!child || child.exitCode !== null) return;
-  await child.engineerOsCancel?.();
-  if (process.platform === "win32") {
+export async function stopProcess(child) {
+  if (!child || child.exitCode !== null) return;
+  if (typeof child.engineerOsCancel === "function") {
+    await child.engineerOsCancel();
+    return;
+  }
+  if (process.platform === "win32") {
     await run(
       "taskkill",
       ["/pid", String(child.pid), "/t", "/f"],