pllla-connect 0.1.0

package/dist/account.js

@@ -0,0 +1,24 @@
+/**
+ * Bridge account id (docs/agent/EXTERNAL_RUNTIME.md §6.3) — one gateway can
+ * host N PLLLA agents, each as its own `channels.pllla.accounts.<id>` lane.
+ * The default id is derived from the pairing token so re-running the same
+ * connect command targets the same account instead of minting a new lane.
+ *
+ * Lives outside main.ts so tests can import it without executing the CLI.
+ */
+export const PAIRING_TOKEN_PREFIX = "pair_live_";
+const ACCOUNT_ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/;
+export function isValidAccountId(value) {
+    return ACCOUNT_ID_PATTERN.test(value);
+}
+/** `agent-` + the first 8 hex characters of the token body. */
+export function deriveAccountId(pairingToken) {
+    const body = pairingToken.startsWith(PAIRING_TOKEN_PREFIX)
+        ? pairingToken.slice(PAIRING_TOKEN_PREFIX.length)
+        : pairingToken;
+    const head = body.slice(0, 8).toLowerCase();
+    if (!/^[0-9a-f]{8}$/.test(head)) {
+        throw new Error("The pairing token looks malformed — copy the full command from the connect card in PLLLA.");
+    }
+    return `agent-${head}`;
+}

package/dist/catalog.js

@@ -0,0 +1,58 @@
+/**
+ * Server-driven runtime catalog — the connector never hardcodes runtime
+ * knowledge beyond the per-runtime bridge adapters. The list of runtimes,
+ * how to detect them, how to install them, and which Node they need all come
+ * from the server (docs/agent/EXTERNAL_RUNTIME.md), so a runtime raising its
+ * floor reaches every installed connector without a release.
+ *
+ * Mirrors `ExternalRuntimeDescriptor` in
+ * `src/data/constants/externalRuntimeCatalog.ts` — keep the two in step.
+ */
+function isRecord(value) {
+    return typeof value === "object" && value !== null;
+}
+/**
+ * Wire-shape guard. `runtime` arrived in the same contract generation as an
+ * additive field; a server without it cannot drive provisioning, so the
+ * connector refuses loudly instead of guessing a Node version.
+ */
+export function isCatalogRuntime(value) {
+    if (!isRecord(value))
+        return false;
+    const { detect, install, bridge, runtime } = value;
+    return (typeof value.id === "string" &&
+        typeof value.label === "string" &&
+        isRecord(detect) &&
+        Array.isArray(detect.commands) &&
+        Array.isArray(detect.gatewayPorts) &&
+        isRecord(install) &&
+        typeof install.command === "string" &&
+        isRecord(bridge) &&
+        typeof bridge.package === "string" &&
+        isRecord(runtime) &&
+        typeof runtime.nodeRange === "string" &&
+        typeof runtime.provisionNodeMajor === "number" &&
+        typeof runtime.minVersion === "string");
+}
+export async function fetchRuntimeCatalog(serverOrigin) {
+    const response = await fetch(`${serverOrigin}/api/user/ai-agent/external-runtimes`);
+    const data = await response.json().catch(() => null);
+    if (!response.ok ||
+        !isRecord(data) ||
+        data.success !== true ||
+        !Array.isArray(data.runtimes)) {
+        throw new Error(`Could not load the runtime catalog from ${serverOrigin} (HTTP ${response.status}).`);
+    }
+    const runtimes = [];
+    for (const entry of data.runtimes) {
+        if (!isCatalogRuntime(entry)) {
+            const id = isRecord(entry) && typeof entry.id === "string" ? entry.id : "?";
+            throw new Error(`Runtime catalog entry "${id}" is missing prerequisites (runtime.nodeRange/provisionNodeMajor/minVersion) — the server at ${serverOrigin} predates this connector.`);
+        }
+        runtimes.push(entry);
+    }
+    return {
+        contractVersion: typeof data.contractVersion === "number" ? data.contractVersion : 0,
+        runtimes,
+    };
+}

package/dist/detect.js

