@engineeros/connector 0.8.9 → 0.9.1

package/README.md

@@ -26,10 +26,16 @@ npx --yes @engineeros/connector@latest pair PAIRING-CODE --url http://localhost:
 
 Connect a local Codex CLI workspace to EngineerOS through an outbound WebSocket.
 
-This package is only a connector. EngineerOS owns every prompt, Goal instruction, and
-execution boundary. The connector validates the assignment envelope, passes the supplied
-Markdown to Codex CLI unchanged, streams lifecycle events, and returns bounded results.
-It contains no product, assessment, planning, architecture, or delivery prompt templates.
+## Agent roles and skills
+
+The selected ACP or Codex agent is the execution engine. EngineerOS chooses a provider-neutral role for each activity and the connector injects only that role's bundled skill:
+
+- `research` uses `codebase-research` with read-only access for questions and workspace assessment.
+- `planning` uses `change-planning` with read-only access for shaping, specifications, architecture, and design work.
+- `implementation` uses `goal-execution` with workspace-write access only for a registered Goal.
+- `verification` uses `change-verification` with read-only access for artifact review and independent Goal proof.
+
+The connector rejects a role whose access does not match the assignment before starting the agent. Role-specific sessions preserve useful context without mixing planning, research, implementation, or verification responsibilities. A shared interaction contract makes the Agent infer the current project situation, lead with the useful outcome, and suggest one concrete next activity only when it genuinely helps. User-visible responses refer neutrally to the Agent; provider and harness details remain operational metadata.
 
 ## Onboard a workspace
 
@@ -45,7 +51,7 @@ From **Project steering -> Workspace**, run the workspace assessment to use the
 
 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.
 
-Project prompts use resumable, purpose-specific coding-agent sessions. The connector keeps the external session identifiers in its local configuration, so Copilot and artifact conversations survive connector restarts. Changing the purpose, model, or reasoning effort starts a separate session. Goal implementation and verification remain isolated runs.
+Project prompts use resumable, role- and purpose-specific agent sessions. The connector keeps the external session identifiers in its local configuration, so Copilot and artifact conversations survive connector restarts. Changing the role, purpose, model, or reasoning effort starts a separate session. Goal implementation and verification remain isolated runs.
 
 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.
 
@@ -86,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

