@engineeros/connector 0.8.9 → 0.9.0

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.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@engineeros/connector",
-  "version": "0.8.9",
+  "version": "0.9.0",
   "description": "Connect a local coding agent to EngineerOS, using ACP when supported.",
   "private": false,
   "type": "module",
@@ -16,7 +16,7 @@
   "scripts": {
     "start": "node ./bin/engineeros-connector.mjs",
     "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 ./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,108 @@
+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 }) {
+  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.");
+  }
+
+  return [
+    "# 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.",
+    "",
+    "## 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.",
+    "",
+    "## Active Skill",
+    "",
+    bundledSkill(role.skill),
+    "",
+    "## Assignment",
+    "",
+    assignment,
+  ].join("\n");
+}
+
+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 },
+    );
+  }
+}

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,7 @@ 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";
 
 const deflate = promisify(deflateRaw);
 const MAX_ARCHIVE_BYTES = 25 * 1024 * 1024;
@@ -117,7 +118,15 @@ export async function executeAssignment(assignment, config, callbacks) {
   );
   const verifier = launchAgentProcess(
     runWorkspace,
-    verificationPrompt(assignment, committed.revision, committed.changedFiles),
+    buildAgentHarnessPrompt({
+      agentRole: "verification",
+      prompt: verificationPrompt(
+        assignment,
+        committed.revision,
+        committed.changedFiles,
+      ),
+      sandboxMode: "read-only",
+    }),
     "read-only",
     config,
     callbacks,
@@ -656,8 +665,8 @@ function assessmentCommandMilestone(command) {
 }
 
 export function connectorExecution(assignment) {
-  const prompt = assignment?.prompt_markdown;
-  if (typeof prompt !== "string" || !prompt.trim()) {
+  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 +685,23 @@ export function connectorExecution(assignment) {
       "EngineerOS assignment has an unsupported reasoning effort.",
     );
   }
+  const agentRole = assignment?.agent_role;
+  const prompt = buildAgentHarnessPrompt({
+    agentRole,
+    prompt: rawPrompt,
+    sandboxMode,
+  });
   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)}`,

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.