agent-hitch 0.1.0 → 0.2.0

package/dist/src/harbor-backend.js

@@ -0,0 +1,280 @@
+import { spawn } from "node:child_process";
+import { createWriteStream } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { HitchError, invalidInput } from "./errors.js";
+import { atomicWriteJSON, ensureDir, readJSON } from "./fs.js";
+import { consumeLines } from "./line-stream.js";
+import { terminateProcess } from "./process.js";
+import { detectVersion, fingerprintExecutable } from "./registry.js";
+import { HARBOR_CREDENTIAL_ENV, locateHarbor } from "./eval-tools.js";
+import { packageRoot } from "./package-root.js";
+const BRIDGE_DIRECTORY = path.join(packageRoot(), "integrations", "harbor");
+export async function runHarborBackend({ evalDirectory, request, root, resolvedRevision, runtimeDirectory, runtimeId, env = process.env, harborExecutable, signal, emit = () => { }, }) {
+    const backendDirectory = await ensureDir(path.join(evalDirectory, "harbor"));
+    const executable = await discoverHarbor(harborExecutable, root, env);
+    const version = await detectVersion(executable, ["--version"]);
+    const identity = await fingerprintExecutable(executable);
+    const jobName = "job";
+    const configPath = path.join(backendDirectory, "job.json");
+    const jobDirectory = path.join(backendDirectory, jobName);
+    const resultPath = path.join(jobDirectory, "result.json");
+    const config = await buildHarborJobConfig({
+        request,
+        resolvedRevision,
+        runtimeDirectory,
+        runtimeId,
+        backendDirectory,
+        jobName,
+        env,
+    });
+    await atomicWriteJSON(configPath, config);
+    emit({ type: "eval.backend.started", backend: "harbor", executable, version: version || null });
+    const invocation = await invokeHarbor(executable, ["run", "--config", configPath, "--yes"], {
+        cwd: evalDirectory,
+        env: withBridgePythonPath(env),
+        stdoutPath: path.join(backendDirectory, "stdout.log"),
+        stderrPath: path.join(backendDirectory, "stderr.log"),
+        ...(signal ? { signal } : {}),
+        emit,
+    });
+    const jobResult = await readJSON(resultPath, null);
+    const rawResult = jobResult ? await attachTrialResults(jobDirectory, jobResult) : null;
+    emit({
+        type: "eval.backend.completed",
+        backend: "harbor",
+        process_exit_code: invocation.code,
+        signal: invocation.signal,
+        result_available: rawResult !== null,
+    });
+    return {
+        backend: {
+            name: "harbor",
+            executable,
+            version: version || null,
+            identity,
+            config_path: configPath,
+            result_path: rawResult ? resultPath : null,
+            stdout_path: path.join(backendDirectory, "stdout.log"),
+            stderr_path: path.join(backendDirectory, "stderr.log"),
+            process_exit_code: invocation.code,
+            signal: invocation.signal,
+        },
+        rawResult,
+        summary: rawResult ? normalizeHarborResult(rawResult) : null,
+    };
+}
+async function attachTrialResults(jobDirectory, jobResult) {
+    if (Array.isArray(jobResult.trial_results))
+        return jobResult;
+    let entries;
+    try {
+        entries = await readdir(jobDirectory, { withFileTypes: true });
+    }
+    catch (error) {
+        if (error?.code === "ENOENT")
+            return jobResult;
+        throw error;
+    }
+    const trialResults = [];
+    for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+        if (!entry.isDirectory())
+            continue;
+        const trial = await readJSON(path.join(jobDirectory, entry.name, "result.json"), null);
+        if (trial?.trial_name && trial?.task_name)
+            trialResults.push(trial);
+    }
+    return { ...jobResult, trial_results: trialResults };
+}
+export async function buildHarborJobConfig({ request, resolvedRevision, runtimeDirectory, runtimeId, backendDirectory, jobName = "job", env = process.env, }) {
+    const timeoutSeconds = request.timeout_ms > 0 ? Math.ceil(request.timeout_ms / 1_000) : null;
+    const setupTimeoutSeconds = request.setup_timeout_ms > 0 ? Math.ceil(request.setup_timeout_ms / 1_000) : null;
+    const agent = {
+        import_path: "hitch_harbor_agent:HitchHarborAgent",
+        model_name: request.model || null,
+        kwargs: {
+            candidate_id: "candidate-1",
+            harness_ref: lockedHarnessRef(resolvedRevision),
+            revision_identity: resolvedRevision.identity,
+            // The bridge consumes the shared compiled runtime cache. The local
+            // absolute cache path is diagnostic machine-local state, not identity
+            // (spec §4.2); `runtime_id` records the exact execution payload.
+            hitch_runtime_dir: runtimeDirectory,
+            ...(runtimeId ? { controller_runtime_id: runtimeId } : {}),
+            hitch_timeout_ms: request.timeout_ms,
+            agent_args: request.agent_args,
+            workdir: "/app",
+        },
+        env: credentialEnvironment(request.pass_env, env),
+        include_logs: ["hitch-*"],
+    };
+    if (timeoutSeconds !== null)
+        agent.override_timeout_sec = timeoutSeconds + 30;
+    if (setupTimeoutSeconds !== null)
+        agent.override_setup_timeout_sec = setupTimeoutSeconds;
+    return compact({
+        job_name: jobName,
+        jobs_dir: backendDirectory,
+        n_attempts: request.attempts,
+        n_concurrent_trials: request.max_concurrent,
+        environment: { type: "docker", delete: true },
+        agents: [agent],
+        datasets: [await datasetConfig(request.dataset)],
+        tasks: [],
+    });
+}
+export function lockedHarnessRef(resolvedRevision) {
+    if (resolvedRevision?.revision?.type === "version" && resolvedRevision.revision.version) {
+        return `${resolvedRevision.harness_id}@version:${resolvedRevision.revision.version}`;
+    }
+    if (resolvedRevision?.revision?.type === "commit" && resolvedRevision.revision.commit) {
+        return `${resolvedRevision.harness_id}@commit:${resolvedRevision.revision.commit}`;
+    }
+    throw invalidInput("Harbor eval requires a resolved exact version or commit");
+}
+export function normalizeHarborResult(raw) {
+    const trials = Array.isArray(raw?.trial_results) ? raw.trial_results : [];
+    const rewardValues = new Map();
+    const normalizedTrials = trials.map((trial) => {
+        const verifier = (trial?.verifier_result || {});
+        const rewards = (verifier.rewards || {});
+        for (const [name, value] of Object.entries(rewards)) {
+            if (typeof value !== "number" || !Number.isFinite(value))
+                continue;
+            const values = rewardValues.get(name) || [];
+            values.push(value);
+            rewardValues.set(name, values);
+        }
+        return {
+            task_name: trial?.task_name || null,
+            trial_name: trial?.trial_name || null,
+            status: trial?.exception_info ? "errored" : "completed",
+            rewards,
+            exception: trial?.exception_info || null,
+        };
+    });
+    const rewards = Object.fromEntries([...rewardValues.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([name, values]) => [name, {
+            count: values.length,
+            mean: values.reduce((sum, value) => sum + value, 0) / values.length,
+            min: Math.min(...values),
+            max: Math.max(...values),
+        }]));
+    const rewardEntries = Object.entries(rewards);
+    const primary = rewards.reward || rewardEntries[0]?.[1] || null;
+    const stats = (raw?.stats || {});
+    return {
+        n_trials: raw?.n_total_trials ?? trials.length,
+        n_completed: stats.n_completed_trials ?? normalizedTrials.filter((trial) => trial.status === "completed").length,
+        n_errored: stats.n_errored_trials ?? normalizedTrials.filter((trial) => trial.status === "errored").length,
+        n_cancelled: stats.n_cancelled_trials ?? 0,
+        primary_reward: primary?.mean ?? null,
+        rewards,
+        trials: normalizedTrials,
+    };
+}
+async function discoverHarbor(explicit, root, env) {
+    const located = await locateHarbor({ root, explicit, env });
+    if (!located.executable) {
+        throw new HitchError(`Harbor executable not found: ${located.requested}`, {
+            code: "harbor_unavailable",
+            exitCode: 3,
+        });
+    }
+    return located.executable;
+}
+async function datasetConfig(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw invalidInput("dataset must be a non-empty string");
+    const raw = value.trim();
+    const localPath = path.resolve(raw);
+    try {
+        if ((await stat(localPath)).isDirectory())
+            return { path: localPath };
+    }
+    catch (error) {
+        if (error?.code !== "ENOENT")
+            throw error;
+    }
+    const separator = raw.lastIndexOf("@");
+    const name = separator > 0 ? raw.slice(0, separator) : raw;
+    const version = separator > 0 ? raw.slice(separator + 1) : "";
+    if (!name)
+        throw invalidInput(`invalid Harbor dataset: ${value}`);
+    return name.includes("/")
+        ? { name, ref: version || "latest" }
+        : compact({ name, version: version || undefined });
+}
+function credentialEnvironment(explicitNames, env) {
+    const names = new Set(HARBOR_CREDENTIAL_ENV.filter((name) => env[name] !== undefined));
+    for (const name of explicitNames || []) {
+        if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(name))
+            throw invalidInput(`invalid environment variable name: ${name}`);
+        if (env[name] === undefined)
+            throw invalidInput(`environment variable is not set: ${name}`);
+        names.add(name);
+    }
+    return Object.fromEntries([...names].sort().map((name) => [name, `\${${name}}`]));
+}
+function withBridgePythonPath(env) {
+    return {
+        ...env,
+        PYTHONPATH: [BRIDGE_DIRECTORY, env.PYTHONPATH].filter(Boolean).join(path.delimiter),
+    };
+}
+function invokeHarbor(executable, args, { cwd, env, stdoutPath, stderrPath, signal, emit }) {
+    return new Promise((resolve, reject) => {
+        const stdout = createWriteStream(stdoutPath, { flags: "w", mode: 0o600 });
+        const stderr = createWriteStream(stderrPath, { flags: "w", mode: 0o600 });
+        const child = spawn(executable, args, {
+            cwd,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+            detached: process.platform !== "win32",
+            windowsHide: true,
+        });
+        child.stdout.pipe(stdout);
+        child.stderr.pipe(stderr);
+        consumeLines(child.stdout, (line) => emit({ type: "eval.backend.output", stream: "stdout", text: line }));
+        consumeLines(child.stderr, (line) => emit({ type: "eval.backend.output", stream: "stderr", text: line }));
+        let settled = false;
+        const abort = () => terminateProcess(child).catch(() => { });
+        signal?.addEventListener("abort", abort, { once: true });
+        child.once("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", abort);
+            stdout.destroy();
+            stderr.destroy();
+            reject(new HitchError(`failed to launch Harbor: ${error.message}`, {
+                code: "harbor_launch_failed",
+                exitCode: 6,
+                cause: error,
+            }));
+        });
+        child.once("close", (code, processSignal) => {
+            if (settled)
+                return;
+            settled = true;
+            signal?.removeEventListener("abort", abort);
+            Promise.all([closeWriteStream(stdout), closeWriteStream(stderr)])
+                .then(() => resolve({ code, signal: processSignal }))
+                .catch(reject);
+        });
+        if (signal?.aborted)
+            abort();
+    });
+}
+function closeWriteStream(stream) {
+    return new Promise((resolve, reject) => {
+        if (stream.closed)
+            return resolve();
+        stream.once("error", reject);
+        stream.once("close", resolve);
+        stream.end();
+    });
+}
+function compact(value) {
+    return Object.fromEntries(Object.entries(value).filter(([, entry]) => entry !== undefined && entry !== null));
+}
+//# sourceMappingURL=harbor-backend.js.map