@@ -396,7 +396,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,9 +553,7 @@ 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;
   const reportedMilestones = new Set();
   const reportProgress = (message, { milestone = true } = {}) => {
@@ -607,9 +605,7 @@ 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) {
     if (socket.readyState === WebSocket.OPEN) {
       socket.send(

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineeros/connector",
-  "version": "0.8.9",
+  "version": "0.9.1",
   "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-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

@@ -0,0 +1,183 @@
+import { readFileSync } from "node:fs";
+
+const ROLE_DEFINITIONS = Object.freeze({
+  research: Object.freeze({
+    title: "Repository Research",
+    sandboxMode: "read-only",
+    skill: "codebase-research",
+    instruction:
+      "Investigate the connected workspace deeply enough to answer from observed evidence. Trace relevant relationships, distinguish facts from inference, and do not change the workspace.",
+  }),
+  planning: Object.freeze({
+    title: "Change Planning",
+    sandboxMode: "read-only",
+    skill: "change-planning",
+    instruction:
+      "Turn the request and current workspace evidence into a decision-complete change plan. Resolve discoverable questions through inspection, state consequential assumptions, and do not implement the plan.",
+  }),
+  implementation: Object.freeze({
+    title: "Goal Implementation",
+    sandboxMode: "workspace-write",
+    skill: "goal-execution",
+    instruction:
+      "Execute the bounded Goal autonomously, keep changes inside its boundary, and verify the result. EngineerOS owns the final commit and acceptance workflow.",
+  }),
+  verification: Object.freeze({
+    title: "Independent Verification",
+    sandboxMode: "read-only",
+    skill: "change-verification",
+    instruction:
+      "Independently inspect and test the supplied revision. Report only directly observed evidence and do not repair or otherwise modify the workspace.",
+  }),
+});
+
+const skillCache = new Map();
+
+export const AGENT_ROLE_IDS = Object.freeze(Object.keys(ROLE_DEFINITIONS));
+export const AGENT_SKILL_IDS = Object.freeze(
+  AGENT_ROLE_IDS.map((roleId) => ROLE_DEFINITIONS[roleId].skill),
+);
+
+export function agentHarnessCapabilities() {
+  return {
+    agent_roles: [...AGENT_ROLE_IDS],
+    agent_skills: [...AGENT_SKILL_IDS],
+  };
+}
+
+export function buildAgentHarnessPrompt({
+  agentRole,
+  prompt,
+  sandboxMode,
+  requiredOutputHeading,
+}) {
+  const role = ROLE_DEFINITIONS[agentRole];
+  if (!role) {
+    throw new Error(
+      `EngineerOS assignment has an unsupported agent_role. Expected one of: ${AGENT_ROLE_IDS.join(", ")}.`,
+    );
+  }
+  if (role.sandboxMode !== sandboxMode) {
+    throw new Error(
+      `EngineerOS ${agentRole} role requires ${role.sandboxMode} access, but the assignment requested ${sandboxMode}.`,
+    );
+  }
+  const assignment = String(prompt || "").trim();
+  if (!assignment) {
+    throw new Error("EngineerOS assignment is missing prompt_markdown.");
+  }
+  const outputHeading = normalizedOutputHeading(requiredOutputHeading);
+
+  const sections = [
+    "# EngineerOS Agent Assignment",
+    "",
+    "## Active Role",
+    "",
+    `- Role: ${role.title}`,
+    `- 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.",
+  ];
+  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",
+    "",
+    bundledSkill(role.skill),
+    "",
+    "## Assignment",
+    "",
+    assignment,
+  );
+  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) {
+  const cached = skillCache.get(skillName);
+  if (cached) return cached;
+  try {
+    const content = readFileSync(
+      new URL(`./skills/${skillName}/SKILL.md`, import.meta.url),
+      "utf8",
+    ).trim();
+    skillCache.set(skillName, content);
+    return content;
+  } catch (error) {
+    throw new Error(
+      `EngineerOS bundled skill '${skillName}' is unavailable. Reinstall @engineeros/connector.`,
+      { cause: error },
+    );
+  }
+}
+
+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/capabilities.mjs

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { agentHarnessCapabilities } from "./agent-harness.mjs";
 
 export function advertisedCapabilities(config, codingAgent) {
   const configuredModels = String(
@@ -15,6 +16,7 @@ export function advertisedCapabilities(config, codingAgent) {
     workspace_name: path.basename(config.workspace),
     agent_name: codingAgent.name,
     agent_version: codingAgent.version,
+    ...agentHarnessCapabilities(),
     execution_profiles: {
       model_selection: codingAgent.protocol === "codex",
       models: codingAgent.protocol === "codex" ? configuredModels : [],

package/src/runner.mjs

@@ -12,6 +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,
+  normalizeAgentStructuredOutput,
+} from "./agent-harness.mjs";
 
 const deflate = promisify(deflateRaw);
 const MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
@@ -109,15 +113,25 @@ 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,
-    verificationPrompt(assignment, committed.revision, committed.changedFiles),
+    buildAgentHarnessPrompt({
+      agentRole: "verification",
+      prompt: verificationPrompt(
+        assignment,
+        committed.revision,
+        committed.changedFiles,
+      ),
+      sandboxMode: "read-only",
+      requiredOutputHeading: verificationHeading,
+    }),
     "read-only",
     config,
     callbacks,
@@ -125,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,
@@ -138,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,
   };
 }
 
@@ -290,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"],
@@ -333,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"],
@@ -495,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,
@@ -655,9 +675,20 @@ function assessmentCommandMilestone(command) {
   return "Tracing architecture and code relationships";
 }
 
-export function connectorExecution(assignment) {
-  const prompt = assignment?.prompt_markdown;
-  if (typeof prompt !== "string" || !prompt.trim()) {
+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.");
   }
   const sandboxMode = assignment?.sandbox_mode;
@@ -676,14 +707,24 @@ export function connectorExecution(assignment) {
       "EngineerOS assignment has an unsupported reasoning effort.",
     );
   }
+  const agentRole = assignment?.agent_role;
+  const prompt = buildAgentHarnessPrompt({
+    agentRole,
+    prompt: rawPrompt,
+    sandboxMode,
+    requiredOutputHeading: options.requiredOutputHeading,
+  });
   return {
     prompt,
+    agentRole,
     sandboxMode,
     sessionKey:
       typeof assignment.session_key === "string" &&
       assignment.session_key.trim()
         ? assignment.session_key.trim()
-        : `project-${String(assignment.purpose || "general")
+        : `project-${String(agentRole)}-${String(
+            assignment.purpose || "general",
+          )
             .toLowerCase()
             .replace(/[^a-z0-9]+/g, "-")
             .slice(0, 80)}`,
@@ -895,7 +936,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)));

package/src/skills/change-planning/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: change-planning
+description: Produce a decision-complete implementation plan grounded in the connected repository.
+---
+
+# Change Planning
+
+1. Inspect current behavior, ownership boundaries, call paths, tests, and project instructions before proposing changes.
+2. Define the intended outcome, affected components, non-goals, risks, and proof of completion.
+3. Resolve questions answerable from the repository. Label only genuinely unavailable facts as assumptions.
+4. Sequence bounded implementation steps with the files or symbols each step affects and the verification it requires.
+5. Stay read-only and hand off a plan that an implementation Agent can execute without rediscovering the problem.

package/src/skills/change-verification/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: change-verification
+description: Independently verify a completed change against its explicit proof contract.
+---
+
+# Change Verification
+
+1. Inspect the exact supplied revision, changed paths, Goal boundaries, constraints, and every Proof item.
+2. Run or inspect each check independently; do not rely on the implementation Agent's claims.
+3. Stay read-only. Do not repair failures, edit files, install dependencies, commit, or push.
+4. Mark a check passed only when directly observed evidence matches its expected result.
+5. Return the requested structured verification report with concise commands, exit codes, and evidence.

package/src/skills/codebase-research/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: codebase-research
+description: Investigate a connected repository and answer from directly observed evidence.
+---
+
+# Codebase Research
+
+1. Define the exact question and inspect the smallest relevant surface first.
+2. Trace callers, dependencies, data flow, configuration, and tests when they materially affect the answer.
+3. Separate observed facts from inferences and cite concrete repository paths for important claims.
+4. Stay read-only. Do not install, generate, edit, delete, commit, or start long-running services.
+5. Return the answer first, followed by supporting evidence and unresolved gaps only when they matter.

package/src/skills/goal-execution/SKILL.md

@@ -0,0 +1,12 @@
+---
+name: goal-execution
+description: Implement one bounded EngineerOS Goal and prove the resulting behavior.
+---
+
+# Goal Execution
+
+1. Read the complete Goal packet, repository instructions, current Git state, and relevant implementation paths.
+2. Implement the smallest coherent change that satisfies the included outcome and constraints.
+3. Preserve unrelated user changes and stay inside the stated boundary; stop only for a genuine missing authority or prerequisite.
+4. Run focused checks while working, then the proportionate final tests, lint, type checks, or build required by the Goal.
+5. Do not commit or push. EngineerOS creates the isolated run commit after the implementation completes.