@engineeros/connector 0.16.1 → 0.17.0

package/src/codex-app-server.mjs

@@ -1,250 +0,0 @@
-import { spawn } from "node:child_process";
-import readline from "node:readline";
-import { normalizeTokenUsage } from "./acp-client.mjs";
-
-export async function inspectCodexExecutionProfiles({
-  workspace,
-  command = process.env.CODEX_BIN || (process.platform === "win32" ? "codex.cmd" : "codex"),
-  spawnProcess = spawn,
-  timeoutMs = 15_000,
-}) {
-  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 stderr = "";
-  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 lines = readline.createInterface({ input: child.stdout });
-  lines.on("line", (line) => {
-    try {
-      const message = JSON.parse(line);
-      const waiter = pending.get(message.id);
-      if (!waiter) return;
-      pending.delete(message.id);
-      if (message.error) waiter.reject(new Error(message.error.message || "Codex model discovery failed."));
-      else waiter.resolve(message.result);
-    } catch {
-      // Ignore non-protocol output.
-    }
-  });
-  child.stderr.setEncoding("utf8");
-  child.stderr.on("data", (chunk) => { stderr = `${stderr}${chunk}`.slice(-4_000); });
-  const rejectPending = (message) => {
-    for (const waiter of pending.values()) waiter.reject(new Error(message));
-    pending.clear();
-  };
-  child.once("error", (error) => rejectPending(error.message));
-  child.once("close", (code) => {
-    if (pending.size) rejectPending(`Codex model discovery stopped with code ${code ?? 1}. ${stderr}`.trim());
-  });
-  const timeout = setTimeout(() => {
-    rejectPending("Codex model discovery timed out.");
-    child.kill();
-  }, timeoutMs);
-  try {
-    await request("initialize", {
-      clientInfo: { name: "engineeros-connector", title: "EngineerOS Connector", version: "0.11.0" },
-    });
-    child.stdin.write(`${JSON.stringify({ method: "initialized" })}\n`);
-    const models = [];
-    let cursor = null;
-    do {
-      const result = await request("model/list", { cursor, includeHidden: false });
-      models.push(...(Array.isArray(result?.data) ? result.data : []));
-      cursor = result?.nextCursor || null;
-    } while (cursor);
-    return models.map((item) => ({
-      id: item.model || item.id,
-      name: item.displayName || item.model || item.id,
-      description: item.description || "",
-      is_default: item.isDefault === true,
-      default_reasoning_effort: item.defaultReasoningEffort || null,
-      reasoning_efforts: (item.supportedReasoningEfforts || [])
-        .map((option) => option.reasoningEffort)
-        .filter(Boolean),
-    })).filter((item) => item.id);
-  } catch (error) {
-    const detail = error instanceof Error ? error.message : String(error);
-    throw new Error(`${detail}${stderr ? ` ${stderr}` : ""}`.trim());
-  } finally {
-    clearTimeout(timeout);
-    child.kill();
-  }
-}
-
-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 usage = null;
-  let settled = false;
-  let completionTimer = null;
-
-  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;
-      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);
-      else resolve({
-        finalMessage,
-        output: stderr.slice(-20_000),
-        model: profile.model || "codex-app-server",
-        sessionId: threadId,
-        usage,
-      });
-    };
-
-    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") {
-        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");
-    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.11.0" },
-        });
-        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;
-        await callbacks.onSession?.(threadId);
-        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();
-    },
-  };
-}

package/src/config.mjs

