@engineeros/connector 0.13.4 → 0.14.2

package/package.json

@@ -1,41 +1,41 @@
-{
-  "name": "@engineeros/connector",
-  "version": "0.13.4",
-  "description": "Connect a local coding agent to EngineerOS, using ACP when supported.",
-  "private": false,
-  "type": "module",
-  "license": "UNLICENSED",
-  "files": [
-    "bin",
-    "src",
-    "README.md"
-  ],
-  "bin": {
-    "engineeros-connector": "bin/engineeros-connector.mjs"
-  },
-  "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 ./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/codex-app-server.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"
-  },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/vinpuli/engineerosv2.git",
-    "directory": "packages/engineeros-connector"
-  },
-  "bugs": {
-    "url": "https://github.com/vinpuli/engineerosv2/issues"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@agentclientprotocol/sdk": "1.3.0",
-    "zod": "3.25.76"
-  }
-}
+{
+  "name": "@engineeros/connector",
+  "version": "0.14.2",
+  "description": "Connect a local coding agent to EngineerOS, using ACP when supported.",
+  "private": false,
+  "type": "module",
+  "license": "UNLICENSED",
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "bin": {
+    "engineeros-connector": "bin/engineeros-connector.mjs"
+  },
+  "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 ./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/codex-app-server.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"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vinpuli/engineerosv2.git",
+    "directory": "packages/engineeros-connector"
+  },
+  "bugs": {
+    "url": "https://github.com/vinpuli/engineerosv2/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "1.3.0",
+    "zod": "3.25.76"
+  }
+}

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,10 +49,10 @@ export function launchAcpAgent(
       callbacks,
     })
     .finally(async () => {
-      if (!persistent) await runtime.dispose();
-    });
-  runtime.child.engineerOsCancel = () => runtime.dispose();
-  return {
+      if (!persistent) await runtime.dispose();
+    });
+  runtime.child.engineerOsCancel = () => runtime.dispose();
+  return {
     child: runtime.child,
     completed,
     cancel: () => runtime.cancel(sessionKey),
@@ -115,22 +115,23 @@ class AcpRuntime {
     this.onClose = onClose;
     this.sessions = new Map();
     this.turns = new Map();
-    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 || {}) },
-        windowsHide: true,
-        shell:
-          process.platform === "win32" &&
-          /\.(cmd|bat)$/i.test(config.agent_command),
-        stdio: ["pipe", "pipe", "pipe"],
-      },
-    );
+    this.stderr = "";
+    this.disposed = false;
+    this.disposePromise = null;
+    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 || {}) },
+        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);
@@ -158,11 +159,13 @@ class AcpRuntime {
       )
       .connect(stream);
     this.context = this.connection.agent;
-    this.ready = this.initialize();
-    void this.ready.catch(() => {
-      void this.dispose();
-    });
-    this.child.once("exit", () => this.closed());
+    this.ready = this.initialize();
+    void this.ready.catch(() => {
+      void this.dispose();
+    });
+    this.child.stdout.once("end", () => this.closed());
+    this.child.stdout.once("close", () => this.closed());
+    this.child.once("exit", () => this.closed());
     void this.connection.closed.then(
       () => this.closed(),
       () => this.closed(),
@@ -358,13 +361,17 @@ class AcpRuntime {
     });
   }
 
-  isRunning() {
-    return (
-      !this.disposed &&
-      this.child.exitCode === null &&
-      !this.connection.signal.aborted
-    );
-  }
+  isRunning() {
+    return (
+      !this.disposed &&
+      this.childIsRunning() &&
+      !this.connection.signal.aborted
+    );
+  }
+
+  childIsRunning() {
+    return this.child.exitCode === null && this.child.signalCode === null;
+  }
 
   scheduleIdleDisposal() {
     if (this.turns.size || this.disposed) return;
@@ -386,32 +393,44 @@ class AcpRuntime {
     );
   }
 