package/dist/src/harbor-backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harbor-backend.js","sourceRoot":"","sources":["../../src/harbor-backend.ts"],"names":[],"mappings":"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"}

package/dist/src/harness-reference.js

@@ -0,0 +1,83 @@
+import { fileURLToPath, pathToFileURL } from "node:url";
+import path from "node:path";
+import { invalidInput } from "./errors.js";
+const VERSION_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const COMMIT_PATTERN = /^[0-9a-fA-F]{7,64}$/;
+const HARNESS_ID_PATTERN = /^[a-z][a-z0-9-]*$/;
+export function parseHarnessReference(value) {
+    if (typeof value !== "string" || !value.trim())
+        throw invalidInput("harness reference must be a non-empty string");
+    const raw = value.trim();
+    const separator = raw.indexOf("@");
+    const harnessId = separator < 0 ? raw : raw.slice(0, separator);
+    const revision = separator < 0 ? "installed" : raw.slice(separator + 1);
+    if (!HARNESS_ID_PATTERN.test(harnessId))
+        throw invalidInput(`invalid harness name: ${harnessId || raw}`);
+    if (!revision)
+        throw invalidInput(`harness reference is missing a selector: ${raw}`);
+    if (revision === "installed") {
+        return canonicalReference(raw, harnessId, { type: "installed" });
+    }
+    if (revision.startsWith("version:")) {
+        const version = revision.slice("version:".length);
+        if (!VERSION_PATTERN.test(version)) {
+            throw invalidInput(`version selector must be an exact semantic version: ${version || "(empty)"}`);
+        }
+        return canonicalReference(raw, harnessId, { type: "version", value: version });
+    }
+    if (revision.startsWith("commit:")) {
+        const commit = revision.slice("commit:".length);
+        assertCommit(commit);
+        return canonicalReference(raw, harnessId, { type: "commit", value: commit.toLowerCase() });
+    }
+    if (revision.startsWith("git+")) {
+        const hash = revision.lastIndexOf("#");
+        if (hash < 0)
+            throw invalidInput("explicit Git references require #<commit>");
+        const sourceValue = revision.slice("git+".length, hash);
+        const commit = revision.slice(hash + 1);
+        assertCommit(commit);
+        let source;
+        try {
+            source = new URL(sourceValue);
+        }
+        catch (error) {
+            throw invalidInput(`invalid Git source URL: ${sourceValue}`, { cause: error });
+        }
+        if (source.protocol !== "file:") {
+            throw invalidInput("explicit Git sources are limited to file:// URLs; use the registered source for remote commits");
+        }
+        const localPath = path.resolve(fileURLToPath(source));
+        const sourceUrl = pathToFileURL(localPath).href;
+        return canonicalReference(raw, harnessId, {
+            type: "commit",
+            value: commit.toLowerCase(),
+            source: { type: "git", url: sourceUrl, local_path: localPath, explicit: true },
+        });
+    }
+    throw invalidInput(`unsupported harness selector in ${raw}; use installed, version:<exact>, or commit:<sha>`);
+}
+function canonicalReference(raw, harnessId, selector) {
+    let suffix;
+    if (selector.type === "installed") {
+        suffix = "installed";
+    }
+    else if (selector.type === "commit" && selector.source) {
+        suffix = `git+${selector.source.url}#${selector.value}`;
+    }
+    else {
+        suffix = `${selector.type}:${selector.value}`;
+    }
+    return {
+        raw,
+        canonical: `${harnessId}@${suffix}`,
+        harness_id: harnessId,
+        selector,
+    };
+}
+function assertCommit(value) {
+    if (!COMMIT_PATTERN.test(value || "")) {
+        throw invalidInput(`commit selector must be a 7-64 character hexadecimal ID: ${value || "(empty)"}`);
+    }
+}
+//# sourceMappingURL=harness-reference.js.map

