@engineeros/connector 0.8.8 → 0.9.0

package/src/agent-registry.mjs

@@ -0,0 +1,643 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import {
+  access,
+  chmod,
+  mkdir,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+
+export const ACP_REGISTRY_URL =
+  "https://cdn.agentclientprotocol.com/registry/v1/latest/registry.json";
+
+const CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
+const PRIORITY_AGENT_IDS = ["codex-acp", "claude-acp", "gemini"];
+const AGENT_ALIASES = {
+  codex: "codex-acp",
+  claude: "claude-acp",
+};
+const SAFE_MODES = {
+  "codex-acp": { "read-only": "read-only", "workspace-write": "agent" },
+  "claude-acp": {
+    "read-only": "plan",
+    "workspace-write": "acceptEdits",
+  },
+};
+
+let defaultRegistryPromise;
+const commandChecks = new Map();
+
+export async function registeredAgents(options = {}) {
+  const registry = await loadRegistry(options);
+  return registry.agents
+    .map((agent) => ({
+      ...agent,
+      modes: { ...(SAFE_MODES[agent.id] || {}) },
+      distribution_type: distributionType(agent),
+    }))
+    .sort(compareAgents);
+}
+
+export async function registeredAgent(agentId, options = {}) {
+  const normalized = normalizeLookup(agentId);
+  const resolvedId = AGENT_ALIASES[normalized] || normalized;
+  const agents = await registeredAgents(options);
+  return (
+    agents.find(
+      (agent) =>
+        agent.id.toLowerCase() === resolvedId ||
+        agent.name.toLowerCase() === normalized,
+    ) ?? null
+  );
+}
+
+export async function registeredAgentConfig(agentId, options = {}) {
+  const agent = await requireAgent(agentId, options);
+  const launch = resolveLaunch(agent, options);
+  return {
+    agent_id: agent.id,
+    agent_protocol: "acp",
+    agent_command: launch.command,
+    agent_args: launch.args,
+    agent_env: launch.env,
+    agent_name: agent.name,
+    agent_version: agent.version,
+    agent_distribution: launch.type,
+    agent_modes: { ...agent.modes },
+  };
+}
+
+export async function agentInstallCommand(agentId, options = {}) {
+  const agent = await requireAgent(agentId, options);
+  const launch = resolveLaunch(agent, options);
+  if (launch.type === "npx") {
+    return [
+      platformCommand("npm", options.platform),
+      ["exec", "--yes", `--package=${launch.package}`, "--", "node", "-e", ""],
+    ];
+  }
+  if (launch.type === "uvx") {
+    return [
+      platformCommand("uv", options.platform),
+      ["tool", "install", launch.package],
+    ];
+  }
+  return null;
+}
+
+export async function agentCheckCommand(agentId, options = {}) {
+  const agent = await requireAgent(agentId, options);
+  const launch = resolveLaunch(agent, options);
+  if (launch.type === "binary") return null;
+  return [launch.command, ["--version"]];
+}
+
+export async function inspectRegisteredAgent(agentId, options = {}) {
+  const agent = await requireAgent(agentId, options);
+  const launch = resolveLaunch(agent, options);
+  const ready =
+    launch.type === "binary"
+      ? await fileExists(launch.command)
+      : await commandAvailable(launch.command, options);
+  if (!ready) {
+    throw new Error(
+      `${agent.name} is not ready. Run ` +
+        `\`engineeros-connector agent ${agent.id} install\`, then retry.`,
+    );
+  }
+  return {
+    protocol: "acp",
+    id: agent.id,
+    name: agent.name,
+    version: agent.version,
+    distribution: launch.type,
+  };
+}
+
+export async function installRegisteredAgent(agentId, options = {}) {
+  const agent = await requireAgent(agentId, options);
+  const launch = resolveLaunch(agent, options);
+  if (launch.type === "binary") {
+    await installBinary(agent, launch, options);
+  } else {
+    const install = await agentInstallCommand(agent.id, options);
+    const result = await (options.runCommand || runCommand)(
+      install[0],
+      install[1],
+      {
+        ...options,
+        inherit: true,
+      },
+    );
+    if (result.code !== 0) {
+      throw new Error(
+        `Could not prepare ${agent.name}. ${String(result.output || "").trim()}`.trim(),
+      );
+    }
+  }
+  return inspectRegisteredAgent(agent.id, options);
+}
+
+export function parseAgentRegistry(value) {
+  if (!value || typeof value !== "object" || !Array.isArray(value.agents)) {
+    throw new Error(
+      "The ACP registry response does not contain an agent list.",
+    );
+  }
+  const agents = value.agents.map((agent, index) =>
+    validateAgent(agent, index),
+  );
+  return {
+    version: String(value.version || "unknown"),
+    agents,
+  };
+}
+
+export function currentPlatformKey(
+  platform = process.platform,
+  arch = process.arch,
+) {
+  const platformName =
+    platform === "win32"
+      ? "windows"
+      : platform === "darwin" || platform === "linux"
+        ? platform
+        : null;
+  const architecture =
+    arch === "arm64" ? "aarch64" : arch === "x64" ? "x86_64" : null;
+  if (!platformName || !architecture) {
+    throw new Error(
+      `ACP registry binaries do not support ${platform}/${arch}. Use --agent-command for a local ACP agent.`,
+    );
+  }
+  return `${platformName}-${architecture}`;
+}
+
+async function requireAgent(agentId, options) {
+  const agent = await registeredAgent(agentId, options);
+  if (agent) return agent;
+  throw new Error(
+    `Unknown coding agent '${agentId}'. Run \`engineeros-connector agents\` to see the current official ACP catalog.`,
+  );
+}
+
+async function loadRegistry(options) {
+  if (options.registry) return parseAgentRegistry(options.registry);
+  if (Object.keys(options).length === 0 && defaultRegistryPromise) {
+    return defaultRegistryPromise;
+  }
+  const loading = fetchRegistry(options);
+  if (Object.keys(options).length === 0) defaultRegistryPromise = loading;
+  try {
+    return await loading;
+  } catch (error) {
+    if (Object.keys(options).length === 0) defaultRegistryPromise = undefined;
+    throw error;
+  }
+}
+
+async function fetchRegistry(options) {
+  const cachePath =
+    options.cachePath ||
+    path.join(os.homedir(), ".engineeros", "cache", "acp-registry.json");
+  const cached = await readRegistryCache(cachePath);
+  if (cached && Date.now() - cached.fetched_at < CACHE_TTL_MS) {
+    return cached.registry;
+  }
+  try {
+    const fetcher = options.fetch || globalThis.fetch;
+    const response = await fetcher(options.registryUrl || ACP_REGISTRY_URL, {
+      signal: options.signal || AbortSignal.timeout(10_000),
+    });
+    if (!response.ok) {
+      throw new Error(`${response.status} ${response.statusText}`.trim());
+    }
+    const registry = parseAgentRegistry(await response.json());
+    await writeRegistryCache(cachePath, registry);
+    return registry;
+  } catch (error) {
+    if (cached) return cached.registry;
+    throw new Error(
+      `The official ACP agent catalog is unavailable. Check the network connection and retry. ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+async function readRegistryCache(cachePath) {
+  try {
+    const parsed = JSON.parse(await readFile(cachePath, "utf8"));
+    return {
+      fetched_at: Number(parsed.fetched_at || 0),
+      registry: parseAgentRegistry(parsed.registry),
+    };
+  } catch {
+    return null;
+  }
+}
+
+async function writeRegistryCache(cachePath, registry) {
+  try {
+    await mkdir(path.dirname(cachePath), { recursive: true });
+    await writeFile(
+      cachePath,
+      `${JSON.stringify({ fetched_at: Date.now(), registry }, null, 2)}\n`,
+      "utf8",
+    );
+  } catch {
+    // The live registry remains usable when a locked-down machine disallows caching.
+  }
+}
+
+function validateAgent(agent, index) {
+  if (!agent || typeof agent !== "object") {
+    throw new Error(`ACP registry agent ${index + 1} is invalid.`);
+  }
+  const id = String(agent.id || "").trim();
+  const name = String(agent.name || "").trim();
+  const version = String(agent.version || "").trim();
+  if (
+    !/^[a-z0-9][a-z0-9-]*$/.test(id) ||
+    !name ||
+    !version ||
+    /[\0\r\n]/.test(version)
+  ) {
+    throw new Error(
+      `ACP registry agent ${index + 1} has invalid identity fields.`,
+    );
+  }
+  if (!agent.distribution || typeof agent.distribution !== "object") {
+    throw new Error(`ACP registry agent '${id}' has no distribution.`);
+  }
+  return {
+    id,
+    name,
+    version,
+    description: String(agent.description || "").trim(),
+    repository: agent.repository ? String(agent.repository) : undefined,
+    website: agent.website ? String(agent.website) : undefined,
+    icon: agent.icon ? String(agent.icon) : undefined,
+    distribution: agent.distribution,
+  };
+}
+
+function distributionType(agent) {
+  if (agent.distribution.npx) return "npx";
+  if (agent.distribution.uvx) return "uvx";
+  if (agent.distribution.binary) return "binary";
+  return "unsupported";
+}
+
+function resolveLaunch(agent, options) {
+  if (agent.distribution.npx) {
+    const distribution = validatePackageDistribution(
+      agent,
+      "npx",
+      agent.distribution.npx,
+    );
+    return {
+      type: "npx",
+      package: distribution.package,
+      command: platformCommand("npx", options.platform),
+      args: ["--yes", distribution.package, ...(distribution.args || [])],
+      env: { ...(distribution.env || {}) },
+    };
+  }
+  if (agent.distribution.uvx) {
+    const distribution = validatePackageDistribution(
+      agent,
+      "uvx",
+      agent.distribution.uvx,
+    );
+    return {
+      type: "uvx",
+      package: distribution.package,
+      command: platformCommand("uvx", options.platform),
+      args: [distribution.package, ...(distribution.args || [])],
+      env: { ...(distribution.env || {}) },
+    };
+  }
+  const platformKey = currentPlatformKey(options.platform, options.arch);
+  const target = agent.distribution.binary?.[platformKey];
+  if (!target) {
+    throw new Error(
+      `${agent.name} does not publish an ACP binary for ${platformKey}. Use --agent-command if it is already installed another way.`,
+    );
+  }
+  const agentHome =
+    options.agentHome || path.join(os.homedir(), ".engineeros", "agents");
+  const installDir = path.join(
+    agentHome,
+    agent.id,
+    managedSegment(agent.version),
+    platformKey,
+  );
+  return {
+    type: "binary",
+    command: resolveManagedCommand(installDir, target.cmd),
+    args: stringArray(target.args, `${agent.id} binary args`),
+    env: stringRecord(target.env, `${agent.id} binary environment`),
+    archive: validatedArchiveUrl(target.archive, agent.name),
+    sha256: target.sha256 ? String(target.sha256).toLowerCase() : null,
+    installDir,
+    target,
+  };
+}
+
+function validatePackageDistribution(agent, type, distribution) {
+  const packageName = String(distribution.package || "").trim();
+  if (!packageName || !/^[a-zA-Z0-9@][a-zA-Z0-9@/._+=:-]*$/.test(packageName)) {
+    throw new Error(`${agent.name} has an invalid ${type} package.`);
+  }
+  return {
+    package: packageName,
+    args: stringArray(distribution.args, `${agent.id} ${type} args`),
+    env: stringRecord(distribution.env, `${agent.id} ${type} environment`),
+  };
+}
+
+function stringArray(value, label) {
+  if (value === undefined) return [];
+  if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) {
+    throw new Error(`The ACP registry contains invalid ${label}.`);
+  }
+  return [...value];
+}
+
+function stringRecord(value, label) {
+  if (value === undefined) return {};
+  if (
+    !value ||
+    typeof value !== "object" ||
+    Array.isArray(value) ||
+    Object.values(value).some((item) => typeof item !== "string")
+  ) {
+    throw new Error(`The ACP registry contains an invalid ${label}.`);
+  }
+  return { ...value };
+}
+
+function compareAgents(left, right) {
+  const leftPriority = PRIORITY_AGENT_IDS.indexOf(left.id);
+  const rightPriority = PRIORITY_AGENT_IDS.indexOf(right.id);
+  if (leftPriority >= 0 || rightPriority >= 0) {
+    if (leftPriority < 0) return 1;
+    if (rightPriority < 0) return -1;
+    return leftPriority - rightPriority;
+  }
+  return left.name.localeCompare(right.name);
+}
+
+function normalizeLookup(value) {
+  return String(value || "")
+    .trim()
+    .toLowerCase();
+}
+
+function managedSegment(value) {
+  const segment = String(value).replace(/[^a-zA-Z0-9._+-]/g, "_");
+  return segment === "." || segment === ".." ? `_${segment}` : segment;
+}
+
+function validatedArchiveUrl(value, agentName) {
+  try {
+    const url = new URL(String(value || ""));
+    if (url.protocol !== "https:") throw new Error("not HTTPS");
+    return url.toString();
+  } catch {
+    throw new Error(
+      `${agentName} has an invalid binary download URL in the ACP registry.`,
+    );
+  }
+}
+
+function platformCommand(command, platform = process.platform) {
+  return platform === "win32" ? `${command}.cmd` : command;
+}
+
+async function commandAvailable(command, options) {
+  const key = `${options.platform || process.platform}:${command}`;
+  if (!options.runCommand && commandChecks.has(key))
+    return commandChecks.get(key);
+  const checking = (async () => {
+    const checker =
+      (options.platform || process.platform) === "win32"
+        ? "where.exe"
+        : "which";
+    const result = await (options.runCommand || runCommand)(
+      checker,
+      [command],
+      {
+        ...options,
+        inherit: false,
+      },
+    );
+    return result.code === 0;
+  })();
+  if (!options.runCommand) commandChecks.set(key, checking);
+  return checking;
+}
+
+async function installBinary(agent, launch, options) {
+  if (await fileExists(launch.command)) return;
+  if (!launch.archive) {
+    throw new Error(
+      `${agent.name} has no binary download URL in the ACP registry.`,
+    );
+  }
+  const parent = path.dirname(launch.installDir);
+  const stage = path.join(
+    parent,
+    `.${path.basename(launch.installDir)}-${randomUUID()}`,
+  );
+  const downloadPath = path.join(stage, archiveFilename(launch.archive));
+  await mkdir(stage, { recursive: true });
+  try {
+    const response = await (options.fetch || globalThis.fetch)(launch.archive, {
+      signal: options.signal || AbortSignal.timeout(120_000),
+    });
+    if (!response.ok || !response.body) {
+      throw new Error(
+        `Download failed (${response.status} ${response.statusText}).`.trim(),
+      );
+    }
+    await pipeline(
+      Readable.fromWeb(response.body),
+      createWriteStream(downloadPath),
+    );
+    if (launch.sha256) await verifySha256(downloadPath, launch.sha256);
+    const archiveKind = archiveType(downloadPath);
+    if (archiveKind === "binary") {
+      const stagedCommand = resolveManagedCommand(stage, launch.target.cmd);
+      await mkdir(path.dirname(stagedCommand), { recursive: true });
+      await rename(downloadPath, stagedCommand);
+    } else {
+      await extractArchive(downloadPath, stage, archiveKind, options);
+      await rm(downloadPath, { force: true });
+    }
+    const stagedCommand = resolveManagedCommand(stage, launch.target.cmd);
+    if (!(await fileExists(stagedCommand))) {
+      throw new Error(
+        `The ${agent.name} archive did not contain ${launch.target.cmd}.`,
+      );
+    }
+    if ((options.platform || process.platform) !== "win32") {
+      await chmod(stagedCommand, 0o755);
+    }
+    await mkdir(parent, { recursive: true });
+    await rm(launch.installDir, { recursive: true, force: true });
+    await rename(stage, launch.installDir);
+  } catch (error) {
+    await rm(stage, { recursive: true, force: true });
+    throw new Error(
+      `Could not install ${agent.name}: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}
+
+function archiveFilename(url) {
+  try {
+    const filename = path
+      .basename(new URL(url).pathname)
+      .replace(/[^a-zA-Z0-9._+-]/g, "_");
+    return filename && filename !== "." && filename !== ".."
+      ? filename
+      : "agent-binary";
+  } catch {
+    return "agent-binary";
+  }
+}
+
+function archiveType(filename) {
+  const lower = filename.toLowerCase();
+  if (lower.endsWith(".zip")) return "zip";
+  if (
+    lower.endsWith(".tar.gz") ||
+    lower.endsWith(".tgz") ||
+    lower.endsWith(".tar.bz2") ||
+    lower.endsWith(".tbz2")
+  ) {
+    return "tar";
+  }
+  return "binary";
+}
+
+async function extractArchive(archive, destination, kind, options) {
+  const platform = options.platform || process.platform;
+  const command = kind === "zip" && platform === "linux" ? "unzip" : "tar";
+  const listArgs =
+    kind === "zip" && platform === "linux"
+      ? ["-Z1", archive]
+      : ["-tf", archive];
+  const args =
+    kind === "zip" && platform === "linux"
+      ? ["-q", archive, "-d", destination]
+      : ["-xf", archive, "-C", destination];
+  const runner = options.runCommand || runCommand;
+  const listing = await runner(command, listArgs, {
+    ...options,
+    inherit: false,
+  });
+  if (listing.code !== 0) {
+    throw new Error(
+      `Archive inspection failed. Install '${command}' and retry. ${String(listing.output || "").trim()}`.trim(),
+    );
+  }
+  validateArchiveEntries(listing.output);
+  const result = await runner(command, args, {
+    ...options,
+    inherit: true,
+  });
+  if (result.code !== 0) {
+    throw new Error(
+      `Archive extraction failed. Install '${command}' and retry. ${String(result.output || "").trim()}`.trim(),
+    );
+  }
+}
+
+function validateArchiveEntries(output) {
+  for (const entry of String(output || "").split(/\r?\n/)) {
+    const normalized = entry.trim().replace(/\\/g, "/");
+    if (!normalized) continue;
+    const segments = normalized.split("/");
+    if (
+      normalized.startsWith("/") ||
+      /^[a-zA-Z]:/.test(normalized) ||
+      segments.includes("..")
+    ) {
+      throw new Error(`The agent archive contains an unsafe path: ${entry}.`);
+    }
+  }
+}
+
+function resolveManagedCommand(root, command) {
+  const relative = String(command || "")
+    .replace(/^[.][\\/]/, "")
+    .replace(/[\\/]+/g, path.sep);
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(resolvedRoot, relative);
+  if (
+    !relative ||
+    (resolved !== resolvedRoot &&
+      !resolved.startsWith(`${resolvedRoot}${path.sep}`))
+  ) {
+    throw new Error("The ACP registry contains an unsafe binary command path.");
+  }
+  return resolved;
+}
+
+async function verifySha256(filename, expected) {
+  if (!/^[a-f0-9]{64}$/.test(expected)) {
+    throw new Error("The ACP registry contains an invalid SHA-256 checksum.");
+  }
+  const hash = createHash("sha256");
+  for await (const chunk of createReadStream(filename)) hash.update(chunk);
+  const actual = hash.digest("hex");
+  if (actual !== expected) {
+    throw new Error(
+      `Binary checksum mismatch (expected ${expected}, received ${actual}).`,
+    );
+  }
+}
+
+async function fileExists(filename) {
+  try {
+    await access(filename);
+    const details = await stat(filename);
+    return details.isFile();
+  } catch {
+    return false;
+  }
+}
+
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve) => {
+    let output = "";
+    const child = spawn(command, args, {
+      cwd: options.cwd ?? process.cwd(),
+      env: { ...process.env, ...(options.env || {}) },
+      shell:
+        (options.platform || process.platform) === "win32" &&
+        /\.(cmd|bat)$/i.test(command),
+      stdio: options.inherit ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+    if (!options.inherit) {
+      child.stdout.setEncoding("utf8");
+      child.stderr.setEncoding("utf8");
+      child.stdout.on("data", (chunk) => (output += chunk));
+      child.stderr.on("data", (chunk) => (output += chunk));
+    }
+    child.once("error", (error) =>
+      resolve({ code: -1, output: error.message }),
+    );
+    child.once("close", (code) => resolve({ code: code ?? -1, output }));
+  });
+}

package/src/capabilities.mjs

@@ -1,4 +1,5 @@
 import path from "node:path";
+import { agentHarnessCapabilities } from "./agent-harness.mjs";
 
 export function advertisedCapabilities(config, codingAgent) {
   const configuredModels = String(
@@ -15,6 +16,7 @@ export function advertisedCapabilities(config, codingAgent) {
     workspace_name: path.basename(config.workspace),
     agent_name: codingAgent.name,
     agent_version: codingAgent.version,
+    ...agentHarnessCapabilities(),
     execution_profiles: {
       model_selection: codingAgent.protocol === "codex",
       models: codingAgent.protocol === "codex" ? configuredModels : [],

package/src/config.mjs

@@ -46,11 +46,18 @@ export function mergePairedConfig(
 ) {
   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 || {} : {},
   };
 }