tryharness 0.3.0 → 0.4.1

package/README.md

@@ -1,22 +1,41 @@
 # tryharness
 
-Connect this machine to [Harness](https://tryharness.ai).
+Connect the coding agents installed on this machine to [Harness](https://tryharness.ai):
 
-```
+```sh
 npx tryharness
 ```
 
-Prints a short code — approve it in Harness (Settings, Connections, Connect a machine).
-Then it sets up everything it finds on this machine: memory access, automatic sharing
-for new sessions, accurate connection status, and task delegation for Claude Code,
-Codex, pi, and opencode. Setup does not import old history, so it finishes quickly.
+Supports the Node.js 18, 20, 22, and 24 release lines.
+
+That one command pairs the machine, detects Claude Code, Codex, pi, and opencode,
+configures every installed agent, installs the Harness daemon as a user-level login
+service, validates readiness, and starts indexing existing coding sessions locally in
+SQLite. Setup returns as soon as the daemon is ready; indexing continues in the
+background and does not require an open Harness tab.
+
+The command is idempotent. Run it again after installing another agent or to repair its
+configuration.
 
-Other commands: `npx tryharness bridge` (start the task bridge again),
-`npx tryharness sync --agent all` (explicitly import existing sessions),
-`npx tryharness drain` (retry session reports that missed).
+## Operations
+
+```sh
+npx tryharness status
+npx tryharness doctor
+npx tryharness sync --agent codex
+npx tryharness logs --follow
+npx tryharness handoff codex --file ./implementation-brief.md
+npx tryharness disconnect
+```
 
-Use `npx tryharness --agent codex` (or another agent name) to connect only one
-installed agent. Plain `npx tryharness` connects all detected agents.
+`status` is the normal health view. `doctor` verifies pairing, the login service, the
+daemon, the bridge, the database, and agent discovery. `sync` requests a background
+rescan; it is diagnostic, not part of normal setup.
 
-No tokens to copy: approval releases the credential directly to the waiting command.
-Everything your agents share stays between your machine and your browser.
+The daemon dials out to Harness over one authenticated WebSocket. Its local control
+socket is permissioned to the current user. When OpenCode is installed, the daemon also
+starts OpenCode's own helper on a random loopback-only port with a random per-process
+password so it can index OpenCode history; no fixed or unauthenticated port is used.
+Connection tokens stay in `~/.harness/config.json` with owner-only permissions. Coding
+history and handoffs stay in the local SQLite database unless an explicit operation
+sends content through Harness.

package/assets/opencode-plugin.js

@@ -0,0 +1,27 @@
+// Installed globally by tryharness. It only nudges the local daemon; indexing and retry
+// state stay in the daemon's SQLite database and never block opencode's idle event.
+import net from "node:net";
+import os from "node:os";
+import path from "node:path";
+
+const socketPath = process.platform === "win32"
+  ? "\\\\.\\pipe\\tryharness-daemon"
+  : path.join(os.homedir(), ".harness", "daemon.sock");
+
+function notify(message) {
+  try {
+    const socket = net.createConnection(socketPath);
+    socket.setTimeout(1_000);
+    socket.on("connect", () => socket.end(JSON.stringify(message) + "\n"));
+    socket.on("error", () => {});
+    socket.on("timeout", () => socket.destroy());
+  } catch {}
+}
+
+export const TryHarnessPlugin = async ({ directory }) => ({
+  event: async ({ event }) => {
+    if (event?.type !== "session.idle") return;
+    const sessionId = event?.properties?.sessionID || event?.properties?.sessionId;
+    if (sessionId) notify({ command: "sync", agent: "opencode", sessionId, cwd: directory });
+  },
+});

package/assets/pi-extension.ts

@@ -0,0 +1,92 @@
+// @ts-nocheck
+// Installed globally by tryharness. pi has no native MCP client, so the extension maps
+// the connected Harness MCP surface into normal pi tools without blocking pi startup.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+const CONFIG_PATH = path.join(os.homedir(), ".harness", "config.json");
+let nextId = 1;
+let typeApi = null;
+
+function config() {
+  try { return JSON.parse(fs.readFileSync(CONFIG_PATH, "utf8")); } catch { return {}; }
+}
+
+async function rpc(method, params = {}) {
+  const current = config();
+  if (!current.origin || !current.token) throw new Error("Harness is not connected. Run: npx tryharness");
+  const response = await fetch(String(current.origin).replace(/\/$/, "") + "/api/mcp", {
+    method: "POST",
+    headers: { "content-type": "application/json", authorization: "Bearer " + current.token },
+    body: JSON.stringify({ jsonrpc: "2.0", id: nextId++, method, params }),
+    signal: AbortSignal.timeout(90_000),
+  });
+  const payload = await response.json().catch(() => null);
+  if (!response.ok || payload?.error) throw new Error(payload?.error?.message || "Harness returned HTTP " + response.status);
+  return payload?.result;
+}
+
+async function types() {
+  if (typeApi) return typeApi;
+  try { typeApi = (await import("@sinclair/typebox")).Type; }
+  catch { const loaded = await import("typebox"); typeApi = loaded.Type || loaded; }
+  return typeApi;
+}
+
+function toType(schema, Type) {
+  if (!schema || typeof schema !== "object") return Type.Any();
+  const opts = typeof schema.description === "string" ? { description: schema.description } : {};
+  if (Array.isArray(schema.enum) && schema.enum.length) return Type.Union(schema.enum.map((value) => Type.Literal(value)), opts);
+  if (Array.isArray(schema.anyOf || schema.oneOf)) return Type.Union((schema.anyOf || schema.oneOf).map((entry) => toType(entry, Type)), opts);
+  if (schema.type === "object") {
+    const required = new Set(schema.required || []);
+    const properties = {};
+    for (const [name, child] of Object.entries(schema.properties || {})) {
+      const converted = toType(child, Type);
+      properties[name] = required.has(name) ? converted : Type.Optional(converted);
+    }
+    return Type.Object(properties, { ...opts, additionalProperties: schema.additionalProperties === true });
+  }
+  if (schema.type === "array") return Type.Array(toType(schema.items, Type), opts);
+  if (schema.type === "string") return Type.String(opts);
+  if (schema.type === "integer") return Type.Integer(opts);
+  if (schema.type === "number") return Type.Number(opts);
+  if (schema.type === "boolean") return Type.Boolean(opts);
+  if (schema.type === "null") return Type.Null(opts);
+  return Type.Any(opts);
+}
+
+export default function tryHarness(pi) {
+  const installed = new Set();
+  let connecting = null;
+  const connect = async (ctx) => {
+    if (connecting) return connecting;
+    connecting = (async () => {
+      const Type = await types();
+      const listing = await rpc("tools/list");
+      for (const def of listing?.tools || []) {
+        if (!def?.name || def.name === "report_session" || installed.has(def.name)) continue;
+        pi.registerTool({
+          name: def.name,
+          label: "Harness: " + def.name.replaceAll("_", " "),
+          description: def.description || "Use this connected Harness capability.",
+          parameters: toType(def.inputSchema, Type),
+          async execute(_id, params) {
+            try {
+              const result = await rpc("tools/call", { name: def.name, arguments: params || {} });
+              return { content: result?.content || [{ type: "text", text: "Harness returned no content." }], details: {}, isError: result?.isError === true };
+            } catch (error) {
+              return { content: [{ type: "text", text: error?.message || "Harness call failed." }], details: {}, isError: true };
+            }
+          },
+        });
+        installed.add(def.name);
+      }
+      ctx?.ui?.notify?.("Harness connected", "info");
+    })().finally(() => { connecting = null; });
+    return connecting;
+  };
+  pi.on("session_start", (_event, ctx) => void connect(ctx).catch((error) => ctx?.ui?.notify?.("Harness unavailable: " + error?.message, "warning")));
+  pi.registerCommand("harness-reconnect", { description: "Reconnect Harness", handler: async (_args, ctx) => connect(ctx) });
+}

package/cli.mjs

@@ -1,69 +1,251 @@
 #!/usr/bin/env node
-// tryharness: thin bootstrap. The real logic lives on the Harness server and is fetched
-// fresh on every run, so this package never needs republishing to pick up improvements
-// (a cached copy in ~/.harness runs when offline). Works on Node 18+ — when the runtime
-// lacks a built-in WebSocket (added in Node 22), the bundled `ws` package fills it in,
-// which is why scripts run IN-PROCESS here instead of being spawned. Commands:
-//   npx tryharness            pair this machine + set up every detected agent
-//   npx tryharness --agent codex   set up only one detected agent
-//   npx tryharness bridge     start the task bridge (after pairing)
-//   npx tryharness sync       explicitly import existing agent sessions
-//   npx tryharness drain      retry any session reports that missed
 import fs from "node:fs";
-import path from "node:path";
 import os from "node:os";
-import { pathToFileURL } from "node:url";
-
-const HARNESS_DIR = path.join(os.homedir(), ".harness");
-const COMMANDS = {
-  connect: { file: "connect.mjs", args: [] },
-  bridge: { file: "bridge.mjs", args: [] },
-  sync: { file: "report-session.mjs", args: ["--backfill"] },
-  backfill: { file: "report-session.mjs", args: ["--backfill"] },
-  drain: { file: "report-session.mjs", args: ["--drain"] },
-};
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { configureAgents, AGENTS, removeAgentConfigurations } from "./lib/adapters.mjs";
+import { detectAgents } from "./lib/commands.mjs";
+import { daemonRequest } from "./lib/control-client.mjs";
+import { ensureDir, readJson, writeJsonAtomic } from "./lib/files.mjs";
+import { paths } from "./lib/paths.mjs";
+import { installRuntime } from "./lib/runtime-install.mjs";
+import { installService, serviceInfo, uninstallService } from "./lib/service.mjs";
 
-const argv = process.argv.slice(2);
-const sub = argv[0] && !argv[0].startsWith("-") ? argv.shift() : "connect";
-const command = COMMANDS[sub];
-if (!command) {
-  console.error("unknown command: " + sub + " (try: connect | bridge | sync | drain)");
+const SOURCE_ROOT = path.dirname(fileURLToPath(import.meta.url));
+const PACKAGE = readJson(path.join(SOURCE_ROOT, "package.json"), { version: "0.4.1" });
+const VERSION = PACKAGE.version;
+const NODE_MAJOR = Number(process.versions.node.split(".")[0]);
+if (!Number.isFinite(NODE_MAJOR) || NODE_MAJOR < 18) {
+  console.error(`tryharness requires Node.js 18 or newer (current: ${process.version}). Upgrade Node, then rerun: npx tryharness`);
   process.exit(1);
 }
+const argv = process.argv.slice(2);
+const command = ["--help", "-h"].includes(argv[0])
+  ? (argv.shift(), "help")
+  : argv[0] === "--version"
+    ? (argv.shift(), "version")
+    : argv[0] && !argv[0].startsWith("-") ? argv.shift() : "connect";
 
-let savedOrigin = null;
-try {
-  savedOrigin = JSON.parse(fs.readFileSync(path.join(HARNESS_DIR, "config.json"), "utf8")).origin || null;
-} catch {
-  savedOrigin = null;
+function arg(flag, fallback = null) {
+  const index = argv.indexOf(flag);
+  return index >= 0 && argv[index + 1] ? argv[index + 1] : fallback;
+}
+function has(flag) { return argv.includes(flag); }
+function origin() {
+  const saved = readJson(paths.config, {});
+  return String(arg("--origin", saved.origin || "https://tryharness.ai")).replace(/\/$/, "");
 }
-const originIndex = argv.indexOf("--origin");
-const origin = (originIndex !== -1 && argv[originIndex + 1] ? argv[originIndex + 1] : savedOrigin || "https://tryharness.ai").replace(/\/$/, "");
 
-const dest = path.join(HARNESS_DIR, command.file);
-fs.mkdirSync(HARNESS_DIR, { recursive: true });
-try {
-  // 15s cap: a fetch that dials the server mid-restart can otherwise hang forever
-  // with zero output. On timeout the cached copy runs, same as any other fetch failure.
-  const res = await fetch(origin + "/" + command.file, { signal: AbortSignal.timeout(15000) });
-  if (!res.ok) throw new Error("HTTP " + res.status);
-  fs.writeFileSync(dest, await res.text());
-} catch (error) {
-  if (!fs.existsSync(dest)) {
-    console.error("could not reach " + origin + " (" + error.message + ") and no cached copy exists");
-    process.exit(1);
+async function validateConnection(config) {
+  if (!config.origin || !config.token) return false;
+  try {
+    const response = await fetch(String(config.origin).replace(/\/$/, "") + "/api/mcp", {
+      method: "POST",
+      headers: { "content-type": "application/json", authorization: "Bearer " + config.token },
+      body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: { protocolVersion: "2025-06-18", capabilities: {}, clientInfo: { name: "tryharness", version: VERSION } } }),
+      signal: AbortSignal.timeout(10_000),
+    });
+    return response.ok && !((await response.json().catch(() => null))?.error);
+  } catch { return false; }
+}
+
+async function pair(pairOrigin, agents) {
+  const response = await fetch(pairOrigin + "/api/pair/start", {
+    method: "POST",
+    headers: { "content-type": "application/json" },
+    body: JSON.stringify({ hostname: os.hostname().slice(0, 64), agents }),
+    signal: AbortSignal.timeout(15_000),
+  });
+  if (!response.ok) throw new Error(`pairing unavailable (HTTP ${response.status})`);
+  const { pairId, code } = await response.json();
+  console.log(`\n  Your code:  ${code}\n`);
+  console.log("In Harness: Settings -> Connections -> Connect a machine -> enter the code.");
+  console.log("Waiting for approval (expires in 10 minutes)...");
+  return new Promise((resolve, reject) => {
+    fetch(pairOrigin + "/api/pair/wait/" + pairId, { headers: { accept: "text/event-stream" } }).then(async (waitResponse) => {
+      if (!waitResponse.ok || !waitResponse.body) throw new Error("pairing stream failed");
+      const reader = waitResponse.body.getReader();
+      const decoder = new TextDecoder();
+      let buffer = "";
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buffer += decoder.decode(value, { stream: true });
+        const frames = buffer.split("\n\n");
+        buffer = frames.pop() || "";
+        for (const frame of frames) {
+          const line = frame.split("\n").find((entry) => entry.startsWith("data: "));
+          if (!line) continue;
+          const payload = JSON.parse(line.slice(6));
+          if (payload.token) { resolve(payload.token); return; }
+          if (payload.error) { reject(new Error(payload.error)); return; }
+        }
+      }
+      reject(new Error("pairing stream ended without approval"));
+    }).catch(reject);
+  });
+}
+
+async function waitForDaemon(timeoutMs = 12_000) {
+  const deadline = Date.now() + timeoutMs;
+  let lastError;
+  let lastStatus;
+  while (Date.now() < deadline) {
+    try {
+      lastStatus = await daemonRequest({ command: "status" }, 1_000);
+      if (lastStatus.connected) return lastStatus;
+      if (lastStatus.lastError) lastError = new Error(lastStatus.lastError);
+    }
+    catch (error) { lastError = error; }
+    await new Promise((resolve) => setTimeout(resolve, 250));
+  }
+  throw new Error(`daemon started but its authenticated Harness bridge did not become ready: ${lastError?.message || lastStatus?.lastError || "timeout"}. Run: npx tryharness doctor`);
+}
+
+function printAgentStates(states) {
+  for (const state of states) {
+    const icon = !state.installed ? "–" : state.configured ? "✓" : "!";
+    console.log(`  ${icon} ${state.agent}: ${state.detail}`);
   }
-  console.error("could not refresh from " + origin + " - running the cached copy");
 }
 
-// Older LTS Node (18/20): provide WebSocket from the bundled `ws` package so the bridge
-// works everywhere npx does.
-if (typeof globalThis.WebSocket === "undefined") {
-  const { WebSocket } = await import("ws");
-  globalThis.WebSocket = WebSocket;
+async function connect() {
+  ensureDir(paths.home);
+  const detected = detectAgents();
+  const installed = detected.filter((entry) => entry.path).map((entry) => entry.agent);
+  const requested = argv.flatMap((value, index) => value === "--agent" && argv[index + 1] ? [argv[index + 1]] : []);
+  for (const agent of requested) if (!AGENTS.includes(agent)) throw new Error(`unknown agent '${agent}'`);
+  const selected = requested.length ? installed.filter((agent) => requested.includes(agent)) : installed;
+  console.log(`Harness setup ${VERSION}`);
+  console.log("detected: " + (installed.join(", ") || "no supported coding agents"));
+
+  const pairOrigin = origin();
+  let config = readJson(paths.config, {});
+  const reusable = !has("--reconnect") && config.origin === pairOrigin && await validateConnection(config);
+  if (reusable) console.log("pairing: already connected");
+  else {
+    const token = await pair(pairOrigin, selected);
+    config = { ...config, origin: pairOrigin, token };
+    writeJsonAtomic(paths.config, config);
+    console.log("pairing: approved");
+  }
+
+  // The persistent runtime is version-pinned; neither MCP clients nor the login service
+  // point into npm's temporary npx cache.
+  const runtimeRoot = installRuntime({ sourceRoot: SOURCE_ROOT, version: VERSION });
+  const states = configureAgents({ runtimeRoot, selected });
+  const stateMap = Object.fromEntries(states.map((state) => [state.agent, state]));
+  config = { ...readJson(paths.config, config), version: VERSION, runtimeRoot, agentStates: stateMap };
+  writeJsonAtomic(paths.config, config);
+  printAgentStates(states);
+
+  const service = installService({ runtimeRoot });
+  const ready = await waitForDaemon();
+  console.log(`daemon: ready via ${service.manager} and connected to Harness`);
+  const failed = states.filter((state) => selected.includes(state.agent) && state.installed && !state.configured);
+  if (failed.length) {
+    throw new Error(`setup is incomplete for ${failed.map((state) => state.agent).join(", ")}. Nothing was hidden; run npx tryharness doctor after fixing the reported CLI error, then rerun setup.`);
+  }
+  console.log("history: indexing locally in the background");
+  console.log("Done. You can close this terminal.");
 }
 
-// Run the script in-process (so the polyfill above applies), with argv shaped exactly
-// as a direct `node <script> <args>` run would see it.
-process.argv = [process.argv[0], dest, ...command.args, ...argv];
-await import(pathToFileURL(dest).href);
+async function status() {
+  const fallback = readJson(paths.status, null);
+  let current;
+  try { current = await daemonRequest({ command: "status" }); }
+  catch { current = fallback ? { ok: false, ...fallback } : null; }
+  const service = serviceInfo();
+  if (!current) {
+    console.log("Harness daemon: not running");
+    console.log(`service: ${service.installed ? "installed" : "not installed"}`);
+    process.exitCode = 1;
+    return;
+  }
+  console.log(`Harness daemon ${current.version || "unknown"}: ${current.ok === false ? "not responding" : "running"} (pid ${current.pid || "?"})`);
+  console.log(`Harness bridge: ${current.connected ? "connected" : "disconnected"}`);
+  console.log(`history: ${current.indexing ? "indexing" : "ready"}${current.lastIndexedAt ? ` · last scan ${current.lastIndexedAt}` : ""}`);
+  for (const state of current.agents || []) {
+    const count = Number(current.counts?.[state.agent] || 0);
+    console.log(`  ${state.agent}: ${state.installed ? state.configured ? "ready" : "installed, configuration needs repair" : "not installed"} · ${count} sessions`);
+  }
+}
+
+async function doctor() {
+  console.log(`tryharness ${VERSION}`);
+  const config = readJson(paths.config, {});
+  console.log(`pairing: ${await validateConnection(config) ? "valid" : "missing or invalid"}`);
+  const service = serviceInfo();
+  console.log(`service: ${service.installed ? `installed (${service.manager})` : `not installed (${service.manager})`}`);
+  try {
+    const report = await daemonRequest({ command: "doctor" });
+    console.log(`daemon: running (pid ${report.status.pid})`);
+    console.log(`bridge: ${report.status.connected ? "connected" : `disconnected${report.status.lastError ? ` — ${report.status.lastError}` : ""}`}`);
+    console.log(`database: ${report.database}`);
+    console.log(`control socket: ${report.socket}`);
+    console.log(`log: ${report.log}`);
+  } catch (error) {
+    console.log(`daemon: unavailable — ${error.message}`);
+    process.exitCode = 1;
+  }
+  for (const found of detectAgents()) console.log(`${found.agent}: ${found.path || "not installed"}`);
+}
+
+async function sync() {
+  const agent = arg("--agent", "all");
+  if (agent !== "all" && !AGENTS.includes(agent)) throw new Error(`unknown agent '${agent}'`);
+  const response = await daemonRequest({ command: "sync", agent });
+  if (!response.ok) throw new Error(response.error || "sync rejected");
+  console.log(`Local history scan started for ${agent}. It runs in the daemon; this terminal does not need to stay open.`);
+}
+
+async function handoff() {
+  const agent = argv[0];
+  if (!AGENTS.includes(agent)) throw new Error("usage: tryharness handoff <claude-code|codex|pi|opencode> --file <brief.md>");
+  const file = arg("--file");
+  let body = "";
+  if (file) body = fs.readFileSync(path.resolve(file), "utf8");
+  else if (!process.stdin.isTTY) for await (const chunk of process.stdin) body += chunk;
+  else body = arg("--body", "");
+  if (!body.trim()) throw new Error("handoff needs --file, --body, or piped input");
+  const response = await daemonRequest({ command: "handoffs.create", agent, sessionId: arg("--session"), title: arg("--title", path.basename(file || "Harness handoff")), body, source: file ? path.resolve(file) : "tryharness CLI" });
+  if (!response.ok) throw new Error(response.error || "handoff failed");
+  console.log(`Handoff ${response.id} is ready for ${agent}. Harness's get_handoff tool can read it.`);
+}
+
+function logs() {
+  if (!fs.existsSync(paths.log)) { console.log("No daemon log yet."); return; }
+  const lines = fs.readFileSync(paths.log, "utf8").split("\n");
+  process.stdout.write(lines.slice(-Math.max(1, Number(arg("--lines", "100")))).join("\n"));
+  if (has("--follow")) fs.watchFile(paths.log, { interval: 500 }, () => process.stdout.write(fs.readFileSync(paths.log, "utf8").split("\n").slice(-20).join("\n")));
+}
+
+async function disconnect() {
+  uninstallService();
+  try { await daemonRequest({ command: "shutdown" }, 2_000); } catch {}
+  removeAgentConfigurations();
+  try { fs.renameSync(paths.config, paths.config + `.disconnected-${Date.now()}`); } catch {}
+  for (const target of [paths.status, paths.socket]) try { fs.unlinkSync(target); } catch {}
+  console.log("Harness disconnected. The local history database was preserved.");
+}
+
+function help() {
+  console.log(`tryharness ${VERSION}\n\nCommands:\n  tryharness                 set up everything and start the daemon\n  tryharness status          show daemon, bridge, agent, and index health\n  tryharness doctor          diagnose the complete connection\n  tryharness sync [--agent]  rescan local coding history in the background\n  tryharness handoff <agent> --file <path>\n  tryharness logs [--follow]\n  tryharness disconnect\n`);
+}
+
+try {
+  if (command === "connect" || command === "setup") await connect();
+  else if (command === "status" || command === "bridge") await status();
+  else if (command === "doctor") await doctor();
+  else if (command === "sync" || command === "backfill" || command === "drain") await sync();
+  else if (command === "handoff") await handoff();
+  else if (command === "logs") logs();
+  else if (command === "disconnect") await disconnect();
+  else if (command === "daemon") { const { startDaemon } = await import("./lib/daemon.mjs"); await startDaemon(); }
+  else if (command === "version") console.log(VERSION);
+  else if (["help", "--help", "-h"].includes(command)) help();
+  else throw new Error(`unknown command '${command}' (run: tryharness help)`);
+} catch (error) {
+  console.error(`tryharness: ${error.message}`);
+  process.exitCode = 1;
+}

package/lib/adapters.mjs

@@ -0,0 +1,81 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { detectAgents, run } from "./commands.mjs";
+import { ensureDir, readJson } from "./files.mjs";
+import { paths } from "./paths.mjs";
+
+export const AGENTS = ["claude-code", "codex", "pi", "opencode"];
+
+function installAsset(source, target) {
+  ensureDir(path.dirname(target));
+  fs.copyFileSync(source, target);
+  try { fs.chmodSync(target, 0o600); } catch {}
+}
+
+function diagnostic(result) {
+  return (result.stderr || result.stdout || result.error || "command failed").replace(/\s+/g, " ").trim().slice(0, 240);
+}
+
+export function integrationAssets(homeDir = os.homedir()) {
+  return {
+    pi: path.join(homeDir, ".pi", "agent", "extensions", "tryharness.ts"),
+    opencode: path.join(homeDir, ".config", "opencode", "plugins", "tryharness.js"),
+  };
+}
+
+export function configureAgents({ runtimeRoot, selected = AGENTS, homeDir = os.homedir(), detected = detectAgents(), execute = run, connection = readJson(paths.config, {}) }) {
+  const byAgent = new Map(detected.map((entry) => [entry.agent, entry]));
+  const mcpPath = path.join(runtimeRoot, "lib", "mcp-stdio.mjs");
+  const assets = integrationAssets(homeDir);
+  const states = [];
+  for (const agent of AGENTS) {
+    const found = byAgent.get(agent);
+    if (!found?.path) {
+      states.push({ agent, installed: false, configured: false, detail: "not installed" });
+      continue;
+    }
+    if (!selected.includes(agent)) {
+      states.push({ agent, installed: true, configured: false, detail: "not selected" });
+      continue;
+    }
+    if (agent === "claude-code") {
+      execute(found.path, ["mcp", "remove", "--scope", "user", "harness"]);
+      const added = execute(found.path, ["mcp", "add", "--scope", "user", "harness", "--", process.execPath, mcpPath, "--agent", agent]);
+      states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? "MCP configured" : diagnostic(added) });
+    } else if (agent === "codex") {
+      execute(found.path, ["mcp", "remove", "harness"]);
+      const added = execute(found.path, ["mcp", "add", "harness", "--", process.execPath, mcpPath, "--agent", agent]);
+      states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? "MCP configured" : diagnostic(added) });
+    } else if (agent === "pi") {
+      installAsset(path.join(runtimeRoot, "assets", "pi-extension.ts"), assets.pi);
+      states.push({ agent, installed: true, configured: fs.existsSync(assets.pi), detail: "extension installed" });
+    } else {
+      installAsset(path.join(runtimeRoot, "assets", "opencode-plugin.js"), assets.opencode);
+      // Keep opencode's already-working remote MCP configuration. The daemon/plugin path
+      // handles history; this command supplies Harness memory tools.
+      execute(found.path, ["mcp", "remove", "harness"]);
+      const added = execute(found.path, ["mcp", "add", "harness", "--url", String(connection.origin).replace(/\/$/, "") + "/api/mcp", "--header", "Authorization=Bearer " + connection.token]);
+      states.push({ agent, installed: true, configured: added.ok, detail: added.ok ? "MCP and plugin configured" : `plugin installed; MCP: ${diagnostic(added)}` });
+    }
+  }
+  return states;
+}
+
+export function agentHealth(states) {
+  return Object.fromEntries(states.map((state) => [state.agent, state]));
+}
+
+export function removeAgentConfigurations({ homeDir = os.homedir(), detected = detectAgents(), execute = run } = {}) {
+  for (const found of detected) {
+    if (!found.path) continue;
+    if (found.agent === "claude-code") execute(found.path, ["mcp", "remove", "--scope", "user", "harness"]);
+    else if (found.agent === "codex" || found.agent === "opencode") execute(found.path, ["mcp", "remove", "harness"]);
+  }
+  const assets = integrationAssets(homeDir);
+  for (const target of Object.values(assets)) {
+    try { fs.unlinkSync(target); } catch (error) {
+      if (error?.code !== "ENOENT") throw error;
+    }
+  }
+}