package/dist/src/harness-reference.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"harness-reference.js","sourceRoot":"","sources":["../../src/harness-reference.ts"],"names":[],"mappings":"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"}

package/dist/src/line-stream.js

@@ -0,0 +1,20 @@
+export function consumeLines(stream, onLine) {
+    let buffer = "";
+    stream.setEncoding("utf8");
+    stream.on("data", (chunk) => {
+        buffer += chunk;
+        for (;;) {
+            const newline = buffer.indexOf("\n");
+            if (newline < 0)
+                break;
+            const line = buffer.slice(0, newline).replace(/\r$/, "");
+            buffer = buffer.slice(newline + 1);
+            onLine(line);
+        }
+    });
+    stream.on("end", () => {
+        if (buffer.length > 0)
+            onLine(buffer.replace(/\r$/, ""));
+    });
+}
+//# sourceMappingURL=line-stream.js.map

package/dist/src/line-stream.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"line-stream.js","sourceRoot":"","sources":["../../src/line-stream.ts"],"names":[],"mappings":"AAEA,MAAM,UAAU,YAAY,CAAC,MAAgB,EAAE,MAA8B;IAC3E,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;IAC3B,MAAM,CAAC,EAAE,CAAC,MAAM,EAAE,CAAC,KAAsB,EAAE,EAAE;QAC3C,MAAM,IAAI,KAAK,CAAC;QAChB,SAAS,CAAC;YACR,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC;YACrC,IAAI,OAAO,GAAG,CAAC;gBAAE,MAAM;YACvB,MAAM,IAAI,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC,EAAE,OAAO,CAAC,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC;YACzD,MAAM,GAAG,MAAM,CAAC,KAAK,CAAC,OAAO,GAAG,CAAC,CAAC,CAAC;YACnC,MAAM,CAAC,IAAI,CAAC,CAAC;QACf,CAAC;IACH,CAAC,CAAC,CAAC;IACH,MAAM,CAAC,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE;QACpB,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC;YAAE,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,CAAC;IAC3D,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/locks.js

