@harness-control/runner 0.1.0 → 0.3.0

package/README.md

@@ -5,16 +5,18 @@ Local runner for Harness Control Protocol, with Codex, Claude Code, OpenCode, an
 ```sh
 npm install --global @harness-control/runner
 hcp-runner version
-hcp-runner pair https://your-app.example/hcp/runner --out runner.json
+hcp-runner connect https://your-app.example/hcp/runner
 ```
 
-Open the approval URL printed by the CLI. Once approved, configure `provider_instances`, `workspaces`, and optionally `workspace_management.allowed_roots` in `runner.json`, then:
+Choose which detected agents to enable in the terminal, then approve this computer in the browser that opens. HCP saves its configuration and starts the connection. Keep the terminal open; run the same command to reconnect. Add existing project folders from your app after connecting.
 
-```sh
-hcp-runner run --config runner.json
-```
+Use your application's actual runner URL. Guided setup allows folder registration under the local filesystem root (the home drive on Windows), but adds no folders automatically. Custom roots and provider settings can be changed in the printed configuration path. Existing settings are preserved on reconnect. Credentials stay in the local credentials file; do not commit it. The runner connects outward, so the local machine needs no inbound port.
+
+`connect` stores one installation ID in `~/.hcp-runner/identity.json` and endpoint-specific configuration under `~/.hcp-runner/connections/`. On upgrade it adopts the existing runner ID. The ID survives reconnects, package upgrades, and credential replacement; it is not a hardware fingerprint. Do not copy this directory to another computer.
+
+Use `--config <path>` to adopt an existing configuration on first setup. Its location is remembered, so the standard command reconnects it afterward. A second configuration for the same endpoint is rejected, and only one `connect` process can use that endpoint at a time. Use `--providers codex,claude` for explicit noninteractive selection, `--no-browser` to open the printed link manually, or `--pair` to replace revoked credentials with browser approval. Control planes should match the approved account and runner ID within their environment, rotate credentials on that existing machine record, and preserve its references. Hostnames are labels, not identity.
 
