@harness-control/runner 0.2.0 → 0.3.0

package/README.md

@@ -12,7 +12,11 @@ Choose which detected agents to enable in the terminal, then approve this comput
 
 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 endpoint-specific configuration under `~/.hcp-runner/connections/`. Use `--config <path>` for an existing installation, `--providers codex,claude` for explicit noninteractive selection, `--no-browser` to open the printed link manually, or `--pair` to replace revoked credentials. 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 custom integrations.
+`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.
+
+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

@@ -1,6 +1,8 @@
 export type ConnectOptions = {
     controlPlaneUrl: string;
     configPath: string;
+    connectionDirectory: string;
+    identityPath: string;
     providers?: string[];
     pair: boolean;
     openBrowser: boolean;

package/dist/connect.js

@@ -1,10 +1,11 @@
 import { createHash, randomUUID } from "node:crypto";
 import { existsSync, unlinkSync } from "node:fs";
-import { mkdir, open, rename, rm, writeFile } from "node:fs/promises";
+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";
@@ -13,7 +14,8 @@ export function parseConnectOptions(args, home = homedir()) {
         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 options = { controlPlaneUrl, configPath: join(home, ".hcp-runner", "connections", key, "runner.json"), pair: false, openBrowser: true };
+    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")
@@ -53,7 +55,7 @@ export async function openApprovalBrowser(value) {
         child.once("exit", code => resolveOpened(code === 0));
     });
 }
-async function saveConfig(path, config) {
+async function saveJson(path, config) {
     const temp = `${path}.${randomUUID()}.tmp`;
     try {
         await writeFile(temp, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600, flag: "wx" });
@@ -63,10 +65,29 @@ async function saveConfig(path, config) {
         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) {
-    const configPath = options.configPath;
-    await mkdir(dirname(configPath), { recursive: true, mode: 0o700 });
-    const lockPath = `${configPath}.lock`;
+    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);
@@ -86,12 +107,22 @@ export async function connectMachine(options, run) {
     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.");
             }
@@ -119,12 +150,13 @@ export async function connectMachine(options, run) {
                 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 identity = randomUUID();
-            config = RunnerConfigSchema.parse({ runner_id: `runner-${identity}`, host_id: hostname(), control_plane_url: options.controlPlaneUrl,
+            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 saveConfig(configPath, config);
+            await saveJson(configPath, config);
         }
+        await saveJson(locationPath, configPath);
         setupAbort.signal.throwIfAborted();
         const credential = await loadRunnerCredential(config);
         if (!credential || options.pair) {
@@ -138,7 +170,7 @@ export async function connectMachine(options, run) {
                 } });
             config.credentials_path ??= join(dirname(configPath), "credentials.json");
             await writeRunnerCredentials(config.credentials_path, pairing.credential);
-            await saveConfig(configPath, config);
+            await saveJson(configPath, config);
         }
         process.removeListener("SIGINT", cancelSetup);
         process.removeListener("SIGTERM", cancelSetup);

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.2.0",
+  "version": "0.3.0",
   "license": "Apache-2.0",
   "type": "module",
   "bin": {
@@ -45,7 +45,7 @@
   },
   "dependencies": {
     "@anthropic-ai/claude-agent-sdk": "0.3.267",
-    "@harness-control/protocol": "0.2.0",
+    "@harness-control/protocol": "0.3.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
     "ws": "^8.21.0",
     "zod": "^4.4.3"