@engineeros/connector 0.10.4 → 0.11.1

package/bin/engineeros-connector.mjs

@@ -1,779 +1,790 @@
-#!/usr/bin/env node
-import os from "node:os";
-import path from "node:path";
-import {
-  assessmentResultUrl,
-  connectorResumeCredentials,
-  loadConfig,
-  mergePairedConfig,
-  resultUrl,
-  saveConfig,
-  socketUrl,
-  workspaceUrl,
-} from "../src/config.mjs";
-import {
-  assessmentProgressMessage,
-  assessmentStreamDelta,
-  applyAcceptedChange,
-  executeAssignment,
-  executeConnectedPrompt,
-  executeWorkspaceAssessment,
-  inspectCodingAgent,
-  promptStreamEvent,
-  stopProcess,
-  workspaceSnapshot,
-} from "../src/runner.mjs";
-import { disposeAcpRuntimes } from "../src/acp-client.mjs";
-import {
-  installRegisteredAgent,
-  inspectRegisteredAgent,
-  registeredAgentConfig,
-  registeredAgents,
-} from "../src/agent-registry.mjs";
-import {
-  describeWebSocketError,
-  startConnectionWatchdog,
-} from "../src/connection.mjs";
-import { advertisedCapabilities } from "../src/capabilities.mjs";
-import { parseConnectorArgs } from "../src/cli-args.mjs";
-import { runMcpServer } from "../src/mcp-server.mjs";
-import packageJson from "../package.json" with { type: "json" };
-
-const { command, positional, flags } = parseConnectorArgs(
-  process.argv.slice(2),
-);
-
-if (command === "agents") {
-  let agents;
-  try {
-    agents = await registeredAgents();
-  } catch (error) {
-    fail(error instanceof Error ? error.message : String(error));
-  }
-  const statuses = await Promise.all(
-    agents.map(async (agent) => {
-      try {
-        await inspectRegisteredAgent(agent.id);
-        return `${agent.id}: ready (${agent.name} ${agent.version}, ${agent.distribution_type})`;
-      } catch (error) {
-        const detail = error instanceof Error ? error.message : String(error);
-        return `${agent.id}: setup needed (${agent.name} ${agent.version}, ${agent.distribution_type}) - ${detail}`;
-      }
-    }),
-  );
-  for (const status of statuses) {
-    console.log(status);
-  }
-  process.exit(0);
-}
-
-if (command === "agent") {
-  const agentId = positional[0];
-  const action = positional[1] || "check";
-  if (!agentId || !["check", "install"].includes(action)) {
-    fail("Usage: engineeros-connector agent AGENT_ID [check|install]");
-  }
-  try {
-    const installed =
-      action === "install"
-        ? await installRegisteredAgent(agentId)
-        : await inspectRegisteredAgent(agentId);
-    console.log(
-      `${installed.name} is ready (${installed.version}, ${installed.distribution}).`,
-    );
-  } catch (error) {
-    fail(error instanceof Error ? error.message : String(error));
-  }
-  process.exit(0);
-}
-
-if (command === "mcp") {
-  const config = await loadConfig(flags.workspace || process.cwd());
-  if (!config) fail("This workspace is not paired with EngineerOS.");
-  const runId = flags["run-id"] || positional[0];
-  if (!runId)
-    fail("Usage: engineeros-connector mcp --run-id RUN_ID [--workspace PATH]");
-  await runMcpServer({
-    config,
-    runId,
-    version: packageJson.version,
-    input: process.stdin,
-    output: process.stdout,
-  });
-  process.exit(0);
-}
-
-if (command === "status") {
-  const config = await loadConfig(flags.workspace || process.cwd());
-  console.log(
-    config
-      ? `Paired as ${config.name} (${config.connector_id}) for ${config.workspace}`
-      : "Not paired",
-  );
-  process.exit(config ? 0 : 1);
-}
-
-let config;
-let firstMessage;
-let existingConfig;
-if (command === "pair") {
-  const pairingCode = positional[0];
-  if (!pairingCode)
-    fail(
-      "Usage: engineeros-connector pair CODE --url URL [--agent AGENT_ID] [--name NAME] [--workspace PATH] [--skip-git-repo-check]",
-    );
-  const url = flags.url;
-  if (!url) fail("Pairing requires --url with the EngineerOS backend address.");
-  if (flags.agent && flags["agent-command"]) {
-    fail("Use either --agent or --agent-command, not both.");
-  }
-  let agentConfig = {};
-  try {
-    if (flags.agent) {
-      await inspectRegisteredAgent(flags.agent);
-      agentConfig = await registeredAgentConfig(flags.agent);
-    }
-  } catch (error) {
-    fail(error instanceof Error ? error.message : String(error));
-  }
-  config = {
-    server_url: socketUrl(url),
-    workspace: path.resolve(flags.workspace || process.cwd()),
-    onboard: flags.onboard === true,
-    onboarding_pending: flags.onboard === true,
-    agent_protocol: flags["agent-command"] ? "acp" : "codex",
-    agent_command: flags["agent-command"] || null,
-    agent_args: parseAgentArgs(flags["agent-args"]),
-    agent_name: flags["agent-name"] || null,
-    ...agentConfig,
-    skip_git_repo_check: flags["skip-git-repo-check"] === true,
-    name:
-      flags.name ||
-      `${os.hostname()} - ${path.basename(path.resolve(flags.workspace || process.cwd()))}`,
-  };
-  existingConfig = await loadConfig(config.workspace);
-  firstMessage = {
-    type: "pair",
-    pairing_code: pairingCode,
-    name: config.name,
-    capabilities: {},
-    ...connectorResumeCredentials(existingConfig, config.server_url),
-  };
-} else if (command === "start") {
-  config = await loadConfig(flags.workspace || process.cwd());
-  if (!config)
-    fail(
-      "This connector is not paired. Create a pairing command in EngineerOS first.",
-    );
-  firstMessage = {
-    type: "authenticate",
-    connector_id: config.connector_id,
-    token: config.token,
-  };
-} else {
-  fail(
-    "Use `engineeros-connector pair`, `start`, `status`, `agents`, `agent`, or `mcp`.",
-  );
-}
-
-let codingAgent;
-try {
-  codingAgent = await inspectCodingAgent(config, config.workspace);
-} catch (error) {
-  fail(error instanceof Error ? error.message : String(error));
-}
-console.log(
-  `Using ${codingAgent.name} through ${codingAgent.protocol} (${codingAgent.version}).`,
-);
-const capabilities = advertisedCapabilities(config, codingAgent);
-firstMessage.capabilities = capabilities;
-
-let stopped = false;
-let active = null;
-const available = [];
-const assessments = [];
-const activePrompts = new Map();
-let socket;
-let pingTimer;
-let reconnectTimer;
-let clearConnectionWatchdog;
-let reconnectDelay = 1_000;
-let connectionRejected = false;
-let lastConnectionError;
-let snapshotInFlight = false;
-
-process.on("SIGINT", async () => {
-  stopped = true;
-  clearConnectionWatchdog?.();
-  clearTimeout(reconnectTimer);
-  clearInterval(pingTimer);
-  await stopProcess(active?.child);
-  await Promise.all([...activePrompts.values()].map(cancelPrompt));
-  await disposeAcpRuntimes();
-  socket?.close();
-  process.exit(0);
-});
-
-await connect();
-
-async function connect() {
-  console.log(`Connecting ${config.name} to ${config.server_url}`);
-  connectionRejected = false;
-  lastConnectionError = undefined;
-  socket = new WebSocket(config.server_url);
-  clearConnectionWatchdog = startConnectionWatchdog(socket, config.server_url, {
-    onTimeout: (message) => {
-      lastConnectionError = message;
-      console.error(message);
-      scheduleReconnect();
-    },
-  });
-  socket.addEventListener("open", () =>
-    socket.send(JSON.stringify(firstMessage)),
-  );
-  socket.addEventListener("message", async (event) => {
-    const message = JSON.parse(String(event.data));
-    if (message.type === "paired") {
-      clearConnectionWatchdog?.();
-      const reusedConnector =
-        existingConfig?.connector_id === message.connector.id;
-      config = mergePairedConfig(
-        config,
-        existingConfig,
-        message.connector.id,
-        message.token,
-      );
-      await saveConfig(config);
-      firstMessage = {
-        type: "authenticate",
-        connector_id: config.connector_id,
-        token: config.token,
-        capabilities,
-      };
-      console.log(
-        reusedConnector
-          ? `Reconnected existing workspace connector ${config.connector_id}; assessment history is preserved.`
-          : `Paired. Connector ${config.connector_id} is online.`,
-      );
-      reconnectDelay = 1_000;
-      startPings();
-      if (config.onboarding_pending) void submitWorkspaceSnapshot();
-      return;
-    }
-    if (message.type === "authenticated") {
-      clearConnectionWatchdog?.();
-      console.log("Connected and waiting for EngineerOS runs.");
-      reconnectDelay = 1_000;
-      startPings();
-      if (config.onboarding_pending) void submitWorkspaceSnapshot();
-      return;
-    }
-    if (message.type === "workspace.refresh") {
-      void submitWorkspaceSnapshot();
-      return;
-    }
-    if (message.type === "workspace.assessment") {
-      if (
-        active?.runId !== message.assessment_id &&
-        !assessments.some(
-          (candidate) => candidate.assessment_id === message.assessment_id,
-        )
-      ) {
-        assessments.push(message);
-      }
-      pump();
-      return;
-    }
-    if (message.type === "prompt.execute") {
-      if (!activePrompts.has(message.prompt_id)) void executePrompt(message);
-      return;
-    }
-    if (message.type === "prompt.cancel") {
-      const promptState = activePrompts.get(message.prompt_id);
-      if (promptState) await cancelPrompt(promptState);
-      return;
-    }
-    if (message.type === "run.available") {
-      if (!available.includes(message.run_id)) available.push(message.run_id);
-      pump();
-      return;
-    }
-    if (message.type === "run.assignment") {
-      await execute(message);
-      return;
-    }
-    if (message.type === "run.cancelled" && active?.runId === message.run_id) {
-      console.log(`Run ${message.run_id} cancelled by EngineerOS.`);
-      active.cancelled = true;
-      await stopProcess(active.child);
-      return;
-    }
-    if (message.type === "connector.revoked") {
-      stopped = true;
-      console.error("This connector was revoked in EngineerOS.");
-      socket.close();
-      return;
-    }
-    if (message.type === "run.error") {
-      console.error(`EngineerOS: ${message.message}`);
-      if (!message.run_id) snapshotInFlight = false;
-      if (active?.runId === message.run_id && !active.child) {
-        active = null;
-        pump();
-      }
-    }
-    if (message.type === "connection.error") {
-      connectionRejected = true;
-      console.error(`EngineerOS: ${message.message}`);
-    }
-  });
-  socket.addEventListener("close", (event) => {
-    clearConnectionWatchdog?.();
-    clearInterval(pingTimer);
-    for (const promptState of activePrompts.values())
-      void cancelPrompt(promptState);
-    if (event.code === 4001 && active?.kind === "assessment") {
-      void stopProcess(active.child);
-    }
-    if (connectionRejected) {
-      stopped = true;
-      console.error(
-        "Connection rejected. Create a new pairing command in EngineerOS if this connector was revoked.",
-      );
-      return;
-    }
-    if (stopped) return;
-    scheduleReconnect();
-  });
-  socket.addEventListener("error", (event) => {
-    lastConnectionError = describeWebSocketError(event);
-    console.error(
-      `WebSocket connection to ${config.server_url} failed: ${lastConnectionError}`,
-    );
-  });
-}
-
-function scheduleReconnect() {
-  if (stopped || connectionRejected || reconnectTimer) return;
-  const detail = lastConnectionError
-    ? ` Last error: ${lastConnectionError}`
-    : "";
-  console.error(
-    `Connection unavailable.${detail} Retrying in ${Math.round(reconnectDelay / 1_000)}s.`,
-  );
-  reconnectTimer = setTimeout(() => {
-    reconnectTimer = undefined;
-    void connect();
-  }, reconnectDelay);
-  reconnectDelay = Math.min(30_000, reconnectDelay * 2);
-}
-
-async function submitWorkspaceSnapshot() {
-  if (snapshotInFlight || socket.readyState !== WebSocket.OPEN) return;
-  snapshotInFlight = true;
-  console.log("Inspecting the workspace without executing its code.");
-  try {
-    const snapshot = await workspaceSnapshot(config.workspace);
-    const response = await fetch(
-      workspaceUrl(config.server_url, config.connector_id),
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${config.token}`,
-        },
-        body: JSON.stringify(snapshot),
-      },
-    );
-    if (!response.ok) {
-      throw new Error(
-        `EngineerOS rejected the workspace (${response.status}): ${await response.text()}`,
-      );
-    }
-    const result = await response.json();
-    config = { ...config, onboarding_pending: false };
-    await saveConfig(config);
-    console.log(
-      `Sent ${snapshot.file_count} safe file(s); ${snapshot.excluded_file_count} sensitive or generated path(s) excluded.`,
-    );
-    console.log(
-      `Workspace inventory registered as ${result.workspace_kind}. Assessment queued.`,
-    );
-    snapshotInFlight = false;
-  } catch (error) {
-    snapshotInFlight = false;
-    console.error(
-      `Workspace assessment failed: ${error instanceof Error ? error.message : String(error)}`,
-    );
-  }
-}
-
-function startPings() {
-  clearInterval(pingTimer);
-  pingTimer = setInterval(() => {
-    if (socket.readyState === WebSocket.OPEN) {
-      socket.send(
-        JSON.stringify({
-          type: "ping",
-          active_run_id: active?.kind === "goal" ? active.runId : null,
-        }),
-      );
-    }
-  }, 10_000);
-}
-
-function sendPromptEvent(promptId, event) {
-  if (!event || socket.readyState !== WebSocket.OPEN) return;
-  const payload = {
-    type: "prompt.event",
-    prompt_id: promptId,
-    kind: event.kind,
-  };
-  if (event.message) payload.message = String(event.message).slice(0, 500);
-  if (event.delta) payload.delta = String(event.delta).slice(0, 50_000);
-  if (event.status) payload.status = String(event.status).slice(0, 100);
-  socket.send(JSON.stringify(payload));
-}
-
-function pump() {
-  if (active || socket.readyState !== WebSocket.OPEN) return;
-  const assessment = assessments.shift();
-  if (assessment) {
-    active = {
-      kind: "assessment",
-      runId: assessment.assessment_id,
-      child: null,
-    };
-    void executeAssessment(assessment);
-    return;
-  }
-  const runId = available.shift();
-  if (!runId) return;
-  active = { kind: "goal", runId, child: null, cancelled: false };
-  socket.send(
-    JSON.stringify({
-      type: "run.claim",
-      run_id: runId,
-      runner_name: codingAgent.name,
-      metadata: {
-        hostname: os.hostname(),
-        workspace_name: path.basename(config.workspace),
-      },
-    }),
-  );
-}
-
-async function executePrompt(assignment) {
-  const promptId = assignment.prompt_id;
-  const promptState = {
-    runId: promptId,
-    child: null,
-    controller: null,
-    cancelled: false,
-  };
-  activePrompts.set(promptId, promptState);
-  let lastEvent;
-  const reportEvent = (event) => {
-    const serialized = event ? JSON.stringify(event) : null;
-    if (
-      !serialized ||
-      serialized === lastEvent ||
-      socket.readyState !== WebSocket.OPEN ||
-      activePrompts.get(promptId) !== promptState
-    ) {
-      return;
-    }
-    lastEvent = serialized;
-    sendPromptEvent(promptId, event);
-  };
-  sendPromptEvent(promptId, {
-    kind: "status",
-    message: "Agent started this request",
-  });
-  console.log(
-    `Answering ${assignment.purpose || "project"} prompt with ${codingAgent.name}.`,
-  );
-  try {
-    const result = await executeConnectedPrompt(assignment, config, {
-      onProcess: (child) => {
-        if (activePrompts.get(promptId) === promptState)
-          promptState.child = child;
-      },
-      onController: (controller) => {
-        if (activePrompts.get(promptId) === promptState) {
-          promptState.controller = controller;
-        }
-      },
-      onEvent: (event) => reportEvent(promptStreamEvent(event)),
-    });
-    config = {
-      ...config,
-      sessions: {
-        ...(config.sessions || {}),
-        [result.sessionKey]: result.sessionId,
-      },
-    };
-    await saveConfig(config);
-    if (promptState.cancelled || socket.readyState !== WebSocket.OPEN) return;
-    socket.send(
-      JSON.stringify({
-        type: "prompt.completed",
-        prompt_id: promptId,
-        content: result.content,
-        model: result.model,
-        session_id: result.sessionId,
-      }),
-    );
-  } catch (error) {
-    if (!promptState.cancelled && socket.readyState === WebSocket.OPEN) {
-      socket.send(
-        JSON.stringify({
-          type: "prompt.failed",
-          prompt_id: promptId,
-          message: error instanceof Error ? error.message : String(error),
-        }),
-      );
-    }
-    if (!promptState.cancelled) {
-      console.error(error instanceof Error ? error.message : String(error));
-    }
-  } finally {
-    if (activePrompts.get(promptId) === promptState)
-      activePrompts.delete(promptId);
-  }
-}
-
-async function cancelPrompt(promptState) {
-  promptState.cancelled = true;
-  if (typeof promptState.controller?.cancel === "function") {
-    await promptState.controller.cancel();
-    return;
-  }
-  await stopProcess(promptState.child);
-}
-
-async function executeAssessment(assignment) {
-  const assessmentId = assignment.assessment_id;
-  console.log(`Agent is assessing the workspace (${assessmentId}).`);
-  let progress = 10;
-  let outputBuffer = "";
-  let outputLength = 0;
-  let outputTimer;
-  const reportedMilestones = new Set();
-  const reportProgress = (message, { milestone = true } = {}) => {
-    if (socket.readyState !== WebSocket.OPEN || active?.runId !== assessmentId)
-      return;
-    if (milestone && reportedMilestones.has(message)) return;
-    if (milestone) reportedMilestones.add(message);
-    socket.send(
-      JSON.stringify({
-        type: "workspace.assessment.progress",
-        assessment_id: assessmentId,
-        progress_percent: progress,
-        message: String(message).slice(0, 500),
-      }),
-    );
-  };
-  const flushOutput = () => {
-    if (outputTimer) clearTimeout(outputTimer);
-    outputTimer = undefined;
-    const output = outputBuffer;
-    outputBuffer = "";
-    if (
-      !output ||
-      socket.readyState !== WebSocket.OPEN ||
-      active?.runId !== assessmentId
-    ) {
-      return;
-    }
-    for (let offset = 0; offset < output.length; offset += 50_000) {
-      socket.send(
-        JSON.stringify({
-          type: "workspace.assessment.output",
-          assessment_id: assessmentId,
-          delta: output.slice(offset, offset + 50_000),
-        }),
-      );
-    }
-  };
-  const reportOutput = (delta) => {
-    const remaining = 120_000 - outputLength;
-    if (!delta || remaining <= 0) return;
-    const bounded = String(delta).slice(0, remaining);
-    outputBuffer += bounded;
-    outputLength += bounded.length;
-    if (outputBuffer.length >= 50_000) {
-      flushOutput();
-    } else if (!outputTimer) {
-      outputTimer = setTimeout(flushOutput, 500);
-    }
-  };
-  reportProgress("Starting read-only repository assessment");
-  const heartbeat = setInterval(() => {
-    progress = Math.min(90, progress + 5);
-    reportProgress("Assessment in progress", { milestone: false });
-  }, 15_000);
-  try {
-    if (assignment.assessment_mode === "incremental") {
-      progress = 15;
-      reportProgress("Calculating changed files and affected evidence");
-    }
-    const result = await executeWorkspaceAssessment(assignment, config, {
-      onProcess: (child) => {
-        if (active?.runId === assessmentId) active.child = child;
-      },
-      onEvent: (event) => {
-        reportOutput(assessmentStreamDelta(event));
-        const message = assessmentProgressMessage(event);
-        if (message) reportProgress(message);
-      },
-    });
-    flushOutput();
-    const response = await fetch(
-      assessmentResultUrl(config.server_url, config.connector_id, assessmentId),
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${config.token}`,
-        },
-        body: JSON.stringify(result),
-      },
-    );
-    if (!response.ok) {
-      throw new Error(
-        `EngineerOS rejected the assessment (${response.status}): ${await response.text()}`,
-      );
-    }
-    console.log("Workspace assessment is current in EngineerOS.");
-  } catch (error) {
-    flushOutput();
-    if (socket.readyState === WebSocket.OPEN) {
-      socket.send(
-        JSON.stringify({
-          type: "workspace.assessment.failed",
-          assessment_id: assessmentId,
-          message: error instanceof Error ? error.message : String(error),
-        }),
-      );
-    }
-    console.error(error instanceof Error ? error.message : String(error));
-  } finally {
-    if (outputTimer) clearTimeout(outputTimer);
-    clearInterval(heartbeat);
-    active = null;
-    pump();
-  }
-}
-
-async function execute(assignment) {
-  const runId = assignment.run_id;
-  console.log(`Running Goal ${runId} with ${codingAgent.name}.`);
-  let progress = 10;
-  const heartbeat = setInterval(() => {
-    if (socket.readyState === WebSocket.OPEN && active?.runId === runId) {
-      progress = Math.min(90, progress + 5);
-      socket.send(
-        JSON.stringify({
-          type: "run.progress",
-          run_id: runId,
-          progress_percent: progress,
-          message: "Agent is working",
-        }),
-      );
-    }
-  }, 15_000);
-  try {
-    const result = await executeAssignment(assignment, config, {
-      onProcess: (child) => {
-        if (active?.runId === runId) active.child = child;
-      },
-      onEvent: (event) => {
-        const message =
-          event.message || event.item?.text || event.type || "Agent is working";
-        if (socket.readyState === WebSocket.OPEN) {
-          socket.send(
-            JSON.stringify({
-              type: "run.progress",
-              run_id: runId,
-              progress_percent: progress,
-              message: String(message).slice(0, 500),
-            }),
-          );
-        }
-      },
-    });
-    if (active?.cancelled) return;
-    const response = await fetch(
-      resultUrl(config.server_url, config.connector_id, runId),
-      {
-        method: "POST",
-        headers: {
-          "Content-Type": "application/json",
-          Authorization: `Bearer ${config.token}`,
-        },
-        body: JSON.stringify(result),
-      },
-    );
-    if (!response.ok)
-      throw new Error(
-        `EngineerOS rejected the result (${response.status}): ${await response.text()}`,
-      );
-    const integration = await applyAcceptedChange(
-      config.workspace,
-      assignment.base_revision,
-      result.head_revision,
-    );
-    if (integration.applied) {
-      console.log(
-        `Run accepted and applied to the connected repository at ${integration.revision}.`,
-      );
-    } else {
-      console.warn(
-        `Run accepted but not applied locally. ${integration.reason}`,
-      );
-      console.warn(
-        `The verified run workspace remains at ${result.run_workspace}.`,
-      );
-    }
-  } catch (error) {
-    if (!active?.cancelled && socket.readyState === WebSocket.OPEN) {
-      socket.send(
-        JSON.stringify({
-          type: "run.failed",
-          run_id: runId,
-          message: error instanceof Error ? error.message : String(error),
-        }),
-      );
-    }
-    if (!active?.cancelled)
-      console.error(error instanceof Error ? error.message : String(error));
-  } finally {
-    clearInterval(heartbeat);
-    active = null;
-    pump();
-  }
-}
-
-function parseAgentArgs(value) {
-  if (!value) return [];
-  try {
-    const parsed = JSON.parse(value);
-    if (
-      !Array.isArray(parsed) ||
-      parsed.some((item) => typeof item !== "string")
-    ) {
-      throw new Error();
-    }
-    return parsed;
-  } catch {
-    fail(
-      '--agent-args must be a JSON array, for example: --agent-args "[\\"acp\\"]"',
-    );
-  }
-}
-
-function fail(message) {
-  console.error(message);
-  process.exit(1);
-}
+#!/usr/bin/env node
+import os from "node:os";
+import path from "node:path";
+import {
+  assessmentResultUrl,
+  connectorResumeCredentials,
+  loadConfig,
+  mergePairedConfig,
+  resultUrl,
+  saveConfig,
+  socketUrl,
+  workspaceUrl,
+} from "../src/config.mjs";
+import {
+  assessmentProgressMessage,
+  assessmentStreamDelta,
+  applyAcceptedChange,
+  executeAssignment,
+  executeConnectedPrompt,
+  executeWorkspaceAssessment,
+  inspectCodingAgent,
+  promptStreamEvent,
+  stopProcess,
+  workspaceSnapshot,
+} from "../src/runner.mjs";
+import { disposeAcpRuntimes } from "../src/acp-client.mjs";
+import {
+  installRegisteredAgent,
+  inspectRegisteredAgent,
+  registeredAgentConfig,
+  registeredAgents,
+} from "../src/agent-registry.mjs";
+import {
+  describeWebSocketError,
+  startConnectionWatchdog,
+} from "../src/connection.mjs";
+import { advertisedCapabilities } from "../src/capabilities.mjs";
+import { parseConnectorArgs } from "../src/cli-args.mjs";
+import { runMcpServer } from "../src/mcp-server.mjs";
+import packageJson from "../package.json" with { type: "json" };
+
+const { command, positional, flags } = parseConnectorArgs(
+  process.argv.slice(2),
+);
+
+if (command === "agents") {
+  let agents;
+  try {
+    agents = await registeredAgents();
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  const statuses = await Promise.all(
+    agents.map(async (agent) => {
+      try {
+        await inspectRegisteredAgent(agent.id);
+        return `${agent.id}: ready (${agent.name} ${agent.version}, ${agent.distribution_type})`;
+      } catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        return `${agent.id}: setup needed (${agent.name} ${agent.version}, ${agent.distribution_type}) - ${detail}`;
+      }
+    }),
+  );
+  for (const status of statuses) {
+    console.log(status);
+  }
+  process.exit(0);
+}
+
+if (command === "agent") {
+  const agentId = positional[0];
+  const action = positional[1] || "check";
+  if (!agentId || !["check", "install"].includes(action)) {
+    fail("Usage: engineeros-connector agent AGENT_ID [check|install]");
+  }
+  try {
+    const installed =
+      action === "install"
+        ? await installRegisteredAgent(agentId)
+        : await inspectRegisteredAgent(agentId);
+    console.log(
+      `${installed.name} is ready (${installed.version}, ${installed.distribution}).`,
+    );
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  process.exit(0);
+}
+
+if (command === "mcp") {
+  const config = await loadConfig(flags.workspace || process.cwd());
+  if (!config) fail("This workspace is not paired with EngineerOS.");
+  const runId = flags["run-id"] || positional[0];
+  if (!runId)
+    fail("Usage: engineeros-connector mcp --run-id RUN_ID [--workspace PATH]");
+  await runMcpServer({
+    config,
+    runId,
+    version: packageJson.version,
+    input: process.stdin,
+    output: process.stdout,
+  });
+  process.exit(0);
+}
+
+if (command === "status") {
+  const config = await loadConfig(flags.workspace || process.cwd());
+  console.log(
+    config
+      ? `Paired as ${config.name} (${config.connector_id}) for ${config.workspace}`
+      : "Not paired",
+  );
+  process.exit(config ? 0 : 1);
+}
+
+let config;
+let firstMessage;
+let existingConfig;
+if (command === "pair") {
+  const pairingCode = positional[0];
+  if (!pairingCode)
+    fail(
+      "Usage: engineeros-connector pair CODE --url URL [--agent AGENT_ID] [--name NAME] [--workspace PATH] [--skip-git-repo-check]",
+    );
+  const url = flags.url;
+  if (!url) fail("Pairing requires --url with the EngineerOS backend address.");
+  if (flags.agent && flags["agent-command"]) {
+    fail("Use either --agent or --agent-command, not both.");
+  }
+  let agentConfig = {};
+  try {
+    if (flags.agent) {
+      await inspectRegisteredAgent(flags.agent);
+      agentConfig = await registeredAgentConfig(flags.agent);
+    }
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+  }
+  config = {
+    server_url: socketUrl(url),
+    workspace: path.resolve(flags.workspace || process.cwd()),
+    onboard: flags.onboard === true,
+    onboarding_pending: flags.onboard === true,
+    agent_protocol: flags["agent-command"] ? "acp" : "codex",
+    agent_command: flags["agent-command"] || null,
+    agent_args: parseAgentArgs(flags["agent-args"]),
+    agent_name: flags["agent-name"] || null,
+    ...agentConfig,
+    skip_git_repo_check: flags["skip-git-repo-check"] === true,
+    name:
+      flags.name ||
+      `${os.hostname()} - ${path.basename(path.resolve(flags.workspace || process.cwd()))}`,
+  };
+  existingConfig = await loadConfig(config.workspace);
+  firstMessage = {
+    type: "pair",
+    pairing_code: pairingCode,
+    name: config.name,
+    capabilities: {},
+    ...connectorResumeCredentials(existingConfig, config.server_url),
+  };
+} else if (command === "start") {
+  config = await loadConfig(flags.workspace || process.cwd());
+  if (!config)
+    fail(
+      "This connector is not paired. Create a pairing command in EngineerOS first.",
+    );
+  firstMessage = {
+    type: "authenticate",
+    connector_id: config.connector_id,
+    token: config.token,
+  };
+} else {
+  fail(
+    "Use `engineeros-connector pair`, `start`, `status`, `agents`, `agent`, or `mcp`.",
+  );
+}
+
+let codingAgent;
+try {
+  codingAgent = await inspectCodingAgent(config, config.workspace);
+} catch (error) {
+  fail(error instanceof Error ? error.message : String(error));
+}
+console.log(
+  `Using ${codingAgent.name} through ${codingAgent.protocol} (${codingAgent.version}).`,
+);
+const capabilities = advertisedCapabilities(config, codingAgent);
+firstMessage.capabilities = capabilities;
+
+let stopped = false;
+let active = null;
+const available = [];
+const assessments = [];
+const activePrompts = new Map();
+let socket;
+let pingTimer;
+let reconnectTimer;
+let clearConnectionWatchdog;
+let reconnectDelay = 1_000;
+let connectionRejected = false;
+let lastConnectionError;
+let snapshotInFlight = false;
+
+process.on("SIGINT", async () => {
+  stopped = true;
+  clearConnectionWatchdog?.();
+  clearTimeout(reconnectTimer);
+  clearInterval(pingTimer);
+  await stopProcess(active?.child);
+  await Promise.all([...activePrompts.values()].map(cancelPrompt));
+  await disposeAcpRuntimes();
+  socket?.close();
+  process.exit(0);
+});
+
+await connect();
+
+async function connect() {
+  console.log(`Connecting ${config.name} to ${config.server_url}`);
+  connectionRejected = false;
+  lastConnectionError = undefined;
+  socket = new WebSocket(config.server_url);
+  clearConnectionWatchdog = startConnectionWatchdog(socket, config.server_url, {
+    onTimeout: (message) => {
+      lastConnectionError = message;
+      console.error(message);
+      scheduleReconnect();
+    },
+  });
+  socket.addEventListener("open", () =>
+    socket.send(JSON.stringify(firstMessage)),
+  );
+  socket.addEventListener("message", async (event) => {
+    const message = JSON.parse(String(event.data));
+    if (message.type === "paired") {
+      clearConnectionWatchdog?.();
+      const reusedConnector =
+        existingConfig?.connector_id === message.connector.id;
+      config = mergePairedConfig(
+        config,
+        existingConfig,
+        message.connector.id,
+        message.token,
+      );
+      await saveConfig(config);
+      firstMessage = {
+        type: "authenticate",
+        connector_id: config.connector_id,
+        token: config.token,
+        capabilities,
+      };
+      console.log(
+        reusedConnector
+          ? `Reconnected existing workspace connector ${config.connector_id}; assessment history is preserved.`
+          : `Paired. Connector ${config.connector_id} is online.`,
+      );
+      reconnectDelay = 1_000;
+      startPings();
+      if (config.onboarding_pending) void submitWorkspaceSnapshot();
+      return;
+    }
+    if (message.type === "authenticated") {
+      clearConnectionWatchdog?.();
+      console.log("Connected and waiting for EngineerOS runs.");
+      reconnectDelay = 1_000;
+      startPings();
+      if (config.onboarding_pending) void submitWorkspaceSnapshot();
+      return;
+    }
+    if (message.type === "workspace.refresh") {
+      void submitWorkspaceSnapshot();
+      return;
+    }
+    if (message.type === "workspace.assessment") {
+      if (
+        active?.runId !== message.assessment_id &&
+        !assessments.some(
+          (candidate) => candidate.assessment_id === message.assessment_id,
+        )
+      ) {
+        assessments.push(message);
+      }
+      pump();
+      return;
+    }
+    if (message.type === "prompt.execute") {
+      if (!activePrompts.has(message.prompt_id)) void executePrompt(message);
+      return;
+    }
+    if (message.type === "prompt.cancel") {
+      const promptState = activePrompts.get(message.prompt_id);
+      if (promptState) await cancelPrompt(promptState);
+      return;
+    }
+    if (message.type === "run.available") {
+      if (!available.includes(message.run_id)) available.push(message.run_id);
+      pump();
+      return;
+    }
+    if (message.type === "run.assignment") {
+      await execute(message);
+      return;
+    }
+    if (message.type === "run.cancelled" && active?.runId === message.run_id) {
+      console.log(`Run ${message.run_id} cancelled by EngineerOS.`);
+      active.cancelled = true;
+      await stopProcess(active.child);
+      return;
+    }
+    if (message.type === "connector.revoked") {
+      stopped = true;
+      console.error("This connector was revoked in EngineerOS.");
+      socket.close();
+      return;
+    }
+    if (message.type === "run.error") {
+      console.error(`EngineerOS: ${message.message}`);
+      if (!message.run_id) snapshotInFlight = false;
+      if (active?.runId === message.run_id && !active.child) {
+        active = null;
+        pump();
+      }
+    }
+    if (message.type === "connection.error") {
+      connectionRejected = true;
+      console.error(`EngineerOS: ${message.message}`);
+    }
+  });
+  socket.addEventListener("close", (event) => {
+    clearConnectionWatchdog?.();
+    clearInterval(pingTimer);
+    for (const promptState of activePrompts.values())
+      void cancelPrompt(promptState);
+    if (event.code === 4001 && active?.kind === "assessment") {
+      void stopProcess(active.child);
+    }
+    if (connectionRejected) {
+      stopped = true;
+      console.error(
+        "Connection rejected. Create a new pairing command in EngineerOS if this connector was revoked.",
+      );
+      return;
+    }
+    if (stopped) return;
+    scheduleReconnect();
+  });
+  socket.addEventListener("error", (event) => {
+    lastConnectionError = describeWebSocketError(event);
+    console.error(
+      `WebSocket connection to ${config.server_url} failed: ${lastConnectionError}`,
+    );
+  });
+}
+
+function scheduleReconnect() {
+  if (stopped || connectionRejected || reconnectTimer) return;
+  const detail = lastConnectionError
+    ? ` Last error: ${lastConnectionError}`
+    : "";
+  console.error(
+    `Connection unavailable.${detail} Retrying in ${Math.round(reconnectDelay / 1_000)}s.`,
+  );
+  reconnectTimer = setTimeout(() => {
+    reconnectTimer = undefined;
+    void connect();
+  }, reconnectDelay);
+  reconnectDelay = Math.min(30_000, reconnectDelay * 2);
+}
+
+async function submitWorkspaceSnapshot() {
+  if (snapshotInFlight || socket.readyState !== WebSocket.OPEN) return;
+  snapshotInFlight = true;
+  console.log("Inspecting the workspace without executing its code.");
+  try {
+    const snapshot = await workspaceSnapshot(config.workspace);
+    const response = await fetch(
+      workspaceUrl(config.server_url, config.connector_id),
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${config.token}`,
+        },
+        body: JSON.stringify(snapshot),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(
+        `EngineerOS rejected the workspace (${response.status}): ${await response.text()}`,
+      );
+    }
+    const result = await response.json();
+    config = { ...config, onboarding_pending: false };
+    await saveConfig(config);
+    console.log(
+      `Inventoried ${snapshot.total_file_count.toLocaleString()} safe file(s).`,
+    );
+    console.log(
+      `Uploaded ${snapshot.evidence_file_count.toLocaleString()} prioritized evidence file(s).`,
+    );
+    console.log(
+      `Excluded ${snapshot.excluded_file_count.toLocaleString()} sensitive or generated file(s).`,
+    );
+    if (snapshot.omitted_evidence_file_count > 0) {
+      console.log(
+        `${snapshot.omitted_evidence_file_count.toLocaleString()} additional file(s) remain available to the connected Agent locally.`,
+      );
+    }
+    console.log(
+      `Workspace inventory registered as ${result.workspace_kind}. Assessment queued.`,
+    );
+    snapshotInFlight = false;
+  } catch (error) {
+    snapshotInFlight = false;
+    console.error(
+      `Workspace assessment failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+function startPings() {
+  clearInterval(pingTimer);
+  pingTimer = setInterval(() => {
+    if (socket.readyState === WebSocket.OPEN) {
+      socket.send(
+        JSON.stringify({
+          type: "ping",
+          active_run_id: active?.kind === "goal" ? active.runId : null,
+        }),
+      );
+    }
+  }, 10_000);
+}
+
+function sendPromptEvent(promptId, event) {
+  if (!event || socket.readyState !== WebSocket.OPEN) return;
+  const payload = {
+    type: "prompt.event",
+    prompt_id: promptId,
+    kind: event.kind,
+  };
+  if (event.message) payload.message = String(event.message).slice(0, 500);
+  if (event.delta) payload.delta = String(event.delta).slice(0, 50_000);
+  if (event.status) payload.status = String(event.status).slice(0, 100);
+  socket.send(JSON.stringify(payload));
+}
+
+function pump() {
+  if (active || socket.readyState !== WebSocket.OPEN) return;
+  const assessment = assessments.shift();
+  if (assessment) {
+    active = {
+      kind: "assessment",
+      runId: assessment.assessment_id,
+      child: null,
+    };
+    void executeAssessment(assessment);
+    return;
+  }
+  const runId = available.shift();
+  if (!runId) return;
+  active = { kind: "goal", runId, child: null, cancelled: false };
+  socket.send(
+    JSON.stringify({
+      type: "run.claim",
+      run_id: runId,
+      runner_name: codingAgent.name,
+      metadata: {
+        hostname: os.hostname(),
+        workspace_name: path.basename(config.workspace),
+      },
+    }),
+  );
+}
+
+async function executePrompt(assignment) {
+  const promptId = assignment.prompt_id;
+  const promptState = {
+    runId: promptId,
+    child: null,
+    controller: null,
+    cancelled: false,
+  };
+  activePrompts.set(promptId, promptState);
+  let lastEvent;
+  const reportEvent = (event) => {
+    const serialized = event ? JSON.stringify(event) : null;
+    if (
+      !serialized ||
+      serialized === lastEvent ||
+      socket.readyState !== WebSocket.OPEN ||
+      activePrompts.get(promptId) !== promptState
+    ) {
+      return;
+    }
+    lastEvent = serialized;
+    sendPromptEvent(promptId, event);
+  };
+  sendPromptEvent(promptId, {
+    kind: "status",
+    message: "Agent started this request",
+  });
+  console.log(
+    `Answering ${assignment.purpose || "project"} prompt with ${codingAgent.name}.`,
+  );
+  try {
+    const result = await executeConnectedPrompt(assignment, config, {
+      onProcess: (child) => {
+        if (activePrompts.get(promptId) === promptState)
+          promptState.child = child;
+      },
+      onController: (controller) => {
+        if (activePrompts.get(promptId) === promptState) {
+          promptState.controller = controller;
+        }
+      },
+      onEvent: (event) => reportEvent(promptStreamEvent(event)),
+    });
+    config = {
+      ...config,
+      sessions: {
+        ...(config.sessions || {}),
+        [result.sessionKey]: result.sessionId,
+      },
+    };
+    await saveConfig(config);
+    if (promptState.cancelled || socket.readyState !== WebSocket.OPEN) return;
+    socket.send(
+      JSON.stringify({
+        type: "prompt.completed",
+        prompt_id: promptId,
+        content: result.content,
+        model: result.model,
+        session_id: result.sessionId,
+      }),
+    );
+  } catch (error) {
+    if (!promptState.cancelled && socket.readyState === WebSocket.OPEN) {
+      socket.send(
+        JSON.stringify({
+          type: "prompt.failed",
+          prompt_id: promptId,
+          message: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    }
+    if (!promptState.cancelled) {
+      console.error(error instanceof Error ? error.message : String(error));
+    }
+  } finally {
+    if (activePrompts.get(promptId) === promptState)
+      activePrompts.delete(promptId);
+  }
+}
+
+async function cancelPrompt(promptState) {
+  promptState.cancelled = true;
+  if (typeof promptState.controller?.cancel === "function") {
+    await promptState.controller.cancel();
+    return;
+  }
+  await stopProcess(promptState.child);
+}
+
+async function executeAssessment(assignment) {
+  const assessmentId = assignment.assessment_id;
+  console.log(`Agent is assessing the workspace (${assessmentId}).`);
+  let progress = 10;
+  let outputBuffer = "";
+  let outputLength = 0;
+  let outputTimer;
+  const reportedMilestones = new Set();
+  const reportProgress = (message, { milestone = true } = {}) => {
+    if (socket.readyState !== WebSocket.OPEN || active?.runId !== assessmentId)
+      return;
+    if (milestone && reportedMilestones.has(message)) return;
+    if (milestone) reportedMilestones.add(message);
+    socket.send(
+      JSON.stringify({
+        type: "workspace.assessment.progress",
+        assessment_id: assessmentId,
+        progress_percent: progress,
+        message: String(message).slice(0, 500),
+      }),
+    );
+  };
+  const flushOutput = () => {
+    if (outputTimer) clearTimeout(outputTimer);
+    outputTimer = undefined;
+    const output = outputBuffer;
+    outputBuffer = "";
+    if (
+      !output ||
+      socket.readyState !== WebSocket.OPEN ||
+      active?.runId !== assessmentId
+    ) {
+      return;
+    }
+    for (let offset = 0; offset < output.length; offset += 50_000) {
+      socket.send(
+        JSON.stringify({
+          type: "workspace.assessment.output",
+          assessment_id: assessmentId,
+          delta: output.slice(offset, offset + 50_000),
+        }),
+      );
+    }
+  };
+  const reportOutput = (delta) => {
+    const remaining = 120_000 - outputLength;
+    if (!delta || remaining <= 0) return;
+    const bounded = String(delta).slice(0, remaining);
+    outputBuffer += bounded;
+    outputLength += bounded.length;
+    if (outputBuffer.length >= 50_000) {
+      flushOutput();
+    } else if (!outputTimer) {
+      outputTimer = setTimeout(flushOutput, 500);
+    }
+  };
+  reportProgress("Starting read-only repository assessment");
+  const heartbeat = setInterval(() => {
+    progress = Math.min(90, progress + 5);
+    reportProgress("Assessment in progress", { milestone: false });
+  }, 15_000);
+  try {
+    if (assignment.assessment_mode === "incremental") {
+      progress = 15;
+      reportProgress("Calculating changed files and affected evidence");
+    }
+    const result = await executeWorkspaceAssessment(assignment, config, {
+      onProcess: (child) => {
+        if (active?.runId === assessmentId) active.child = child;
+      },
+      onEvent: (event) => {
+        reportOutput(assessmentStreamDelta(event));
+        const message = assessmentProgressMessage(event);
+        if (message) reportProgress(message);
+      },
+    });
+    flushOutput();
+    const response = await fetch(
+      assessmentResultUrl(config.server_url, config.connector_id, assessmentId),
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${config.token}`,
+        },
+        body: JSON.stringify(result),
+      },
+    );
+    if (!response.ok) {
+      throw new Error(
+        `EngineerOS rejected the assessment (${response.status}): ${await response.text()}`,
+      );
+    }
+    console.log("Workspace assessment is current in EngineerOS.");
+  } catch (error) {
+    flushOutput();
+    if (socket.readyState === WebSocket.OPEN) {
+      socket.send(
+        JSON.stringify({
+          type: "workspace.assessment.failed",
+          assessment_id: assessmentId,
+          message: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    }
+    console.error(error instanceof Error ? error.message : String(error));
+  } finally {
+    if (outputTimer) clearTimeout(outputTimer);
+    clearInterval(heartbeat);
+    active = null;
+    pump();
+  }
+}
+
+async function execute(assignment) {
+  const runId = assignment.run_id;
+  console.log(`Running Goal ${runId} with ${codingAgent.name}.`);
+  let progress = 10;
+  const heartbeat = setInterval(() => {
+    if (socket.readyState === WebSocket.OPEN && active?.runId === runId) {
+      progress = Math.min(90, progress + 5);
+      socket.send(
+        JSON.stringify({
+          type: "run.progress",
+          run_id: runId,
+          progress_percent: progress,
+          message: "Agent is working",
+        }),
+      );
+    }
+  }, 15_000);
+  try {
+    const result = await executeAssignment(assignment, config, {
+      onProcess: (child) => {
+        if (active?.runId === runId) active.child = child;
+      },
+      onEvent: (event) => {
+        const message =
+          event.message || event.item?.text || event.type || "Agent is working";
+        if (socket.readyState === WebSocket.OPEN) {
+          socket.send(
+            JSON.stringify({
+              type: "run.progress",
+              run_id: runId,
+              progress_percent: progress,
+              message: String(message).slice(0, 500),
+            }),
+          );
+        }
+      },
+    });
+    if (active?.cancelled) return;
+    const response = await fetch(
+      resultUrl(config.server_url, config.connector_id, runId),
+      {
+        method: "POST",
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${config.token}`,
+        },
+        body: JSON.stringify(result),
+      },
+    );
+    if (!response.ok)
+      throw new Error(
+        `EngineerOS rejected the result (${response.status}): ${await response.text()}`,
+      );
+    const integration = await applyAcceptedChange(
+      config.workspace,
+      assignment.base_revision,
+      result.head_revision,
+    );
+    if (integration.applied) {
+      console.log(
+        `Run accepted and applied to the connected repository at ${integration.revision}.`,
+      );
+    } else {
+      console.warn(
+        `Run accepted but not applied locally. ${integration.reason}`,
+      );
+      console.warn(
+        `The verified run workspace remains at ${result.run_workspace}.`,
+      );
+    }
+  } catch (error) {
+    if (!active?.cancelled && socket.readyState === WebSocket.OPEN) {
+      socket.send(
+        JSON.stringify({
+          type: "run.failed",
+          run_id: runId,
+          message: error instanceof Error ? error.message : String(error),
+        }),
+      );
+    }
+    if (!active?.cancelled)
+      console.error(error instanceof Error ? error.message : String(error));
+  } finally {
+    clearInterval(heartbeat);
+    active = null;
+    pump();
+  }
+}
+
+function parseAgentArgs(value) {
+  if (!value) return [];
+  try {
+    const parsed = JSON.parse(value);
+    if (
+      !Array.isArray(parsed) ||
+      parsed.some((item) => typeof item !== "string")
+    ) {
+      throw new Error();
+    }
+    return parsed;
+  } catch {
+    fail(
+      '--agent-args must be a JSON array, for example: --agent-args "[\\"acp\\"]"',
+    );
+  }
+}
+
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}