-Use your application's actual runner URL. Pairing does not automatically configure coding agents or authorize folders. Credentials stay in the local credentials file; do not commit it. The runner connects outward, so the local machine needs no inbound port.
+Run `codex login` or `claude auth login` locally if needed, then restart HCP. The lower-level `pair --out runner.json` and `run --config runner.json` commands remain available for integrations that own their runner identity and configuration lifecycle.
 
 For embedding, public modules are available at `/connection`, `/config`, `/harnesses`, `/mcp`, `/state`, and `/pairing`. Importing the package does not start a runner. See [configuration and examples](https://github.com/qazisaad/harness-control-protocol#runner-configuration), [workspace management](https://github.com/qazisaad/harness-control-protocol/blob/main/docs/workspace-management.md), and [provider support](https://github.com/qazisaad/harness-control-protocol/blob/main/docs/native-providers.md).
 

package/dist/connect.d.ts

@@ -0,0 +1,13 @@
+export type ConnectOptions = {
+    controlPlaneUrl: string;
+    configPath: string;
+    connectionDirectory: string;
+    identityPath: string;
+    providers?: string[];
+    pair: boolean;
+    openBrowser: boolean;
+};
+export declare function parseConnectOptions(args: string[], home?: string): ConnectOptions;
+export declare function openApprovalBrowser(value: string): Promise<boolean>;
+export declare function connectMachine(options: ConnectOptions, run: (path: string) => Promise<number>): Promise<number>;
+//# sourceMappingURL=connect.d.ts.map

package/dist/connect.js

@@ -0,0 +1,187 @@
+import { createHash, randomUUID } from "node:crypto";
+import { existsSync, unlinkSync } from "node:fs";
+import { link, mkdir, open, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir, hostname } from "node:os";
+import { dirname, join, parse, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { createInterface } from "node:readline/promises";
+import { z } from "zod";
+import { loadRunnerConfig, ProviderInstanceConfigSchema, RunnerConfigSchema } from "./config/index.js";
+import { createDefaultHarnessAdapterRegistry } from "./harnesses/adapters/registry.js";
+import { loadRunnerCredential, normalizeControlPlaneUrl, pairWithReferenceControlPlane, writeRunnerCredentials } from "./pairing/index.js";
+export function parseConnectOptions(args, home = homedir()) {
+    if (!args[0])
+        throw new Error("Usage: hcp-runner connect <control-plane-url> [--config path] [--providers codex,claude,opencode] [--pair] [--no-browser]");
+    const controlPlaneUrl = normalizeControlPlaneUrl(args[0]);
+    const key = createHash("sha256").update(controlPlaneUrl).digest("hex").slice(0, 16);
+    const connectionDirectory = join(home, ".hcp-runner", "connections", key);
+    const options = { controlPlaneUrl, connectionDirectory, identityPath: join(home, ".hcp-runner", "identity.json"), configPath: join(connectionDirectory, "runner.json"), pair: false, openBrowser: true };
+    for (let index = 1; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === "--pair")
+            options.pair = true;
+        else if (arg === "--no-browser")
+            options.openBrowser = false;
+        else if (arg === "--config" || arg === "--providers") {
+            const value = args[++index];
+            if (!value || value.startsWith("--"))
+                throw new Error(`${arg} requires a value.`);
+            if (arg === "--config")
+                options.configPath = resolve(value);
+            else
+                options.providers = parseProviders(value);
+        }
+        else
+            throw new Error(`Unknown connect argument: ${arg}`);
+    }
+    return options;
+}
+function parseProviders(value) {
+    const providers = value.split(",").map(item => item.trim()).filter(Boolean);
+    if (!providers.length || providers.some(item => !["codex", "claude", "opencode"].includes(item)) || new Set(providers).size !== providers.length) {
+        throw new Error("Choose one or more agents: codex,claude,opencode (comma-separated, without duplicates).");
+    }
+    return providers;
+}
+export async function openApprovalBrowser(value) {
+    const url = new URL(value);
+    if (!["http:", "https:"].includes(url.protocol) || url.username || url.password)
+        throw new Error("Invalid pairing approval URL.");
+    const command = process.platform === "darwin" ? "open" : process.platform === "win32" ? "rundll32" : "xdg-open";
+    const args = process.platform === "win32" ? ["url.dll,FileProtocolHandler", url.href] : [url.href];
+    return new Promise(resolveOpened => {
+        const child = spawn(command, args, { stdio: "ignore", timeout: 5_000 });
+        child.once("error", () => resolveOpened(false));
+        child.once("exit", code => resolveOpened(code === 0));
+    });
+}
+async function saveJson(path, config) {
+    const temp = `${path}.${randomUUID()}.tmp`;
+    try {
+        await writeFile(temp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: "wx" });
+        await rename(temp, path);
+    }
+    finally {
+        await rm(temp, { force: true });
+    }
+}
+async function installationIdentity(path, existingRunnerId) {
+    const schema = z.object({ runner_id: z.string().min(1).max(200) }).strict();
+    if (!existsSync(path)) {
+        const temporary = `${path}.${randomUUID()}.tmp`;
+        try {
+            await writeFile(temporary, JSON.stringify({ runner_id: existingRunnerId ?? `runner-${randomUUID()}` }), { mode: 0o600, flag: "wx" });
+            try {
+                await link(temporary, path);
+            }
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+            }
+        }
+        finally {
+            await rm(temporary, { force: true });
+        }
+    }
+    return schema.parse(JSON.parse(await readFile(path, "utf8"))).runner_id;
+}
+export async function connectMachine(options, run) {
+    await mkdir(options.connectionDirectory, { recursive: true, mode: 0o700 });
+    const lockPath = join(options.connectionDirectory, "runner.json.lock");
+    let lock;
+    try {
+        lock = await open(lockPath, "wx", 0o600);
+    }
+    catch (error) {
+        if (error.code !== "EEXIST")
+            throw error;
+        throw new Error(`This connection is already in use. Stop its runner first. If it crashed, remove ${lockPath} after confirming it is stopped.`);
+    }
+    await lock.writeFile(String(process.pid));
+    await lock.close();
+    const release = () => { if (existsSync(lockPath))
+        unlinkSync(lockPath); };
+    process.once("exit", release);
+    const setupAbort = new AbortController();
+    const cancelSetup = () => setupAbort.abort(new Error("Setup cancelled. Run the command again when ready."));
+    process.once("SIGINT", cancelSetup);
+    process.once("SIGTERM", cancelSetup);
+    try {
+        const locationPath = join(options.connectionDirectory, "config-path.json");
+        const defaultPath = join(options.connectionDirectory, "runner.json");
+        const savedPath = existsSync(locationPath) ? z.string().min(1).parse(JSON.parse(await readFile(locationPath, "utf8"))) : existsSync(defaultPath) ? defaultPath : undefined;
+        if (savedPath && options.configPath !== defaultPath && options.configPath !== savedPath) {
+            throw new Error(`This machine already has a configuration for this server: ${savedPath}. Run the standard connect command to reuse it.`);
+        }
+        const configPath = savedPath ?? options.configPath;
+        await mkdir(dirname(configPath), { recursive: true, mode: 0o700 });
+        const existing = existsSync(configPath);
+        let config;
+        if (existing) {
+            config = await loadRunnerConfig(configPath);
+            if (normalizeControlPlaneUrl(config.control_plane_url) !== options.controlPlaneUrl)
+                throw new Error("This config belongs to another control plane. Use its URL or a different --config path.");
+            if (await installationIdentity(options.identityPath, config.runner_id) !== config.runner_id)
+                throw new Error("This configuration belongs to a different HCP installation. Use this installation’s saved configuration; do not copy machine credentials between installations.");
+            if (options.providers && options.providers.slice().sort().join(",") !== config.provider_instances.filter(provider => provider.enabled).map(provider => provider.driver_kind).sort().join(",")) {
+                throw new Error("This connection already has different agent settings. Edit its config to change them; reconnect preserves existing settings.");
+            }
+        }
+        else {
+            const providers = ["codex", "claude", "opencode"].map(driver => ProviderInstanceConfigSchema.parse({ id: `${driver}-local`, driver_kind: driver, display_name: driver === "claude" ? "Claude Code" : driver === "codex" ? "Codex" : "OpenCode" }));
+            console.log("Checking installed coding agents…");
+            const statuses = await createDefaultHarnessAdapterRegistry().probeProviders(providers);
+            for (const status of statuses)
+                console.log(`  ${status.driver_kind}: ${!status.installed ? "not installed" : status.authStatus === "unauthenticated" ? "sign in required" : status.status ?? "unknown"}${status.message ? ` — ${status.message}` : ""}`);
+            const installed = statuses.filter(status => status.installed).map(status => status.driver_kind);
+            let selected = options.providers;
+            if (!selected && process.stdin.isTTY && process.stdout.isTTY && installed.length) {
+                const prompt = createInterface({ input: process.stdin, output: process.stdout });
+                prompt.once("SIGINT", cancelSetup);
+                try {
+                    selected = parseProviders((await prompt.question(`Agents to enable [${installed.join(",")}]: `, { signal: setupAbort.signal })).trim() || installed.join(","));
+                }
+                finally {
+                    prompt.close();
+                }
+            }
+            selected ??= installed;
+            if (!selected.length)
+                throw new Error("No coding agents found. Install and sign in to an agent, then run this command again.");
+            if (selected.some(driver => !installed.includes(driver)))
+                throw new Error("A selected agent is not installed. Install it before connecting.");
+            const runnerId = await installationIdentity(options.identityPath);
+            config = RunnerConfigSchema.parse({ runner_id: runnerId, host_id: hostname(), control_plane_url: options.controlPlaneUrl,
+                credentials_path: join(dirname(configPath), "credentials.json"), state_path: join(dirname(configPath), "state.json"),
+                workspaces: [], workspace_management: { allowed_roots: [parse(homedir()).root] }, provider_instances: providers.filter(provider => selected.includes(provider.driver_kind)) });
+            await saveJson(configPath, config);
+        }
+        await saveJson(locationPath, configPath);
+        setupAbort.signal.throwIfAborted();
+        const credential = await loadRunnerCredential(config);
+        if (!credential || options.pair) {
+            console.log("Approve this computer in your browser. You can then register existing folders in P2A; no folder is added automatically.");
+            const pairing = await pairWithReferenceControlPlane({ controlPlaneUrl: config.control_plane_url, runnerId: config.runner_id, hostId: config.host_id ?? config.runner_id, signal: setupAbort.signal,
+                onPairingCode: async (code) => {
+                    console.log(`Approval link: ${code.pairing_url}\nFallback pairing code: ${code.pairing_code}`);
+                    if (options.openBrowser && !await openApprovalBrowser(code.pairing_url))
+                        console.log("Could not open a browser. Open the approval link yourself.");
+                    console.log("Waiting for approval…");
+                } });
+            config.credentials_path ??= join(dirname(configPath), "credentials.json");
+            await writeRunnerCredentials(config.credentials_path, pairing.credential);
+            await saveJson(configPath, config);
+        }
+        process.removeListener("SIGINT", cancelSetup);
+        process.removeListener("SIGTERM", cancelSetup);
+        console.log(`Configuration: ${configPath}\nKeep this terminal open. Press Ctrl+C to disconnect; run the same command to reconnect.`);
+        return await run(configPath);
+    }
+    finally {
+        process.removeListener("SIGINT", cancelSetup);
+        process.removeListener("SIGTERM", cancelSetup);
+        process.removeListener("exit", release);
+        release();
+    }
+}
+//# sourceMappingURL=connect.js.map

