@engineeros/connector 0.9.0 → 0.9.2

package/README.md

@@ -92,3 +92,13 @@ npm install -g @openai/codex@latest
 codex --version
 npx @engineeros/connector start --workspace .
 ```
+
+## Publish the connector
+
+Run the release workflow from this package instead of calling `npm publish` directly:
+
+```sh
+npm run release:patch
+```
+
+The workflow checks the versions already present on npm, keeps the current version when it is unpublished, or advances to the next unused patch version when necessary. It then runs the connector tests, syntax checks, and package dry run before publishing. A direct `npm publish` now stops early with the corrective command when its version already exists.

package/bin/engineeros-connector.mjs

@@ -13,6 +13,7 @@ import {
 } from "../src/config.mjs";
 import {
   assessmentProgressMessage,
+  assessmentStreamDelta,
   applyAcceptedChange,
   executeAssignment,
   executeConnectedPrompt,
@@ -396,7 +397,7 @@ async function submitWorkspaceSnapshot() {
       `Sent ${snapshot.file_count} safe file(s); ${snapshot.excluded_file_count} sensitive or generated path(s) excluded.`,
     );
     console.log(
-      `Workspace assessed as ${result.workspace_kind}. EngineerOS System State is current.`,
+      `Workspace inventory registered as ${result.workspace_kind}. Assessment queued.`,
     );
     snapshotInFlight = false;
   } catch (error) {
@@ -553,10 +554,11 @@ async function cancelPrompt(promptState) {
 
 async function executeAssessment(assignment) {
   const assessmentId = assignment.assessment_id;
-  console.log(
-    `Assessing workspace with ${codingAgent.name} (${assessmentId}).`,
-  );
+  console.log(`Agent is assessing the workspace (${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)
@@ -572,6 +574,40 @@ async function executeAssessment(assignment) {
       }),
     );
   };
+  const flushOutput = () => {
+    if (outputTimer) clearTimeout(outputTimer);
+    outputTimer = undefined;
+    const output = outputBuffer;
+    outputBuffer = "";
+    if (
+      !output ||
+      socket.readyState !== WebSocket.OPEN ||
+      active?.runId !== assessmentId
+    ) {
+      return;
+    }
+    for (let offset = 0; offset < output.length; offset += 50_000) {
+      socket.send(
+        JSON.stringify({
+          type: "workspace.assessment.output",
+          assessment_id: assessmentId,
+          delta: output.slice(offset, offset + 50_000),
+        }),
+      );
+    }
+  };
+  const reportOutput = (delta) => {
+    const remaining = 120_000 - outputLength;
+    if (!delta || remaining <= 0) return;
+    const bounded = String(delta).slice(0, remaining);
+    outputBuffer += bounded;
+    outputLength += bounded.length;
+    if (outputBuffer.length >= 50_000) {
+      flushOutput();
+    } else if (!outputTimer) {
+      outputTimer = setTimeout(flushOutput, 500);
+    }
+  };
   reportProgress("Starting read-only repository assessment");
   const heartbeat = setInterval(() => {
     progress = Math.min(90, progress + 5);
@@ -587,10 +623,12 @@ async function executeAssessment(assignment) {
         if (active?.runId === assessmentId) active.child = child;
       },
       onEvent: (event) => {
+        reportOutput(assessmentStreamDelta(event));
         const message = assessmentProgressMessage(event);
         if (message) reportProgress(message);
       },
     });