@@ -1,109 +0,0 @@
-import { createHash } from "node:crypto";
-import { chmod, mkdir, readFile, writeFile } from "node:fs/promises";
-import os from "node:os";
-import path from "node:path";
-
-export function configPath(workspace = process.cwd()) {
-  const key = createHash("sha256")
-    .update(path.resolve(workspace))
-    .digest("hex")
-    .slice(0, 24);
-  return path.join(os.homedir(), ".engineeros", "connectors", `${key}.json`);
-}
-
-export function socketUrl(value) {
-  const url = new URL(value);
-  if (url.protocol === "http:") url.protocol = "ws:";
-  if (url.protocol === "https:") url.protocol = "wss:";
-  if (!["ws:", "wss:"].includes(url.protocol)) {
-    throw new Error("EngineerOS URL must use http, https, ws, or wss.");
-  }
-  url.pathname = "/api/v1/agent-connectors/ws";
-  url.search = "";
-  url.hash = "";
-  return url.toString();
-}
-
-export function connectorResumeCredentials(config, serverUrl) {
-  if (
-    !config?.connector_id ||
-    !config.token ||
-    config.server_url !== serverUrl
-  ) {
-    return {};
-  }
-  return {
-    existing_connector_id: config.connector_id,
-    existing_token: config.token,
-  };
-}
-
-export function mergePairedConfig(
-  requestedConfig,
-  existingConfig,
-  connectorId,
-  token,
-) {
-  const preserved =
-    existingConfig?.connector_id === connectorId ? existingConfig : {};
-  const sameAgent =
-    preserved.agent_protocol === requestedConfig.agent_protocol &&
-    (preserved.agent_id || preserved.agent_command || null) ===
-      (requestedConfig.agent_id || requestedConfig.agent_command || null) &&
-    (preserved.agent_version || null) ===
-      (requestedConfig.agent_version || null);
-  return {
-    ...preserved,
-    ...requestedConfig,
-    connector_id: connectorId,
-    token,
-    sessions: sameAgent ? preserved.sessions || {} : {},
-  };
-}
-
-export function resultUrl(websocketUrl, connectorId, runId) {
-  const url = new URL(websocketUrl);
-  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
-  url.pathname = `/api/v1/agent-connectors/${connectorId}/runs/${runId}/result`;
-  return url.toString();
-}
-
-export function workspaceUrl(websocketUrl, connectorId) {
-  const url = new URL(websocketUrl);
-  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
-  url.pathname = `/api/v1/agent-connectors/${connectorId}/workspace`;
-  return url.toString();
-}
-
-export function assessmentResultUrl(websocketUrl, connectorId, assessmentId) {
-  const url = new URL(websocketUrl);
-  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
-  url.pathname = `/api/v1/agent-connectors/${connectorId}/assessment/${assessmentId}/result`;
-  return url.toString();
-}
-
-export function artifactToolUrl(websocketUrl, connectorId) {
-  const url = new URL(websocketUrl);
-  url.protocol = url.protocol === "wss:" ? "https:" : "http:";
-  url.pathname = `/api/v1/agent-connectors/${connectorId}/artifact-tools`;
-  return url.toString();
-}
-
-export async function loadConfig(workspace = process.cwd()) {
-  try {
-    return JSON.parse(await readFile(configPath(workspace), "utf8"));
-  } catch (error) {
-    if (error?.code === "ENOENT") return null;
-    throw error;
-  }
-}
-
-export async function saveConfig(config) {
-  const target = configPath(config.workspace);
-  await mkdir(path.dirname(target), { recursive: true });
-  await writeFile(target, `${JSON.stringify(config, null, 2)}\n`, {
-    encoding: "utf8",
-    mode: 0o600,
-  });
-  if (process.platform !== "win32") await chmod(target, 0o600);
-}

package/src/connection.mjs