package/dist/index.js

@@ -9,12 +9,22 @@ import { loadRunnerConfig } from "./config/index.js";
 import { RunnerConnection } from "./connection/index.js";
 import { HarnessSessionManager } from "./harnesses/index.js";
 import { consoleLogger } from "./logs/index.js";
+import { connectMachine, parseConnectOptions } from "./connect.js";
 import { createDevelopmentHmacProofSigner } from "./mcp/McpAttachmentClient.js";
 import { JsonRunnerStateStore, defaultRunnerStatePath } from "./state/index.js";
 import { defaultCredentialsPath, loadRunnerCredential, normalizeControlPlaneUrl, pairWithReferenceControlPlane, requestConnectionToken, writeRunnerCredentials, } from "./pairing/index.js";
 const RUNNER_VERSION = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 export async function main(argv = process.argv.slice(2)) {
     const command = argv[0];
+    if (command === "connect") {
+        try {
+            return await connectMachine(parseConnectOptions(argv.slice(1)), path => main(["run", "--config", path]));
+        }
+        catch (error) {
+            console.error(error instanceof Error ? error.message : String(error));
+            return 1;
+        }
+    }
     if (command === "version") {
         console.log(`hcp-runner ${RUNNER_VERSION} (${HCP_VERSION})`);
         return 0;
@@ -119,7 +129,7 @@ export async function main(argv = process.argv.slice(2)) {
         });
         return new Promise(() => undefined);
     }