-  closed() {
-    if (this.disposed) return;
-    this.disposed = true;
-    this.clearIdleTimer();
-    this.onClose?.();
-  }
-
-  async dispose() {
-    if (this.disposed) return;
-    this.disposed = true;
-    this.clearIdleTimer();
-    this.onClose?.();
-    this.connection.close();
-    if (this.child.exitCode === null) {
-      this.child.kill("SIGTERM");
-      await Promise.race([
-        new Promise((resolve) => this.child.once("exit", resolve)),
-        new Promise((resolve) => setTimeout(resolve, 500)),
-      ]);
-    }
-    if (this.child.exitCode === null) this.child.kill("SIGKILL");
-    this.child.stdin.destroy();
-    this.child.stdout.destroy();
-    this.child.stderr.destroy();
-  }
-}
+  closed() {
+    void this.dispose();
+  }
+
+  async dispose() {
+    if (this.disposePromise) return this.disposePromise;
+    this.disposed = true;
+    this.clearIdleTimer();
+    this.onClose?.();
+    this.disposePromise = this.releaseResources();
+    return this.disposePromise;
+  }
+
+  async releaseResources() {
+    try {
+      this.connection.close();
+    } catch {
+      // The ACP transport may already be closed.
+    }
+    if (this.childIsRunning()) {
+      this.child.kill("SIGTERM");
+      await Promise.race([
+        new Promise((resolve) => this.child.once("exit", resolve)),
+        new Promise((resolve) => setTimeout(resolve, 500)),
+      ]);
+    }
+    if (this.childIsRunning()) {
+      this.child.kill("SIGKILL");
+      await Promise.race([
+        new Promise((resolve) => this.child.once("exit", resolve)),
+        new Promise((resolve) => setTimeout(resolve, 500)),
+      ]);
+    }
+    this.child.stdin.destroy();
+    this.child.stdout.destroy();
+    this.child.stderr.destroy();
+  }
+}
 
 export function normalizeTokenUsage(value) {
   if (!value || typeof value !== "object") return null;
@@ -426,11 +445,11 @@ export function normalizeTokenUsage(value) {
     input_tokens: number("inputTokens", "input_tokens"),
     output_tokens: number("outputTokens", "output_tokens"),
     cache_read_tokens: number("cachedReadTokens", "cachedInputTokens", "cache_read_input_tokens"),
-    cache_write_tokens: number(
-      "cachedWriteTokens",
-      "cacheWriteInputTokens",
-      "cache_creation_input_tokens",
-    ),
+    cache_write_tokens: number(
+      "cachedWriteTokens",
+      "cacheWriteInputTokens",
+      "cache_creation_input_tokens",
+    ),
     reasoning_tokens: number("reasoningTokens", "reasoningOutputTokens", "reasoning_tokens"),
   };
   usage.total_tokens = number("totalTokens", "total_tokens") ||

package/src/agent-harness.mjs

@@ -141,15 +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",
-    "# 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];
+  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) ||
@@ -157,34 +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 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;
+  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/codex-app-server.mjs