@@ -1,80 +0,0 @@
-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 sendConnectionMessage(activeSocket, connection, message) {
-  if (activeSocket !== connection || connection.readyState !== 1) return false;
-  connection.send(JSON.stringify(message));
-  return true;
-}
-
-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}`;
-}

package/src/mcp-server.mjs

@@ -1,256 +0,0 @@
-import readline from "node:readline";
-
-import { artifactToolUrl } from "./config.mjs";
-
-const PROTOCOL_VERSION = "2025-06-18";
-
-const ARTIFACT_TYPES = [
-  "vision",
-  "problem",
-  "capability",
-  "epic",
-  "feature",
-  "story",
-  "architecture",
-  "service",
-  "api",
-  "data_model",
-  "event",
-  "task",
-  "release",
-  "risk",
-  "pattern",
-  "technology",
-  "agent",
-  "workflow",
-  "review",
-  "comment",
-];
-
-const artifactTypeSchema = { type: "string", enum: ARTIFACT_TYPES };
-const artifactIdSchema = {
-  type: "string",
-  format: "uuid",
-  description: "The saved EngineerOS artifact ID.",
-};
-
-export const artifactTools = [
-  {
-    name: "engineeros_list_artifacts",
-    description: "List saved artifacts in the current EngineerOS project.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        artifact_type: artifactTypeSchema,
-        status: { type: "string", enum: ["draft", "active", "archived"] },
-        page: { type: "integer", minimum: 1 },
-        page_size: { type: "integer", minimum: 1, maximum: 50 },
-      },
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: true, destructiveHint: false },
-  },
-  {
-    name: "engineeros_get_artifact",
-    description: "Load one saved artifact from the current EngineerOS project.",
-    inputSchema: {
-      type: "object",
-      properties: { artifact_id: artifactIdSchema },
-      required: ["artifact_id"],
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: true, destructiveHint: false },
-  },
-  {
-    name: "engineeros_create_artifact",
-    description:
-      "Create a saved EngineerOS artifact during the currently approved writable Goal.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        artifact_type: artifactTypeSchema,
-        name: { type: "string", minLength: 1, maxLength: 500 },
-        content: {
-          type: "string",
-          minLength: 1,
-          description: "Complete artifact content as structured Markdown.",
-        },
-        metadata_info: { type: "object" },
-      },
-      required: ["artifact_type", "name", "content"],
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: false, destructiveHint: false },
-  },
-  {
-    name: "engineeros_update_artifact",
-    description:
-      "Update a saved EngineerOS artifact during the currently approved writable Goal.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        artifact_id: artifactIdSchema,
-        artifact_type: artifactTypeSchema,
-        name: { type: "string", minLength: 1, maxLength: 500 },
-        content: {
-          type: "string",
-          minLength: 1,
-          description: "Complete replacement content as structured Markdown.",
-        },
-        metadata_info: { type: "object" },
-      },
-      required: ["artifact_id"],
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: false, destructiveHint: false },
-  },
-  {
-    name: "engineeros_reclassify_artifact",
-    description:
-      "Move a saved artifact to another EngineerOS classification during the currently approved writable Goal.",
-    inputSchema: {
-      type: "object",
-      properties: {
-        artifact_id: artifactIdSchema,
-        target_artifact_type: artifactTypeSchema,
-      },
-      required: ["artifact_id", "target_artifact_type"],
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: false, destructiveHint: false },
-  },
-  {
-    name: "engineeros_materialize_product_artifacts",
-    description:
-      "Materialize structured Product documents into the canonical EngineerOS Vision, Portfolio capabilities, and project graph during the currently approved writable Goal.",
-    inputSchema: {
-      type: "object",
-      properties: {},
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: false, destructiveHint: false },
-  },
-  {
-    name: "engineeros_delete_artifact",
-    description:
-      "Soft-delete a saved EngineerOS artifact during the currently approved writable Goal.",
-    inputSchema: {
-      type: "object",
-      properties: { artifact_id: artifactIdSchema },
-      required: ["artifact_id"],
-      additionalProperties: false,
-    },
-    annotations: { readOnlyHint: false, destructiveHint: true },
-  },
-];
-
-const toolNames = new Map(
-  artifactTools.map((tool) => [tool.name, tool.name.replace("engineeros_", "")]),
-);
-
-export async function handleMcpRequest(message, context) {
-  if (message.method === "notifications/initialized") return null;
-  if (message.method === "initialize") {
-    return success(message.id, {
-      protocolVersion: message.params?.protocolVersion || PROTOCOL_VERSION,
-      capabilities: { tools: { listChanged: false } },
-      serverInfo: { name: "engineeros-connector", version: context.version },
-    });
-  }
-  if (message.method === "ping") return success(message.id, {});
-  if (message.method === "tools/list") {
-    return success(message.id, { tools: artifactTools });
-  }
-  if (message.method === "tools/call") {
-    const tool = toolNames.get(message.params?.name);
-    if (!tool) return failure(message.id, -32602, "Unknown EngineerOS artifact tool.");
-    try {
-      const response = await callArtifactTool(context, tool, message.params?.arguments || {});
-      return success(message.id, {
-        content: [{ type: "text", text: renderArtifactToolResult(response) }],
-        isError: false,
-      });
-    } catch (error) {
-      return success(message.id, {
-        content: [
-          {
-            type: "text",
-            text: `# EngineerOS artifact tool failed\n\n${error instanceof Error ? error.message : String(error)}`,
-          },
-        ],
-        isError: true,
-      });
-    }
-  }
-  return failure(message.id, -32601, `Unsupported MCP method: ${message.method}`);
-}
-
-export async function runMcpServer({ config, runId, version, input, output, fetchImpl = fetch }) {
-  const context = { config, runId, version, fetchImpl };
-  const lines = readline.createInterface({ input, crlfDelay: Infinity });
-  for await (const line of lines) {
-    if (!line.trim()) continue;
-    let response;
-    try {
-      response = await handleMcpRequest(JSON.parse(line), context);
-    } catch (error) {
-      response = failure(null, -32700, error instanceof Error ? error.message : String(error));
-    }
-    if (response) output.write(`${JSON.stringify(response)}\n`);
-  }
-}
-
-async function callArtifactTool(context, tool, arguments_) {
-  const response = await context.fetchImpl(
-    artifactToolUrl(context.config.server_url, context.config.connector_id),
-    {
-      method: "POST",
-      headers: {
-        "Content-Type": "application/json",
-        Authorization: `Bearer ${context.config.token}`,
-      },
-      body: JSON.stringify({ run_id: context.runId, tool, arguments: arguments_ }),
-    },
-  );
-  if (!response.ok) {
-    const detail = await response.text();
-    throw new Error(`EngineerOS rejected ${tool} (${response.status}): ${detail}`);
-  }
-  return response.json();
-}
-
-function renderArtifactToolResult(result) {
-  const lines = ["# EngineerOS artifact tool result", "", result.message || "Completed."];
-  if (result.vision_id) lines.push("", `- Vision ID: \`${result.vision_id}\``);
-  if (Array.isArray(result.capability_ids) && result.capability_ids.length) {
-    lines.push(`- Capability IDs: ${result.capability_ids.map((id) => `\`${id}\``).join(", ")}`);
-  }
-  if (result.artifact) lines.push("", ...artifactMarkdown(result.artifact));
-  if (Array.isArray(result.artifacts)) {
-    lines.push("", `## Artifacts (${result.total ?? result.artifacts.length})`, "");
-    for (const artifact of result.artifacts) {
-      lines.push(`- **${artifact.name}** — \`${artifact.artifact_type}\` — \`${artifact.id}\``);
-    }
-  }
-  return lines.join("\n");
-}
-
-function artifactMarkdown(artifact) {
-  return [
-    `## ${artifact.name}`,
-    "",
-    `- ID: \`${artifact.id}\``,
-    `- Type: \`${artifact.artifact_type}\``,
-    `- Status: \`${artifact.status}\``,
-    "",
-    artifact.content || "",
-  ];
-}
-
-function success(id, result) {
-  return { jsonrpc: "2.0", id, result };
-}
-
-function failure(id, code, message) {
-  return { jsonrpc: "2.0", id, error: { code, message } };
-}