-    console.log("Usage: hcp-runner <version|pair|run>");
+    console.log("Usage: hcp-runner <version|connect|pair|run>");
     return command ? 1 : 0;
 }
 function parseConfigPath(args) {

package/dist/workspaces/index.d.ts

@@ -8,6 +8,9 @@ export declare class WorkspaceManager {
     constructor(config: RunnerConfig, configPath: string | undefined, sessions: Pick<HarnessSessionManager, "updateWorkspaceConfiguration">);
     snapshot(): HcpWorkspaceManagement;
     execute(requestId: string, request: HcpWorkspacesRequestPayload): Promise<HcpWorkspacesResultPayload>;
+    private canonicalRoots;
+    private allowedDirectory;
+    private browse;
     private change;
 }
 //# sourceMappingURL=index.d.ts.map

package/dist/workspaces/index.js

@@ -1,6 +1,7 @@
 import { createHash, randomUUID } from "node:crypto";
-import { open, readFile, realpath, rename, rm, stat } from "node:fs/promises";
-import { isAbsolute, relative, sep } from "node:path";
+import { open, readdir, readFile, realpath, rename, rm, stat } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, sep } from "node:path";
+import { homedir } from "node:os";
 import { isDeepStrictEqual } from "node:util";
 import { z } from "zod";
 import { RunnerConfigSchema } from "../config/index.js";
