@engineeros/connector 0.9.2 → 0.10.2

package/src/agent-harness.mjs

@@ -1,183 +1,196 @@
-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;
-}
+import { readFileSync } from "node:fs";
+
+const ROLE_BOUNDARIES = Object.freeze({
+  research: Object.freeze({
+    sandboxMode: "read-only",
+    skill: "codebase-research",
+  }),
+  planning: Object.freeze({
+    sandboxMode: "read-only",
+    skill: "change-planning",
+  }),
+  implementation: Object.freeze({
+    sandboxMode: "workspace-write",
+    skill: "goal-execution",
+  }),
+  verification: Object.freeze({
+    sandboxMode: "read-only",
+    skill: "change-verification",
+  }),
+});
+
+const skillCache = new Map();
+
+export const AGENT_ROLE_IDS = Object.freeze(Object.keys(ROLE_BOUNDARIES));
+export const AGENT_SKILL_IDS = Object.freeze(
+  AGENT_ROLE_IDS.map((roleId) => ROLE_BOUNDARIES[roleId].skill),
+);
+
+export function agentHarnessCapabilities() {
+  return {
+    agent_roles: [...AGENT_ROLE_IDS],
+    agent_skills: [...AGENT_SKILL_IDS],
+  };
+}
+
+export function buildAgentHarnessPrompt({
+  agentRole,
+  agentDefinition,
+  prompt,
+  sandboxMode,
+  requiredOutputHeading,
+}) {
+  const boundary = ROLE_BOUNDARIES[agentRole];
+  if (!boundary) {
+    throw new Error(
+      `EngineerOS assignment has an unsupported agent_role. Expected one of: ${AGENT_ROLE_IDS.join(", ")}.`,
+    );
+  }
+  if (boundary.sandboxMode !== sandboxMode) {
+    throw new Error(
+      `EngineerOS ${agentRole} role requires ${boundary.sandboxMode} access, but the assignment requested ${sandboxMode}.`,
+    );
+  }
+  const role = validatedAgentDefinition(agentDefinition, agentRole, boundary);
+  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.access}`,
+    `- Responsibility: ${role.instruction}`,
+    `- Permitted tools: ${role.tools.length ? role.tools.join(", ") : "none"}`,
+    "- 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");
+}
+
+function validatedAgentDefinition(definition, agentRole, boundary) {
+  if (!definition || typeof definition !== "object") {
+    throw new Error("EngineerOS assignment is missing agent_definition.");
+  }
+  if (definition.role !== agentRole || definition.access !== boundary.sandboxMode) {
+    throw new Error("EngineerOS agent_definition does not match the assigned role and access.");
+  }
+  if (definition.skill !== boundary.skill) {
+    throw new Error(`EngineerOS ${agentRole} role requires the ${boundary.skill} skill.`);
+  }
+  if (
+    typeof definition.title !== "string" ||
+    !definition.title.trim() ||
+    typeof definition.instruction !== "string" ||
+    !definition.instruction.trim() ||
+    !Array.isArray(definition.tools)
+  ) {
+    throw new Error("EngineerOS agent_definition is incomplete.");
+  }
+  return definition;
+}
+
+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/codex-app-server.mjs

@@ -0,0 +1,139 @@
+import { spawn } from "node:child_process";
+import readline from "node:readline";
+
+export function launchCodexAppServer({
+  workspace,
+  prompt,
+  sandbox,
+  profile = {},
+  previousSessionId,
+  callbacks = {},
+  command = process.env.CODEX_BIN || (process.platform === "win32" ? "codex.cmd" : "codex"),
+  spawnProcess = spawn,
+}) {
+  const child = spawnProcess(command, ["app-server", "--stdio"], {
+    cwd: workspace,
+    env: process.env,
+    shell: process.platform === "win32",
+    windowsHide: true,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+  const pending = new Map();
+  let requestId = 0;
+  let threadId = previousSessionId || "";
+  let turnId = "";
+  let finalMessage = "";
+  let stderr = "";
+  let settled = false;
+
+  const request = (method, params) =>
+    new Promise((resolve, reject) => {
+      const id = ++requestId;
+      pending.set(id, { resolve, reject });
+      child.stdin.write(`${JSON.stringify({ id, method, params })}\n`);
+    });
+
+  const completed = new Promise((resolve, reject) => {
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      for (const waiter of pending.values()) waiter.reject(error || new Error("Codex app-server stopped."));
+      pending.clear();
+      if (error) reject(error);
+      else resolve({ finalMessage, output: stderr.slice(-20_000), sessionId: threadId });
+    };
+
+    child.once("error", finish);
+    child.once("close", (code) => {
+      if (!settled) finish(new Error(`Codex app-server exited before completing the turn (code ${code ?? 1}). ${stderr}`));
+    });
+
+    const lines = readline.createInterface({ input: child.stdout });
+    lines.on("line", (line) => {
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        return;
+      }
+      if (message.id !== undefined) {
+        const waiter = pending.get(message.id);
+        if (!waiter) return;
+        pending.delete(message.id);
+        if (message.error) waiter.reject(new Error(message.error.message || "Codex app-server request failed."));
+        else waiter.resolve(message.result);
+        return;
+      }
+      const params = message.params || {};
+      if (message.method === "item/agentMessage/delta" && typeof params.delta === "string") {
+        finalMessage += params.delta;
+        callbacks.onEvent?.({ type: "codex.agent_message_delta", delta: params.delta });
+      } else if (message.method === "item/started" || message.method === "item/completed") {
+        callbacks.onEvent?.({ type: `codex.${message.method}`, item: params.item });
+      } else if (message.method === "thread/tokenUsage/updated") {
+        callbacks.onEvent?.({ type: "codex.usage", update: params });
+      } else if (message.method === "turn/completed" && params.threadId === threadId) {
+        const status = params.turn?.status;
+        if (status === "failed") finish(new Error(params.turn?.error?.message || "Codex turn failed."));
+        else if (!finalMessage.trim()) finish(new Error("Codex completed without returning a response."));
+        else finish();
+        child.kill();
+      }
+    });
+
+    child.stderr.setEncoding("utf8");
+    child.stderr.on("data", (chunk) => {
+      stderr = `${stderr}${chunk}`.slice(-20_000);
+    });
+
+    void (async () => {
+      try {
+        await request("initialize", {
+          clientInfo: { name: "engineeros-connector", title: "EngineerOS Connector", version: "0.10.1" },
+        });
+        child.stdin.write(`${JSON.stringify({ method: "initialized" })}\n`);
+        const threadResult = previousSessionId
+          ? await request("thread/resume", {
+              threadId: previousSessionId,
+              cwd: workspace,
+              sandbox,
+              approvalPolicy: "never",
+              model: profile.model || null,
+            })
+          : await request("thread/start", {
+              cwd: workspace,
+              sandbox,
+              approvalPolicy: "never",
+              model: profile.model || null,
+              ephemeral: false,
+            });
+        threadId = threadResult.thread.id;
+        callbacks.onEvent?.({ type: "thread.started", thread_id: threadId });
+        const turnResult = await request("turn/start", {
+          threadId,
+          input: [{ type: "text", text: prompt }],
+          effort: profile.reasoning_effort || null,
+        });
+        turnId = turnResult.turn.id;
+      } catch (error) {
+        child.kill();
+        finish(error instanceof Error ? error : new Error(String(error)));
+      }
+    })();
+  });
+
+  return {
+    child,
+    completed,
+    cancel: async () => {
+      if (threadId && turnId && !settled) {
+        try {
+          await request("turn/interrupt", { threadId, turnId });
+        } catch {
+          // Process termination below is the final cancellation boundary.
+        }
+      }
+      child.kill();
+    },
+  };
+}