@@ -103,10 +103,10 @@ export function launchCodexAppServer({
   let threadId = previousSessionId || "";
   let turnId = "";
   let finalMessage = "";
-  let stderr = "";
-  let usage = null;
-  let settled = false;
-  let completionTimer = null;
+  let stderr = "";
+  let usage = null;
+  let settled = false;
+  let completionTimer = null;
 
   const request = (method, params) =>
     new Promise((resolve, reject) => {
@@ -116,10 +116,10 @@ export function launchCodexAppServer({
     });
 
   const completed = new Promise((resolve, reject) => {
-    const finish = (error) => {
-      if (settled) return;
-      settled = true;
-      if (completionTimer) clearTimeout(completionTimer);
+    const finish = (error) => {
+      if (settled) return;
+      settled = true;
+      if (completionTimer) clearTimeout(completionTimer);
       for (const waiter of pending.values()) waiter.reject(error || new Error("Codex app-server stopped."));
       pending.clear();
       if (error) reject(error);
@@ -157,38 +157,38 @@ export function launchCodexAppServer({
       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") {
-        const tokenUsage = params.tokenUsage || params.usage || params;
-        usage = normalizeTokenUsage(
-          previousSessionId
-            ? tokenUsage.last || params.last || tokenUsage
-            : tokenUsage.total || params.total || tokenUsage.last || params.last || tokenUsage,
-        );
-        callbacks.onEvent?.({ type: "codex.usage", update: params });
-        if (usage && completionTimer) {
-          finish();
-          child.kill();
-        }
-      } 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."));
-          child.kill();
-        } else if (!finalMessage.trim()) {
-          finish(new Error("Codex completed without returning a response."));
-          child.kill();
-        } else if (usage) {
-          finish();
-          child.kill();
-        } else if (!completionTimer) {
-          completionTimer = setTimeout(() => {
-            finish();
-            child.kill();
-          }, 250);
-        }
-      }
+      } 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") {
+        const tokenUsage = params.tokenUsage || params.usage || params;
+        usage = normalizeTokenUsage(
+          previousSessionId
+            ? tokenUsage.last || params.last || tokenUsage
+            : tokenUsage.total || params.total || tokenUsage.last || params.last || tokenUsage,
+        );
+        callbacks.onEvent?.({ type: "codex.usage", update: params });
+        if (usage && completionTimer) {
+          finish();
+          child.kill();
+        }
+      } 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."));
+          child.kill();
+        } else if (!finalMessage.trim()) {
+          finish(new Error("Codex completed without returning a response."));
+          child.kill();
+        } else if (usage) {
+          finish();
+          child.kill();
+        } else if (!completionTimer) {
+          completionTimer = setTimeout(() => {
+            finish();
+            child.kill();
+          }, 250);
+        }
+      }
     });
 
     child.stderr.setEncoding("utf8");

package/src/connection.mjs

@@ -1,74 +1,74 @@
-const PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH = 2_000;
-const TRUNCATED_FAILURE_SUFFIX = "\n… [truncated by EngineerOS connector]";
-
-export function describeWebSocketError(event) {
-  return (
-    event?.error?.message ||
-    event?.message ||
-    "The WebSocket connection failed without providing an error detail."
-  );
-}
-
-export function protocolFailureMessage(error) {
-  const raw = error instanceof Error ? error.message : String(error ?? "");
-  const message =
-    raw.trim() || "The connector failed without providing an error detail.";
-  const characters = [...message];
-  if (characters.length <= PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH) return message;
-  const suffix = [...TRUNCATED_FAILURE_SUFFIX];
-  return `${characters
-    .slice(0, PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH - suffix.length)
-    .join("")}${TRUNCATED_FAILURE_SUFFIX}`;
-}
-
-export async function describeRejectedResponse(response, subject) {
-  const responseBody = await response.text();
-  const detail = responseDetail(responseBody);
-  return protocolFailureMessage(
-    `EngineerOS rejected ${subject} (${response.status})${detail ? `: ${detail}` : "."}`,
-  );
-}
-
-export function startConnectionWatchdog(
-  socket,
-  url,
-  { timeoutMs = 15_000, onTimeout = console.error } = {},
-) {
-  const timer = setTimeout(() => {
-    onTimeout(
-      `EngineerOS did not complete the WebSocket handshake at ${url} within ${Math.round(timeoutMs / 1_000)} seconds. Check that the backend is running and the URL is reachable from this machine.`,
-    );
-    try {
-      socket.close();
-    } catch {
-      // Reconnect scheduling is owned by the caller.
-    }
-  }, timeoutMs);
-
-  return () => clearTimeout(timer);
-}
-
-function responseDetail(responseBody) {
-  const body = String(responseBody || "").trim();
-  if (!body) return "";
-  try {
-    const parsed = JSON.parse(body);
-    if (typeof parsed?.detail === "string") return parsed.detail;
-    if (Array.isArray(parsed?.detail)) {
-      return parsed.detail.map(validationIssue).filter(Boolean).join("; ");
-    }
-  } catch {
-    // Plain-text server errors are already useful to the operator.
-  }
-  return body;
-}
-
-function validationIssue(issue) {
-  if (typeof issue === "string") return issue;
-  if (!issue || typeof issue !== "object") return "";
-  const location = Array.isArray(issue.loc) ? issue.loc.join(".") : "";
-  const message = typeof issue.msg === "string" ? issue.msg : "";
-  const type = typeof issue.type === "string" ? ` (${issue.type})` : "";
-  if (!location && !message) return "";
-  return `${location ? `${location}: ` : ""}${message}${type}`;
-}
+const PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH = 2_000;
+const TRUNCATED_FAILURE_SUFFIX = "\n… [truncated by EngineerOS connector]";
+
+export function describeWebSocketError(event) {
+  return (
+    event?.error?.message ||
+    event?.message ||
+    "The WebSocket connection failed without providing an error detail."
+  );
+}
+
+export function protocolFailureMessage(error) {
+  const raw = error instanceof Error ? error.message : String(error ?? "");
+  const message =
+    raw.trim() || "The connector failed without providing an error detail.";
+  const characters = [...message];
+  if (characters.length <= PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH) return message;
+  const suffix = [...TRUNCATED_FAILURE_SUFFIX];
+  return `${characters
+    .slice(0, PROTOCOL_FAILURE_MESSAGE_MAX_LENGTH - suffix.length)
+    .join("")}${TRUNCATED_FAILURE_SUFFIX}`;
+}
+
+export async function describeRejectedResponse(response, subject) {
+  const responseBody = await response.text();
+  const detail = responseDetail(responseBody);
+  return protocolFailureMessage(
+    `EngineerOS rejected ${subject} (${response.status})${detail ? `: ${detail}` : "."}`,
+  );
+}
+
+export function startConnectionWatchdog(
+  socket,
+  url,
+  { timeoutMs = 15_000, onTimeout = console.error } = {},
+) {
+  const timer = setTimeout(() => {
+    onTimeout(
+      `EngineerOS did not complete the WebSocket handshake at ${url} within ${Math.round(timeoutMs / 1_000)} seconds. Check that the backend is running and the URL is reachable from this machine.`,
+    );
+    try {
+      socket.close();
+    } catch {
+      // Reconnect scheduling is owned by the caller.
+    }
+  }, timeoutMs);
+
+  return () => clearTimeout(timer);
+}
+
+function responseDetail(responseBody) {
+  const body = String(responseBody || "").trim();
+  if (!body) return "";
+  try {
+    const parsed = JSON.parse(body);
+    if (typeof parsed?.detail === "string") return parsed.detail;
+    if (Array.isArray(parsed?.detail)) {
+      return parsed.detail.map(validationIssue).filter(Boolean).join("; ");
+    }
+  } catch {
+    // Plain-text server errors are already useful to the operator.
+  }
+  return body;
+}
+
+function validationIssue(issue) {
+  if (typeof issue === "string") return issue;
+  if (!issue || typeof issue !== "object") return "";
+  const location = Array.isArray(issue.loc) ? issue.loc.join(".") : "";
+  const message = typeof issue.msg === "string" ? issue.msg : "";
+  const type = typeof issue.type === "string" ? ` (${issue.type})` : "";
+  if (!location && !message) return "";
+  return `${location ? `${location}: ` : ""}${message}${type}`;
+}