@@ -17,25 +18,88 @@ export class WorkspaceManager {
         return {
             revision: this.config.workspace_revision ?? createHash("sha256").update(JSON.stringify(this.config.workspaces)).digest("hex"),
             allowed_roots: this.configPath ? this.config.workspace_management?.allowed_roots ?? [] : [],
+            directory_browsing: true,
         };
     }
     async execute(requestId, request) {
         let outcome;
         try {
-            if (request.operation.kind === "list") {
-                if (Date.parse(request.expires_at) <= Date.now())
-                    throw new Error("Request expired. Refresh workspaces.");
+            if (request.operation.kind === "browse") {
+                outcome = await this.browse(request);
             }
             else {
-                await this.sessions.updateWorkspaceConfiguration(() => this.change(request));
+                if (request.operation.kind === "list") {
+                    if (Date.parse(request.expires_at) <= Date.now())
+                        throw new Error("Request expired. Refresh workspaces.");
+                }
+                else {
+                    await this.sessions.updateWorkspaceConfiguration(() => this.change(request));
+                }
+                outcome = { kind: "success" };
             }
-            outcome = { kind: "success" };
         }
         catch (error) {
             outcome = { kind: "error", message: error instanceof Error ? error.message.slice(0, 1000) : "Workspace update failed." };
         }
         return { request_id: requestId, outcome, management: this.snapshot(), workspaces: this.config.workspaces.map(workspace => ({ ...workspace })) };
     }
+    async canonicalRoots() {
+        const roots = this.snapshot().allowed_roots;
+        if (roots.length === 0)
+            throw new Error("Folder browsing is disabled. Configure workspace_management.allowed_roots locally, then restart the runner.");
+        return Promise.all(roots.map(root => realpath(root)));
+    }
+    async allowedDirectory(path, roots) {
+        if (!isAbsolute(path))
+            throw new Error("Use an absolute folder path on this machine.");
+        const canonical = await realpath(path);
+        if (!roots.some(root => contained(root, canonical)))
+            throw new Error("The folder is outside this machine’s allowed roots.");
+        if (!(await stat(canonical)).isDirectory())
+            throw new Error("Choose an existing folder.");
+        return canonical;
+    }
+    async browse(request) {
+        if (request.operation.kind !== "browse")
+            throw new Error("Expected a folder browsing request.");
+        const operation = request.operation;
+        if (Date.parse(request.expires_at) <= Date.now())
+            throw new Error("Folder request expired. Try again.");
+        const roots = await this.canonicalRoots();
+        const home = homedir();
+        const path = await this.allowedDirectory(operation.path ?? (roots.some(root => contained(root, home)) ? home : roots[0]), roots);
+        const candidates = (await readdir(path, { withFileTypes: true }))
+            .filter(entry => (entry.isDirectory() || entry.isSymbolicLink()) && (!operation.cursor || entry.name > operation.cursor))
+            .sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+        const entries = [];
+        let pageBytes = 0;
+        let hasMore = false;
+        for (const entry of candidates) {
+            if (Date.parse(request.expires_at) <= Date.now())
+                throw new Error("Folder request expired. Try again.");
+            const candidate = join(path, entry.name);
+            try {
+                const canonical = await realpath(candidate);
+                if (roots.some(root => contained(root, canonical)) && (await stat(canonical)).isDirectory()) {
+                    const item = { name: entry.name, path: canonical };
+                    const bytes = Buffer.byteLength(JSON.stringify(item));
+                    if (entries.length === 200 || pageBytes + bytes > 64 * 1024) {
+                        hasMore = true;
+                        break;
+                    }
+                    entries.push(item);
+                    pageBytes += bytes;
+                }
+            }
+            catch (error) {
+                if (!(error instanceof Error && "code" in error && ["ENOENT", "EACCES", "EPERM", "ELOOP"].includes(String(error.code))))
+                    throw error;
+            }
+        }
+        const parent = dirname(path);
+        return { kind: "directory", path, ...(parent !== path && roots.some(root => contained(root, parent)) ? { parent } : {}),
+            entries, ...(hasMore ? { next_cursor: entries.at(-1).name } : {}) };
+    }
     async change(request) {
         if (Date.parse(request.expires_at) <= Date.now())
             throw new Error("Request expired. Refresh workspaces.");
@@ -48,14 +112,7 @@ export class WorkspaceManager {
         const operation = request.operation;
         let workspaces = this.config.workspaces.map(workspace => ({ ...workspace }));
         if (operation.kind === "add") {
-            if (!isAbsolute(operation.path))
-                throw new Error("Use an absolute folder path on this machine.");
-            const path = await realpath(operation.path);
-            if (!(await stat(path)).isDirectory())
-                throw new Error("The workspace must be an existing folder.");
-            const canonicalRoots = await Promise.all(roots.map(root => realpath(root)));
-            if (!canonicalRoots.some(root => contained(root, path)))
-                throw new Error("The folder is outside this machine’s allowed roots.");
+            const path = await this.allowedDirectory(operation.path, await this.canonicalRoots());
             const existingPaths = await Promise.all(workspaces.map(async (workspace) => {
                 try {
                     return await realpath(workspace.path);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@harness-control/runner",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
@@ -41,11 +41,11 @@
   "scripts": {
     "build": "tsc -b",
     "check": "tsc -b --pretty false",
-    "test": "node --import tsx --test --test-concurrency=1 src/**/*.test.ts"
+    "test": "node --import tsx --test --test-concurrency=1 'src/**/*.test.ts'"
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.267",
-    "@harness-control/protocol": "0.1.0",
+    "@harness-control/protocol": "0.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ws": "^8.21.0",
     "zod": "^4.4.3"