+    flushOutput();
     const response = await fetch(
       assessmentResultUrl(config.server_url, config.connector_id, assessmentId),
       {
@@ -607,10 +645,9 @@ async function executeAssessment(assignment) {
         `EngineerOS rejected the assessment (${response.status}): ${await response.text()}`,
       );
     }
-    console.log(
-      `${codingAgent.name} workspace assessment is current in EngineerOS.`,
-    );
+    console.log("Workspace assessment is current in EngineerOS.");
   } catch (error) {
+    flushOutput();
     if (socket.readyState === WebSocket.OPEN) {
       socket.send(
         JSON.stringify({
@@ -622,6 +659,7 @@ async function executeAssessment(assignment) {
     }
     console.error(error instanceof Error ? error.message : String(error));
   } finally {
+    if (outputTimer) clearTimeout(outputTimer);
     clearInterval(heartbeat);
     active = null;
     pump();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineeros/connector",
-  "version": "0.9.0",
+  "version": "0.9.2",
   "description": "Connect a local coding agent to EngineerOS, using ACP when supported.",
   "private": false,
   "type": "module",
@@ -15,8 +15,10 @@
   },
   "scripts": {
     "start": "node ./bin/engineeros-connector.mjs",
+    "prepublishOnly": "node ./scripts/release.mjs check",
+    "release:patch": "node ./scripts/release.mjs patch",
     "test": "node --test --test-concurrency=1",
-    "type-check": "node --check ./bin/engineeros-connector.mjs && node --check ./src/acp-client.mjs && node --check ./src/agent-harness.mjs && node --check ./src/agent-registry.mjs && node --check ./src/capabilities.mjs && node --check ./src/cli-args.mjs && node --check ./src/config.mjs && node --check ./src/connection.mjs && node --check ./src/mcp-server.mjs && node --check ./src/runner.mjs"
+    "type-check": "node --check ./bin/engineeros-connector.mjs && node --check ./scripts/release.mjs && node --check ./src/acp-client.mjs && node --check ./src/agent-harness.mjs && node --check ./src/agent-registry.mjs && node --check ./src/capabilities.mjs && node --check ./src/cli-args.mjs && node --check ./src/config.mjs && node --check ./src/connection.mjs && node --check ./src/mcp-server.mjs && node --check ./src/runner.mjs"
   },
   "engines": {
     "node": ">=22"

package/src/agent-harness.mjs

@@ -45,7 +45,12 @@ export function agentHarnessCapabilities() {
   };
 }
 
-export function buildAgentHarnessPrompt({ agentRole, prompt, sandboxMode }) {
+export function buildAgentHarnessPrompt({
+  agentRole,
+  prompt,
+  sandboxMode,
+  requiredOutputHeading,
+}) {
   const role = ROLE_DEFINITIONS[agentRole];
   if (!role) {
     throw new Error(
@@ -61,8 +66,9 @@ export function buildAgentHarnessPrompt({ agentRole, prompt, sandboxMode }) {
   if (!assignment) {
     throw new Error("EngineerOS assignment is missing prompt_markdown.");
   }
+  const outputHeading = normalizedOutputHeading(requiredOutputHeading);
 
-  return [
+  const sections = [
     "# EngineerOS Agent Assignment",
     "",
     "## Active Role",
@@ -71,13 +77,20 @@ export function buildAgentHarnessPrompt({ agentRole, prompt, sandboxMode }) {
     `- Access: ${role.sandboxMode}`,
     `- Responsibility: ${role.instruction}`,
     "- User-facing language: refer to yourself neutrally as the Agent. Do not expose internal role, harness, provider, or coding-agent terminology unless the user asks.",
-    "",
-    "## Interaction Contract",
-    "",
-    "- Infer the current project situation from the assignment and workspace evidence before responding.",
-    "- Lead with the useful answer or outcome. Do not narrate routine searches, tool calls, or internal work.",
-    "- When one next activity clearly follows and would help, offer exactly one short, concrete suggestion. Do not force a next step when none is useful.",
-    "- Ask a question only when a consequential choice cannot be resolved from available evidence.",
+  ];
+  if (!outputHeading) {
+    sections.push(
+      "",
+      "## Interaction Contract",
+      "",
+      "- Infer the current project situation from the assignment and workspace evidence before responding.",
+      "- Lead with the useful answer or outcome. Do not narrate routine searches, tool calls, or internal work.",
+      "- When one next activity clearly follows and would help, offer exactly one short, concrete suggestion. Do not force a next step when none is useful.",
+      "- Ask a question only when a consequential choice cannot be resolved from available evidence.",
+      "- If the Assignment defines a response format, follow it exactly instead of adding conversational guidance.",
+    );
+  }
+  sections.push(
     "",
     "## Active Skill",
     "",
@@ -86,7 +99,58 @@ export function buildAgentHarnessPrompt({ agentRole, prompt, sandboxMode }) {
     "## Assignment",
     "",
     assignment,
-  ].join("\n");
+  );
+  if (outputHeading) {
+    sections.push(
+      "",
+      "## Final Response Contract",
+      "",
+      "- Return only the structured Markdown required by the Assignment.",
+      `- The first non-whitespace line must be exactly: ${outputHeading}`,
+      "- Do not add a preamble, status message, commentary, or code fence.",
+      "- Do not append a conversational summary or next activity.",
+    );
+  }
+  return sections.join("\n");
+}
+
+export function normalizeAgentStructuredOutput(
+  response,
+  requiredOutputHeading,
+) {
+  const outputHeading = normalizedOutputHeading(requiredOutputHeading);
+  if (!outputHeading) {
+    throw new Error(
+      "EngineerOS structured output requires a heading contract.",
+    );
+  }
+  const content = String(response || "").trim();
+  if (!content) {
+    throw new Error("Agent completed without returning a response.");
+  }
+  const lines = content.split(/\r?\n/);
+  const headingIndex = lines.findIndex(
+    (line, index) => index < 20 && line.trim() === outputHeading,
+  );
+  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}'.`,
+    );
+  }
+  if (preamble.length > 2_000) {
+    throw new Error(
+      `Agent response contains too much text before the required heading '${outputHeading}'.`,
+    );
+  }
+  const normalized = lines.slice(headingIndex).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 normalized;
 }
 
 function bundledSkill(skillName) {
@@ -106,3 +170,14 @@ function bundledSkill(skillName) {
     );
   }
 }
+
+function normalizedOutputHeading(value) {
+  if (value === undefined || value === null) return null;
+  const heading = String(value).trim();
+  if (!/^# [^\r\n]+$/.test(heading)) {
+    throw new Error(
+      "EngineerOS requiredOutputHeading must be one level-one Markdown heading.",
+    );
+  }
+  return heading;
+}

package/src/runner.mjs

@@ -12,7 +12,10 @@ import path from "node:path";
 import { promisify } from "node:util";
 import { deflateRaw } from "node:zlib";
 import { launchAcpAgent } from "./acp-client.mjs";
-import { buildAgentHarnessPrompt } from "./agent-harness.mjs";
+import {
+  buildAgentHarnessPrompt,
+  normalizeAgentStructuredOutput,
+} from "./agent-harness.mjs";
 
 const deflate = promisify(deflateRaw);
 const MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
@@ -110,12 +113,13 @@ export async function executeAssignment(assignment, config, callbacks) {
   await controller.completed;
   const changedFiles = await changedFilePaths(runWorkspace);
   if (!changedFiles.length)
-    throw new Error("Codex completed without changing any files.");
+    throw new Error("Agent completed without changing any files.");
   const committed = await commitRunChange(
     runWorkspace,
     assignment.base_revision,
     assignment.run_id,
   );
+  const verificationHeading = "# Verification Report";
   const verifier = launchAgentProcess(
     runWorkspace,
     buildAgentHarnessPrompt({
@@ -126,6 +130,7 @@ export async function executeAssignment(assignment, config, callbacks) {
         committed.changedFiles,
       ),
       sandboxMode: "read-only",
+      requiredOutputHeading: verificationHeading,
     }),
     "read-only",
     config,
@@ -134,8 +139,12 @@ export async function executeAssignment(assignment, config, callbacks) {
   );
   callbacks.onProcess?.(verifier.child);
   const verification = await verifier.completed;
-  const proofEvidence = parseVerificationReport(
+  const verificationReport = normalizeAgentStructuredOutput(
     verification.finalMessage,
+    verificationHeading,
+  );
+  const proofEvidence = parseVerificationReport(
+    verificationReport,
     assignment.proof_checks,
     config.connector_id,
     assignment.run_id,
@@ -147,7 +156,7 @@ export async function executeAssignment(assignment, config, callbacks) {
     diff_patch: committed.diffPatch,
     changed_files: committed.changedFiles,
     proof_evidence: proofEvidence,
-    verification_report: verification.finalMessage,
+    verification_report: verificationReport,
   };
 }
 
@@ -299,7 +308,7 @@ export async function executeWorkspaceAssessment(
   config,
   callbacks,
 ) {
-  const execution = connectorExecution(assignment);
+  const execution = workspaceAssessmentExecution(assignment);
   const startingRevision = await run(
     "git",
     ["rev-parse", "HEAD"],
@@ -342,8 +351,10 @@ export async function executeWorkspaceAssessment(
   );
   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.");
+  const report = normalizeAgentStructuredOutput(
+    completed.finalMessage,
+    execution.requiredOutputHeading,
+  );
   const endingRevision = await run(
     "git",
     ["rev-parse", "HEAD"],
@@ -504,7 +515,7 @@ export async function executeConnectedPrompt(assignment, config, callbacks) {
   const completed = await controller.completed;
   const content = completed.finalMessage.trim();
   if (!content) {
-    throw new Error("Codex completed without returning a response.");
+    throw new Error("Agent completed without returning a response.");
   }
   return {
     content,
@@ -640,6 +651,14 @@ export function promptStreamEvent(event) {
   return message ? { kind: "status", message } : null;
 }
 
+export function assessmentStreamDelta(event) {
+  const streamEvent = promptStreamEvent(event);
+  if (streamEvent?.kind !== "message" || !streamEvent.delta) return null;
+  return event.type === "item.completed"
+    ? `${streamEvent.delta.trim()}\n\n`
+    : streamEvent.delta;
+}
+
 function assessmentCommandMilestone(command) {
   const value = Array.isArray(command)
     ? command.join(" ")
@@ -664,7 +683,18 @@ function assessmentCommandMilestone(command) {
   return "Tracing architecture and code relationships";
 }
 
-export function connectorExecution(assignment) {
+export function workspaceAssessmentExecution(assignment) {
+  const requiredOutputHeading =
+    assignment?.assessment_mode === "incremental"
+      ? "# Workspace Assessment Delta"
+      : "# Workspace Assessment";
+  return {
+    ...connectorExecution(assignment, { requiredOutputHeading }),
+    requiredOutputHeading,
+  };
+}
+
+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.");
@@ -690,6 +720,7 @@ export function connectorExecution(assignment) {
     agentRole,
     prompt: rawPrompt,
     sandboxMode,
+    requiredOutputHeading: options.requiredOutputHeading,
   });
   return {
     prompt,
@@ -913,7 +944,7 @@ function launchCodexProcess(
       else if (code === 0)
         reject(
           new Error(
-            "Codex completed without announcing a resumable session id.",
+            "Agent completed without announcing a resumable session id.",
           ),
         );
       else reject(new Error(codexFailureMessage(output, code)));