@@ -0,0 +1,38 @@
+import { randomBytes } from "node:crypto";
+import { open, readFile, rm } from "node:fs/promises";
+// Serializes stale-lock reclamation so an observation about an old owner can
+// never be used to remove a lock that a new owner has just acquired.
+export async function reclaimStaleLock(file, isStale) {
+    const guard = `${file}.reclaim`;
+    const owner = randomBytes(12).toString("hex");
+    let handle;
+    try {
+        handle = await open(guard, "wx", 0o600);
+    }
+    catch (error) {
+        if (error?.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    try {
+        await handle.writeFile(`${JSON.stringify({ owner, pid: process.pid, created_at: new Date().toISOString() })}\n`);
+        await handle.sync();
+        if (!await isStale(file))
+            return false;
+        await rm(file, { force: true });
+        return true;
+    }
+    finally {
+        await handle.close().catch(() => { });
+        let current;
+        try {
+            current = JSON.parse(await readFile(guard, "utf8"));
+        }
+        catch {
+            current = null;
+        }
+        if (current?.owner === owner)
+            await rm(guard, { force: true });
+    }
+}
+//# sourceMappingURL=locks.js.map

package/dist/src/locks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"locks.js","sourceRoot":"","sources":["../../src/locks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,EAAE,EAAE,MAAM,kBAAkB,CAAC;AAEtD,6EAA6E;AAC7E,qEAAqE;AACrE,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,IAAY,EAAE,OAA2C;IAC9F,MAAM,KAAK,GAAG,GAAG,IAAI,UAAU,CAAC;IAChC,MAAM,KAAK,GAAG,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;IAC9C,IAAI,MAAM,CAAC;IACX,IAAI,CAAC;QACH,MAAM,GAAG,MAAM,IAAI,CAAC,KAAK,EAAE,IAAI,EAAE,KAAK,CAAC,CAAC;IAC1C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,EAAE,IAAI,KAAK,QAAQ;YAAE,OAAO,KAAK,CAAC;QACtE,MAAM,KAAK,CAAC;IACd,CAAC;IAED,IAAI,CAAC;QACH,MAAM,MAAM,CAAC,SAAS,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,UAAU,EAAE,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;QACjH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;QACpB,IAAI,CAAC,MAAM,OAAO,CAAC,IAAI,CAAC;YAAE,OAAO,KAAK,CAAC;QACvC,MAAM,EAAE,CAAC,IAAI,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;QAChC,OAAO,IAAI,CAAC;IACd,CAAC;YAAS,CAAC;QACT,MAAM,MAAM,CAAC,KAAK,EAAE,CAAC,KAAK,CAAC,GAAG,EAAE,GAAE,CAAC,CAAC,CAAC;QACrC,IAAI,OAAmC,CAAC;QACxC,IAAI,CAAC;YACH,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,MAAM,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,CAAwB,CAAC;QAC7E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,GAAG,IAAI,CAAC;QACjB,CAAC;QACD,IAAI,OAAO,EAAE,KAAK,KAAK,KAAK;YAAE,MAAM,EAAE,CAAC,KAAK,EAAE,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC;IACjE,CAAC;AACH,CAAC"}

package/dist/src/package-root.js

@@ -0,0 +1,40 @@
+/**
+ * Resolve the Hitch package root and version from the module location,
+ * tolerating both the source layout (`src/cli.ts`) and the compiled layout
+ * (`dist/src/cli.js`). Walks up until a `package.json` with a `name` is found.
+ */
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+let cachedRoot;
+let cachedVersion;
+export function packageRoot() {
+    if (cachedRoot)
+        return cachedRoot;
+    let directory = dirname(fileURLToPath(import.meta.url));
+    for (;;) {
+        const candidate = join(directory, "package.json");
+        try {
+            const metadata = JSON.parse(readFileSync(candidate, "utf8"));
+            if (metadata.name === "agent-hitch") {
+                cachedRoot = directory;
+                return directory;
+            }
+        }
+        catch {
+            // Keep walking up.
+        }
+        const parent = dirname(directory);
+        if (parent === directory)
+            throw new Error("could not locate the Hitch package root");
+        directory = parent;
+    }
+}
+export function packageVersion() {
+    if (cachedVersion)
+        return cachedVersion;
+    const metadata = JSON.parse(readFileSync(join(packageRoot(), "package.json"), "utf8"));
+    cachedVersion = metadata.version;
+    return cachedVersion;
+}
+//# sourceMappingURL=package-root.js.map

package/dist/src/package-root.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package-root.js","sourceRoot":"","sources":["../../src/package-root.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAC1C,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAC;AAEzC,IAAI,UAA8B,CAAC;AACnC,IAAI,aAAiC,CAAC;AAEtC,MAAM,UAAU,WAAW;IACzB,IAAI,UAAU;QAAE,OAAO,UAAU,CAAC;IAClC,IAAI,SAAS,GAAG,OAAO,CAAC,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC;IACxD,SAAS,CAAC;QACR,MAAM,SAAS,GAAG,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC;QAClD,IAAI,CAAC;YACH,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,SAAS,EAAE,MAAM,CAAC,CAAuB,CAAC;YACnF,IAAI,QAAQ,CAAC,IAAI,KAAK,aAAa,EAAE,CAAC;gBACpC,UAAU,GAAG,SAAS,CAAC;gBACvB,OAAO,SAAS,CAAC;YACnB,CAAC;QACH,CAAC;QAAC,MAAM,CAAC;YACP,mBAAmB;QACrB,CAAC;QACD,MAAM,MAAM,GAAG,OAAO,CAAC,SAAS,CAAC,CAAC;QAClC,IAAI,MAAM,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,yCAAyC,CAAC,CAAC;QACrF,SAAS,GAAG,MAAM,CAAC;IACrB,CAAC;AACH,CAAC;AAED,MAAM,UAAU,cAAc;IAC5B,IAAI,aAAa;QAAE,OAAO,aAAa,CAAC;IACxC,MAAM,QAAQ,GAAG,IAAI,CAAC,KAAK,CAAC,YAAY,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,cAAc,CAAC,EAAE,MAAM,CAAC,CAAwB,CAAC;IAC9G,aAAa,GAAG,QAAQ,CAAC,OAAO,CAAC;IACjC,OAAO,aAAa,CAAC;AACvB,CAAC"}

package/dist/src/process.js

@@ -0,0 +1,50 @@
+import { spawn } from "node:child_process";
+export async function terminateProcess(child, graceMs = 3_000) {
+    if (!child || child.exitCode !== null || child.signalCode !== null)
+        return;
+    if (process.platform === "win32") {
+        const killer = spawn("taskkill", ["/pid", String(child.pid), "/t", "/f"], {
+            stdio: "ignore",
+            windowsHide: true,
+        });
+        await waitForExitOrTimeout(killer, graceMs);
+        return;
+    }
+    try {
+        process.kill(-child.pid, "SIGTERM");
+    }
+    catch (error) {
+        if (error?.code !== "ESRCH")
+            throw error;
+        return;
+    }
+    await waitForExitOrTimeout(child, graceMs);
+    if (child.exitCode === null && child.signalCode === null) {
+        try {
+            process.kill(-child.pid, "SIGKILL");
+        }
+        catch (error) {
+            if (error?.code !== "ESRCH")
+                throw error;
+        }
+    }
+}
+export function delay(milliseconds) {
+    return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}
+function waitForExitOrTimeout(child, milliseconds) {
+    return new Promise((resolve) => {
+        let settled = false;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            child.removeListener("exit", finish);
+            resolve();
+        };
+        const timer = setTimeout(finish, milliseconds);
+        child.once("exit", finish);
+    });
+}
+//# sourceMappingURL=process.js.map

package/dist/src/process.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"process.js","sourceRoot":"","sources":["../../src/process.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,oBAAoB,CAAC;AAG3C,MAAM,CAAC,KAAK,UAAU,gBAAgB,CAAC,KAAsC,EAAE,OAAO,GAAG,KAAK;IAC5F,IAAI,CAAC,KAAK,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI;QAAE,OAAO;IAE3E,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,EAAE;YACxE,KAAK,EAAE,QAAQ;YACf,WAAW,EAAE,IAAI;SAClB,CAAC,CAAC;QACH,MAAM,oBAAoB,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;QAC5C,OAAO;IACT,CAAC;IAED,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,CAAE,KAAK,CAAC,GAAc,EAAE,SAAS,CAAC,CAAC;IAClD,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,IAAK,KAA+B,EAAE,IAAI,KAAK,OAAO;YAAE,MAAM,KAAK,CAAC;QACpE,OAAO;IACT,CAAC;IAED,MAAM,oBAAoB,CAAC,KAAK,EAAE,OAAO,CAAC,CAAC;IAC3C,IAAI,KAAK,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,CAAC,UAAU,KAAK,IAAI,EAAE,CAAC;QACzD,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,CAAE,KAAK,CAAC,GAAc,EAAE,SAAS,CAAC,CAAC;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAK,KAA+B,EAAE,IAAI,KAAK,OAAO;gBAAE,MAAM,KAAK,CAAC;QACtE,CAAC;IACH,CAAC;AACH,CAAC;AAED,MAAM,UAAU,KAAK,CAAC,YAAoB;IACxC,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE,CAAC,UAAU,CAAC,OAAO,EAAE,YAAY,CAAC,CAAC,CAAC;AACrE,CAAC;AAED,SAAS,oBAAoB,CAAC,KAAmB,EAAE,YAAoB;IACrE,OAAO,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,EAAE;QAC7B,IAAI,OAAO,GAAG,KAAK,CAAC;QACpB,MAAM,MAAM,GAAG,GAAG,EAAE;YAClB,IAAI,OAAO;gBAAE,OAAO;YACpB,OAAO,GAAG,IAAI,CAAC;YACf,YAAY,CAAC,KAAK,CAAC,CAAC;YACpB,KAAK,CAAC,cAAc,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;YACrC,OAAO,EAAE,CAAC;QACZ,CAAC,CAAC;QACF,MAAM,KAAK,GAAG,UAAU,CAAC,MAAM,EAAE,YAAY,CAAC,CAAC;QAC/C,KAAK,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/src/registry.js

@@ -0,0 +1,81 @@
+import { constants, createReadStream } from "node:fs";
+import { access, lstat, realpath } from "node:fs/promises";
+import { delimiter, isAbsolute, join, resolve } from "node:path";
+import { spawn } from "node:child_process";
+import { createHash } from "node:crypto";
+import { getAdapter, listDefinitions, publicDefinition } from "./adapters.js";
+export async function discoverAgents({ env = process.env, probeVersions = true, } = {}) {
+    return Promise.all(listDefinitions().map((definition) => inspectDefinition(definition, { env, probeVersions })));
+}
+export async function inspectAgent(id, { env = process.env, probeVersions = true } = {}) {
+    const definition = publicDefinition(getAdapter(id));
+    return inspectDefinition(definition, { env, probeVersions });
+}
+async function inspectDefinition(definition, { env, probeVersions }) {
+    const configured = env[definition.path_env]?.trim() || definition.command;
+    const executable = await resolveExecutable(configured, env.PATH || "");
+    if (!executable)
+        return { ...definition, status: "unavailable" };
+    const version = probeVersions
+        ? await detectVersion(executable, getAdapter(definition.id).version_args)
+        : "";
+    const identity = await fingerprintExecutable(executable);
+    return { ...definition, status: "available", executable, version, identity };
+}
+export async function resolveExecutable(command, searchPath) {
+    const candidates = isAbsolute(command) || command.includes("/") || command.includes("\\")
+        ? [resolve(command)]
+        : searchPath.split(delimiter).filter(Boolean).map((directory) => join(directory, command));
+    for (const candidate of candidates) {
+        try {
+            await access(candidate, constants.X_OK);
+            const info = await lstat(candidate);
+            if (info.isDirectory())
+                continue;
+            return await realpath(candidate);
+        }
+        catch {
+            // Keep probing PATH entries.
+        }
+    }
+    return null;
+}
+export async function detectVersion(executable, args, timeoutMs = 5_000) {
+    return new Promise((resolveVersion) => {
+        const child = spawn(executable, args, { stdio: ["ignore", "pipe", "pipe"], windowsHide: true });
+        let stdout = "";
+        let stderr = "";
+        const timer = setTimeout(() => child.kill("SIGKILL"), timeoutMs);
+        child.stdout.on("data", (chunk) => { stdout += chunk; });
+        child.stderr.on("data", (chunk) => { stderr += chunk; });
+        child.once("error", () => {
+            clearTimeout(timer);
+            resolveVersion("");
+        });
+        child.once("close", () => {
+            clearTimeout(timer);
+            resolveVersion(selectVersionLine(stdout, stderr));
+        });
+    });
+}
+export async function fingerprintExecutable(executable) {
+    const hash = createHash("sha256");
+    for await (const chunk of createReadStream(executable))
+        hash.update(chunk);
+    const digest = hash.digest("hex");
+    return `sha256:${digest}`;
+}
+export function selectVersionLine(stdout, stderr) {
+    const streams = [stdout, stderr];
+    const versionPattern = /(?:^|\s)v?\d+\.\d+\.\d+(?:[-+][0-9A-Za-z.-]+)?(?:\s|$)/;
+    for (const stream of streams) {
+        const match = String(stream || "")
+            .split(/\r?\n/)
+            .map((line) => line.trim())
+            .find((line) => versionPattern.test(line));
+        if (match)
+            return match;
+    }
+    return "";
+}
+//# sourceMappingURL=registry.js.map