@@ -0,0 +1,176 @@
+/**
+ * Runtime detection — never trusts PATH alone (docs/agent/EXTERNAL_RUNTIME.md
+ * §6.2). GUI apps do not inherit the shell PATH (nvm/npm-global/homebrew), so
+ * a bare `openclaw` lookup misses an nvm-installed OpenClaw and the connector
+ * would wrongly start a second install. Detection order:
+ *
+ *   1. state dir `~/.openclaw/openclaw.json` (`OPENCLAW_STATE_DIR` respected)
+ *   2. a live gateway on the runtime's known ports
+ *   3. candidate bin dirs: PATH, the PLLLA private prefix, every nvm node,
+ *      homebrew, /usr/local, ~/.npm-global, ~/.local
+ *
+ * Every later CLI call uses the detected `binaryPath`; nothing here or
+ * downstream ever spawns a bare command name.
+ */
+import { execFileSync } from "node:child_process";
+import { accessSync, constants, existsSync, readdirSync, statSync, } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { prependPath } from "./exec.js";
+import { compareVersions, parseOpenClawVersion, parseVersion, } from "./version.js";
+export function resolveStateDir(env = process.env, home = homedir()) {
+    return env.OPENCLAW_STATE_DIR || join(home, ".openclaw");
+}
+/** Per-runtime config file that proves an install; null for unknown runtimes. */
+export function resolveStateFile(runtimeId, env = process.env, home = homedir()) {
+    if (runtimeId === "openclaw") {
+        return join(resolveStateDir(env, home), "openclaw.json");
+    }
+    return null;
+}
+/** `~/.pllla/runtimes/<runtimeId>` — the `npm install -g --prefix` target. */
+export function privateRuntimePrefix(home, runtimeId) {
+    return join(home, ".pllla", "runtimes", runtimeId);
+}
+/** `~/.nvm/versions/node/<v>/bin`, newest version first. */
+export function nvmNodeBinDirs(home) {
+    const versionsDir = join(home, ".nvm", "versions", "node");
+    let entries;
+    try {
+        entries = readdirSync(versionsDir);
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .map((name) => ({ name, version: parseVersion(name) }))
+        .filter((entry) => entry.version !== null)
+        .sort((a, b) => compareVersions(b.version, a.version))
+        .map((entry) => join(versionsDir, entry.name, "bin"));
+}
+/**
+ * Pure candidate computation (home + PATH injected) so the order in §6.2 is
+ * testable without a real machine. Duplicates and empties are dropped.
+ */
+export function candidateBinDirs(params) {
+    const { home, pathEnv, runtimeId } = params;
+    const platform = params.platform ?? process.platform;
+    const pathDelimiter = platform === "win32" ? ";" : ":";
+    const ordered = [
+        ...(pathEnv ?? "").split(pathDelimiter),
+        join(privateRuntimePrefix(home, runtimeId), "bin"),
+        ...nvmNodeBinDirs(home),
+        "/opt/homebrew/bin",
+        "/usr/local/bin",
+        join(home, ".npm-global", "bin"),
+        join(home, ".local", "bin"),
+    ];
+    const unique = [];
+    for (const dir of ordered) {
+        if (dir && !unique.includes(dir))
+            unique.push(dir);
+    }
+    return unique;
+}
+function isExecutableFile(path, platform) {
+    try {
+        if (!statSync(path).isFile())
+            return false;
+        if (platform !== "win32")
+            accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** First `<dir>/<name>` that is an executable file (`.cmd`/`.exe` on Windows). */
+export function findExecutable(name, dirs, platform = process.platform) {
+    const names = platform === "win32" ? [`${name}.cmd`, `${name}.exe`, name] : [name];
+    for (const dir of dirs) {
+        for (const candidate of names) {
+            const path = join(dir, candidate);
+            if (isExecutableFile(path, platform))
+                return path;
+        }
+    }
+    return null;
+}
+/**
+ * `<binaryPath> --version` → `X.Y.Z`. The env must put a usable `node` on
+ * PATH first — the runtime CLI is a `#!/usr/bin/env node` script.
+ */
+export function probeRuntimeVersion(binaryPath, env) {
+    try {
+        const output = execFileSync(binaryPath, ["--version"], {
+            encoding: "utf8",
+            env,
+            timeout: 20_000,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        return parseOpenClawVersion(output);
+    }
+    catch {
+        return null;
+    }
+}
+async function portAnswers(port) {
+    try {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), 1_500);
+        const response = await fetch(`http://127.0.0.1:${port}/`, {
+            signal: controller.signal,
+        });
+        clearTimeout(timer);
+        return response.status < 500;
+    }
+    catch {
+        return false;
+    }
+}
+export async function detectRuntime(runtime, options = {}) {
+    const home = options.home ?? homedir();
+    const env = options.env ?? process.env;
+    const platform = options.platform ?? process.platform;
+    const stateFile = resolveStateFile(runtime.id, env, home);
+    const stateDirFound = stateFile !== null && existsSync(stateFile);
+    let gatewayLive = false;
+    for (const port of runtime.detect.gatewayPorts) {
+        if (await portAnswers(port)) {
+            gatewayLive = true;
+            break;
+        }
+    }
+    const dirs = candidateBinDirs({
+        home,
+        pathEnv: env.PATH,
+        runtimeId: runtime.id,
+        platform,
+    });
+    let binaryPath = null;
+    for (const command of runtime.detect.commands) {
+        binaryPath = findExecutable(command, dirs, platform);
+        if (binaryPath)
+            break;
+    }
+    let version = null;
+    if (binaryPath) {
+        // The CLI's own dir first (an nvm install pairs with its sibling node),
+        // then whatever private/system node the caller already knows about.
+        const probeEnv = prependPath(env, [
+            dirname(binaryPath),
+            ...(options.extraBinDirs ?? []),
+            ...dirs,
+        ]);
+        version = probeRuntimeVersion(binaryPath, probeEnv);
+    }
+    return { runtime, binaryPath, version, gatewayLive, stateDirFound };
+}
+export async function detectRuntimes(runtimes, options = {}) {
+    const results = [];
+    for (const runtime of runtimes) {
+        results.push(await detectRuntime(runtime, options));
+    }
+    return results;
+}

package/dist/exec.js

@@ -0,0 +1,161 @@
+/**
+ * Subprocess helpers — every external command the connector runs goes
+ * through here so timeouts, output streaming, and PATH shaping are uniform.
+ *
+ * PATH matters more than usual: GUI-launched processes (the desktop app) do
+ * not inherit nvm/npm-global/homebrew PATH entries, and the `openclaw` bin
+ * is a `#!/usr/bin/env node` script — it cannot even start unless a `node`
+ * is reachable on the PATH we hand it (§6.1 "private first + verified").
+ */
+import { spawn } from "node:child_process";
+import { delimiter } from "node:path";
+export class CommandFailedError extends Error {
+    file;
+    args;
+    exitCode;
+    stdout;
+    stderr;
+    constructor(params) {
+        super(params.reason);
+        this.name = "CommandFailedError";
+        this.file = params.file;
+        this.args = params.args;
+        this.exitCode = params.exitCode;
+        this.stdout = params.stdout;
+        this.stderr = params.stderr;
+    }
+}
+/** Returns `env` with `dirs` prepended to PATH (deduplicated, empties dropped). */
+export function prependPath(env, dirs) {
+    const existing = (env.PATH ?? "").split(delimiter).filter(Boolean);
+    const merged = [];
+    for (const dir of [...dirs, ...existing]) {
+        if (dir && !merged.includes(dir))
+            merged.push(dir);
+    }
+    return { ...env, PATH: merged.join(delimiter) };
+}
+export function firstLine(text) {
+    return text.split("\n").find((line) => line.trim().length > 0) ?? "";
+}
+/** POSIX single-quote when needed — for `manualCommand` strings a person pastes. */
+export function shellQuote(value) {
+    return /^[A-Za-z0-9_./:=@%+,-]+$/.test(value)
+        ? value
+        : `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** The most useful single line out of a failed command for a user message. */
+export function describeCommandFailure(error) {
+    if (error instanceof CommandFailedError) {
+        const tail = [error.stderr, error.stdout]
+            .map((text) => text.trim().split("\n").filter(Boolean).slice(-1)[0] ?? "")
+            .find((line) => line.length > 0);
+        return tail ? `${error.message}: ${tail}` : error.message;
+    }
+    return error instanceof Error ? error.message : String(error);
+}
+function forwardLines(onLine) {
+    let pending = "";
+    return {
+        push: (chunk) => {
+            if (!onLine)
+                return;
+            pending += chunk.toString("utf8");
+            const lines = pending.split(/\r?\n/);
+            pending = lines.pop() ?? "";
+            for (const line of lines)
+                if (line.trim())
+                    onLine(line);
+        },
+        flush: () => {
+            if (onLine && pending.trim())
+                onLine(pending);
+            pending = "";
+        },
+    };
+}
+/**
+ * Runs a command to completion, streaming output. Rejects with
+ * `CommandFailedError` on a non-zero exit, a spawn error, or a timeout
+ * (SIGTERM, then SIGKILL five seconds later).
+ */
+export function runCommand(options) {
+    const { file, args, env, cwd, timeoutMs, onLine } = options;
+    return new Promise((resolve, reject) => {
+        const useShell = process.platform === "win32" && /\.(cmd|bat)$/i.test(file);
+        const child = spawn(file, args, {
+            cwd,
+            env: env ?? process.env,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+            shell: useShell,
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        let timedOut = false;
+        const out = forwardLines(onLine);
+        const err = forwardLines(onLine);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            setTimeout(() => {
+                if (!settled)
+                    child.kill("SIGKILL");
+            }, 5_000).unref();
+        }, timeoutMs);
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk.toString("utf8");
+            out.push(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk.toString("utf8");
+            err.push(chunk);
+        });
+        child.on("error", (error) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            reject(new CommandFailedError({
+                file,
+                args,
+                exitCode: null,
+                stdout,
+                stderr,
+                reason: `Could not run ${file}: ${error.message}`,
+            }));
+        });
+        child.on("close", (code, signal) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            out.flush();
+            err.flush();
+            if (timedOut) {
+                reject(new CommandFailedError({
+                    file,
+                    args,
+                    exitCode: code,
+                    stdout,
+                    stderr,
+                    reason: `${file} ${args.join(" ")} timed out after ${Math.round(timeoutMs / 1000)}s`,
+                }));
+                return;
+            }
+            if (code !== 0) {
+                reject(new CommandFailedError({
+                    file,
+                    args,
+                    exitCode: code,
+                    stdout,
+                    stderr,
+                    reason: `${file} ${args.join(" ")} exited with ${code ?? `signal ${signal ?? "unknown"}`}`,
+                }));
+                return;
+            }
+            resolve({ stdout, stderr });
+        });
+    });
+}