package/lib/commands.mjs

@@ -0,0 +1,57 @@
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+
+export function resolveCommand(command, env = process.env) {
+  const pathValue = env.PATH || "";
+  const extensions = process.platform === "win32"
+    ? (env.PATHEXT || ".EXE;.CMD;.BAT;.COM").split(";")
+    : [""];
+  for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+    for (const extension of extensions) {
+      const candidate = path.join(dir, process.platform === "win32" ? command + extension.toLowerCase() : command);
+      const alternate = path.join(dir, command + extension);
+      for (const file of candidate === alternate ? [candidate] : [candidate, alternate]) {
+        try {
+          fs.accessSync(file, fs.constants.X_OK);
+          return file;
+        } catch {}
+      }
+    }
+  }
+  return null;
+}
+
+export function run(command, args, options = {}) {
+  const result = spawnSync(command, args, {
+    encoding: "utf8",
+    timeout: options.timeout ?? 20_000,
+    maxBuffer: options.maxBuffer ?? 10_000_000,
+    cwd: options.cwd,
+    env: options.env,
+    input: options.input,
+    stdio: options.stdio,
+  });
+  return {
+    ok: result.status === 0 && !result.error,
+    status: result.status,
+    stdout: String(result.stdout || ""),
+    stderr: String(result.stderr || ""),
+    error: result.error?.message,
+  };
+}
+
+export const AGENT_COMMANDS = {
+  "claude-code": "claude",
+  codex: "codex",
+  pi: "pi",
+  opencode: "opencode",
+};
+
+export function detectAgents() {
+  return Object.entries(AGENT_COMMANDS).map(([agent, command]) => ({
+    agent,
+    command,
+    path: resolveCommand(command),
+  }));
+}