pllla-connect 0.1.0

package/dist/nodeResolve.js

@@ -0,0 +1,84 @@
+/**
+ * Which Node runs the runtime CLI — "private first + verified", the opposite
+ * of the desktop's agentManager resolver (docs/agent/EXTERNAL_RUNTIME.md §6.1).
+ * System-first would grab an older system node (an nvm 22.17, say) and fail
+ * the runtime's floor; private-first picks the copy PLLLA already verified,
+ * then any system node that passes `nodeRange`, and only then downloads.
+ *
+ * Used for an existing install too: the detected `openclaw` is a
+ * `#!/usr/bin/env node` script, so bridging it needs a qualifying `node` on
+ * the PATH we hand it — without ever touching the user's own Node.
+ */
+import { execFileSync } from "node:child_process";
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { candidateBinDirs, findExecutable } from "./detect.js";
+import { defaultNodeRoot, ensurePrivateNode, pickPrivateNode, scanPrivateNodes, } from "./nodeProvision.js";
+import { parseVersion, formatVersion, satisfiesNodeRange } from "./version.js";
+export function probeNodeVersion(nodeBin) {
+    try {
+        const output = execFileSync(nodeBin, ["--version"], {
+            encoding: "utf8",
+            timeout: 15_000,
+            stdio: ["ignore", "pipe", "pipe"],
+            windowsHide: true,
+        });
+        const parsed = parseVersion(output);
+        return parsed ? formatVersion(parsed) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function resolveNodeForRuntime(params) {
+    const home = params.home ?? homedir();
+    const env = params.env ?? process.env;
+    const platform = params.platform ?? process.platform;
+    const root = params.root ?? defaultNodeRoot(home);
+    const privateNode = pickPrivateNode(scanPrivateNodes(root), params.nodeRange);
+    if (privateNode) {
+        params.log(`Using private Node ${privateNode.version}.`);
+        return { ...privateNode, source: "private" };
+    }
+    const dirs = [
+        ...(params.preferredDirs ?? []),
+        ...candidateBinDirs({
+            home,
+            pathEnv: env.PATH,
+            runtimeId: "openclaw",
+            platform,
+        }),
+    ];
+    const seen = new Set();
+    for (const dir of dirs) {
+        if (seen.has(dir))
+            continue;
+        seen.add(dir);
+        const nodeBin = findExecutable("node", [dir], platform);
+        if (!nodeBin)
+            continue;
+        const version = probeNodeVersion(nodeBin);
+        if (!version || !satisfiesNodeRange(version, params.nodeRange))
+            continue;
+        const npmCli = join(dir, "..", "lib", "node_modules", "npm", "bin", "npm-cli.js");
+        params.log(`Using system Node ${version} at ${nodeBin} (untouched).`);
+        return {
+            version,
+            nodeBin,
+            nodeBinDir: dir,
+            // npm-cli.js runs as `node npm-cli.js` — existence, not an exec bit.
+            npmCli: existsSync(npmCli) ? npmCli : null,
+            source: "system",
+        };
+    }
+    const provisioned = await ensurePrivateNode({
+        nodeRange: params.nodeRange,
+        provisionNodeMajor: params.provisionNodeMajor,
+        root,
+        platform,
+        log: params.log,
+        progress: params.progress,
+    });
+    return { ...provisioned, source: "provisioned" };
+}

package/dist/openclaw.js

@@ -0,0 +1,338 @@
+/**
+ * OpenClaw adapter — the connector's per-runtime knowledge lives here; the
+ * shared flow (catalog, detection, Node, progress) stays runtime-agnostic.
+ *
+ * Two entry situations (docs/agent/EXTERNAL_RUNTIME.md §6):
+ *   - existing install → `bridgeExisting` only: plugin + one account under
+ *     `channels.pllla.accounts.<accountId>` + gateway restart. Other accounts'
+ *     keys, the user's Node, and their brain are never touched.
+ *   - nothing installed → `installFresh` into the private prefix on the
+ *     private Node, `resolveAuthChoice` (brain ladder §6.5), `onboardFresh`,
+ *     then the same `bridgeExisting`.
+ *
+ * Every call runs the detected/installed `binaryPath` (never a bare
+ * `openclaw`) with a PATH that starts with the Node we resolved — the CLI is
+ * a `#!/usr/bin/env node` script. The bridge plugin consumes the pairing
+ * token at gateway start, so the rt- runtime key never crosses argv here.
+ */
+import { existsSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { candidateBinDirs, findExecutable, privateRuntimePrefix, } from "./detect.js";
+import { describeCommandFailure, prependPath, runCommand, shellQuote, } from "./exec.js";
+import { ConnectError } from "./progress.js";
+const BRIDGE_TIMEOUT_MS = 3 * 60_000;
+const INSTALL_TIMEOUT_MS = 20 * 60_000;
+const ONBOARD_TIMEOUT_MS = 10 * 60_000;
+const GATEWAY_TIMEOUT_MS = 2 * 60_000;
+/**
+ * PATH for running the runtime CLI: resolved Node first (§6.1 private first),
+ * then the CLI's own dir (an nvm install pairs with its sibling node), then
+ * every §6.2 candidate dir so tools the runtime shells out to are reachable
+ * from a GUI-launched process.
+ */
+export function buildRuntimeEnv(params) {
+    const home = params.home ?? homedir();
+    const baseEnv = params.baseEnv ?? process.env;
+    return prependPath(baseEnv, [
+        params.nodeBinDir,
+        dirname(params.binaryPath),
+        ...candidateBinDirs({
+            home,
+            pathEnv: baseEnv.PATH,
+            runtimeId: "openclaw",
+            platform: params.platform,
+        }),
+    ]);
+}
+/** The command a person runs in a terminal to finish onboarding themselves. */
+export function buildManualOnboardCommand(params) {
+    return `PATH=${shellQuote(params.nodeBinDir)}:"$PATH" ${shellQuote(params.binaryPath)} onboard`;
+}
+async function runOpenClaw(params) {
+    const result = await runCommand({
+        file: params.binaryPath,
+        args: params.args,
+        env: params.env,
+        timeoutMs: params.timeoutMs,
+        onLine: params.log,
+    });
+    return result.stdout;
+}
+/**
+ * Wires one PLLLA account into an OpenClaw that already exists. Idempotent:
+ * re-running with the same account overwrites only that account's two keys.
+ */
+export async function bridgeExisting(params) {
+    const { binaryPath, accountId, pairingToken, serverOrigin, bridgePackage, log, } = params;
+    const env = buildRuntimeEnv({
+        nodeBinDir: params.nodeBinDir,
+        binaryPath,
+        home: params.home,
+    });
+    const run = (args, timeoutMs = BRIDGE_TIMEOUT_MS) => runOpenClaw({ binaryPath, args, env, timeoutMs, log });
+    // 설치 여부는 에러 문구가 아니라 *상태* 로 판정한다 — 이미 설치된 플러그인
+    // (로컬 tgz 설치 포함)은 npm 이 404/불통이어도 설치 단계를 건너뛰어야 한다.
+    let bridgeInstalled = false;
+    try {
+        await run(["plugins", "inspect", "pllla"]);
+        bridgeInstalled = true;
+        log("PLLLA bridge plugin already installed — skipping install.");
+    }
+    catch {
+        bridgeInstalled = false;
+    }
+    if (!bridgeInstalled) {
+        log(`Installing the PLLLA bridge plugin (${bridgePackage})…`);
+        try {
+            await run(["plugins", "install", `npm:${bridgePackage}`]);
+        }
+        catch (error) {
+            const failure = describeCommandFailure(error);
+            // "이미 설치됨"만 관용한다. 그 밖(npm 404, 네트워크 등)을 넘기면 뒤 config
+            // set 이 "unknown channel id: pllla" 로 터져 진짜 원인이 가려진다(실기계 재현).
+            if (!/already (installed|exists|enabled|up.to.date)/i.test(failure)) {
+                throw new ConnectError({
+                    phase: "bridge",
+                    code: "bridge_failed",
+                    message: `Could not install the PLLLA bridge plugin (${bridgePackage}): ${failure}${/404|not found|E404/i.test(failure)
+                        ? " — the bridge package is not available on npm yet."
+                        : ""}`,
+                    cause: error,
+                });
+            }
+            log(`Plugin already present (${failure}) — continuing.`);
+        }
+    }
+    log(`Configuring PLLLA account "${accountId}"…`);
+    const accountKey = `channels.pllla.accounts.${accountId}`;
+    try {
+        await run(["config", "set", `${accountKey}.serverOrigin`, serverOrigin]);
+        await run(["config", "set", `${accountKey}.pairingToken`, pairingToken]);
+    }
+    catch (error) {
+        const failure = describeCommandFailure(error);
+        // 채널 id 미등록 = 플러그인이 로드되지 않은 것 — 설정 문법이 아니라 플러그인
+        // 부재/비활성이 원인임을 그대로 말한다.
+        const hint = /unknown channel id/i.test(failure)
+            ? " OpenClaw has no 'pllla' channel registered — the bridge plugin is not installed or not enabled."
+            : "";
+        throw new ConnectError({
+            phase: "bridge",
+            code: "bridge_failed",
+            message: `Could not write the PLLLA account into OpenClaw's config: ${failure}${hint}`,
+            cause: error,
+        });
+    }
+    try {
+        await run(["plugins", "enable", "pllla"]);
+    }
+    catch {
+        /* bundled auto-enable — enable is best-effort */
+    }
+    log("Restarting the OpenClaw gateway so the bridge pairs and connects…");
+    try {
+        await run(["gateway", "restart"], GATEWAY_TIMEOUT_MS);
+        return { gatewayRestarted: true };
+    }
+    catch (error) {
+        log(`Could not restart the gateway automatically (${describeCommandFailure(error)}). Start it yourself — e.g. \`${shellQuote(binaryPath)} gateway restart\` — the bridge pairs on startup.`);
+        return { gatewayRestarted: false };
+    }
+}
+/**
+ * `npm install -g openclaw@latest --prefix ~/.pllla/runtimes/openclaw` on the
+ * private Node. `--prefix` keeps the user's global npm tree untouched.
+ */
+export async function installFresh(params) {
+    const home = params.home ?? homedir();
+    const prefix = params.prefix ?? privateRuntimePrefix(home, "openclaw");
+    const nodeBinDir = dirname(params.nodeBin);
+    const env = {
+        ...prependPath(process.env, [nodeBinDir]),
+        npm_config_update_notifier: "false",
+        npm_config_fund: "false",
+        npm_config_audit: "false",
+    };
+    params.log(`Installing OpenClaw into ${prefix} (private Node)…`);
+    try {
+        await runCommand({
+            file: params.nodeBin,
+            args: [
+                params.npmCli,
+                "install",
+                "-g",
+                "openclaw@latest",
+                "--prefix",
+                prefix,
+                "--allow-scripts=openclaw",
+            ],
+            env,
+            cwd: home,
+            timeoutMs: INSTALL_TIMEOUT_MS,
+            onLine: params.log,
+        });
+    }
+    catch (error) {
+        throw new ConnectError({
+            phase: "install",
+            code: "install_failed",
+            message: `OpenClaw install failed: ${describeCommandFailure(error)}`,
+            cause: error,
+        });
+    }
+    const binaryPath = join(prefix, "bin", "openclaw");
+    if (!existsSync(binaryPath)) {
+        throw new ConnectError({
+            phase: "install",
+            code: "install_failed",
+            message: `npm finished but ${binaryPath} does not exist.`,
+        });
+    }
+    return { binaryPath, prefix };
+}
+function parseJsonObject(text) {
+    const start = text.indexOf("{");
+    if (start < 0)
+        return null;
+    try {
+        const parsed = JSON.parse(text.slice(start));
+        return typeof parsed === "object" && parsed !== null
+            ? parsed
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** `ollama list` table → model names (header row dropped). */
+export function parseOllamaModels(output) {
+    return output
+        .split("\n")
+        .map((line) => line.trim())
+        .filter((line) => line.length > 0 && !/^NAME\s/i.test(line))
+        .map((line) => line.split(/\s+/)[0])
+        .filter((name) => name.length > 0);
+}
+/**
+ * Brain ladder (§6.5): a signed-in Claude Code → `anthropic-cli`; else a
+ * local Ollama with at least one model → `ollama` (with a caveat); else null
+ * — the caller stops with `needs_model_auth`. No starter brain is lent.
+ */
+export async function resolveAuthChoice(params) {
+    const home = params.home ?? homedir();
+    const baseEnv = params.env ?? process.env;
+    const platform = params.platform ?? process.platform;
+    const dirs = [
+        join(home, ".claude", "local"),
+        ...candidateBinDirs({
+            home,
+            pathEnv: baseEnv.PATH,
+            runtimeId: "openclaw",
+            platform,
+        }),
+    ];
+    const env = prependPath(baseEnv, [
+        ...(params.nodeBinDir ? [params.nodeBinDir] : []),
+        ...dirs,
+    ]);
+    const claudeBin = findExecutable("claude", dirs, platform);
+    if (claudeBin) {
+        try {
+            const { stdout } = await runCommand({
+                file: claudeBin,
+                args: ["auth", "status", "--json"],
+                env,
+                timeoutMs: 30_000,
+            });
+            const status = parseJsonObject(stdout);
+            if (status?.loggedIn === true) {
+                return {
+                    choice: "anthropic-cli",
+                    detail: `Claude Code is signed in (${claudeBin}) — OpenClaw will use it as its brain.`,
+                };
+            }
+            params.log(`Claude Code found at ${claudeBin} but not signed in.`);
+        }
+        catch (error) {
+            params.log(`Claude Code at ${claudeBin} did not answer \`auth status\`: ${describeCommandFailure(error)}`);
+        }
+    }
+    const ollamaBin = findExecutable("ollama", dirs, platform);
+    if (ollamaBin) {
+        try {
+            const { stdout } = await runCommand({
+                file: ollamaBin,
+                args: ["list"],
+                env,
+                timeoutMs: 20_000,
+            });
+            const models = parseOllamaModels(stdout);
+            if (models.length > 0) {
+                return {
+                    choice: "ollama",
+                    detail: `Ollama has ${models.length} local model(s): ${models.slice(0, 5).join(", ")}.`,
+                    warning: "Small local models are weak at tool calling (measured: a 20b model ran out of memory on 16 GB; gemma4 ignores tools). Replies may be unreliable — sign in to Claude Code for a dependable brain.",
+                };
+            }
+            params.log(`Ollama found at ${ollamaBin} but it has no models.`);
+        }
+        catch (error) {
+            params.log(`Ollama at ${ollamaBin} did not answer \`list\`: ${describeCommandFailure(error)}`);
+        }
+    }
+    return null;
+}
+/**
+ * `onboard --non-interactive …` on the private Node, then the gateway
+ * service (install is best-effort — a restart failure is guidance only,
+ * because `bridgeExisting` restarts again after wiring the plugin).
+ */
+export async function onboardFresh(params) {
+    const { binaryPath, authChoice, log } = params;
+    const env = buildRuntimeEnv({
+        nodeBinDir: params.nodeBinDir,
+        binaryPath,
+        home: params.home,
+    });
+    const run = (args, timeoutMs) => runOpenClaw({ binaryPath, args, env, timeoutMs, log });
+    log(`Onboarding OpenClaw with auth choice "${authChoice}"…`);
+    try {
+        await run([
+            "onboard",
+            "--non-interactive",
+            "--accept-risk",
+            "--flow",
+            "quickstart",
+            "--auth-choice",
+            authChoice,
+            "--skip-health",
+            "--json",
+        ], ONBOARD_TIMEOUT_MS);
+    }
+    catch (error) {
+        throw new ConnectError({
+            phase: "onboard",
+            code: "install_failed",
+            message: `OpenClaw onboarding failed: ${describeCommandFailure(error)}`,
+            manualCommand: buildManualOnboardCommand({
+                binaryPath,
+                nodeBinDir: params.nodeBinDir,
+            }),
+            cause: error,
+        });
+    }
+    log("Installing the OpenClaw gateway service…");
+    try {
+        await run(["gateway", "install"], GATEWAY_TIMEOUT_MS);
+    }
+    catch (error) {
+        log(`Gateway service install reported: ${describeCommandFailure(error)} (continuing)`);
+    }
+    try {
+        await run(["gateway", "restart"], GATEWAY_TIMEOUT_MS);
+    }
+    catch (error) {
+        log(`Gateway restart reported: ${describeCommandFailure(error)} (the bridge step restarts again)`);
+    }
+}

package/dist/progress.js

@@ -0,0 +1,74 @@
+/**
+ * NDJSON progress protocol (docs/agent/EXTERNAL_RUNTIME.md §6.4).
+ *
+ * With `--json` every step is one JSON object per line on **stdout** — the
+ * desktop app reads it to draw the connect card's step timeline. Human text
+ * (subprocess output, hints) always goes to **stderr**, so stdout stays a
+ * clean machine channel; without `--json` the same events are rendered as
+ * text on stderr too.
+ *
+ * `needs_model_auth` is an honest stop, not a failure: it carries the
+ * `manualCommand` a person runs in a terminal (§6.5).
+ */
+/**
+ * Failure carrying the phase it happened in so `main` emits exactly one
+ * error event with the contract's code. Modules throw this when phase and
+ * code are unambiguous; anything else is wrapped by the caller.
+ */
+export class ConnectError extends Error {
+    phase;
+    code;
+    manualCommand;
+    constructor(params) {
+        super(params.message, { cause: params.cause });
+        this.name = "ConnectError";
+        this.phase = params.phase;
+        this.code = params.code;
+        this.manualCommand = params.manualCommand;
+    }
+}
+export function toConnectError(error, fallbackPhase, fallbackCode) {
+    if (error instanceof ConnectError)
+        return error;
+    return new ConnectError({
+        phase: fallbackPhase,
+        code: fallbackCode,
+        message: error instanceof Error ? error.message : String(error),
+        cause: error,
+    });
+}
+export function formatProgressLine(event) {
+    const label = `[${event.phase}]`.padEnd(10);
+    if (event.status === "error") {
+        const code = event.code ? ` (${event.code})` : "";
+        const manual = event.manualCommand
+            ? `\n${" ".repeat(10)}Run: ${event.manualCommand}`
+            : "";
+        return `${label}error${code}: ${event.message ?? ""}${manual}`;
+    }
+    if (event.status === "done") {
+        const account = event.account ? ` account=${event.account}` : "";
+        return `${label}done${account}${event.message ? ` — ${event.message}` : ""}`;
+    }
+    return `${label}${event.message ?? ""}`;
+}
+export function createProgressReporter(options) {
+    const stdout = options.stdout ?? process.stdout;
+    const stderr = options.stderr ?? process.stderr;
+    const emit = (event) => {
+        if (options.json) {
+            stdout.write(`${JSON.stringify(event)}\n`);
+        }
+        else {
+            stderr.write(`${formatProgressLine(event)}\n`);
+        }
+    };
+    return {
+        json: options.json,
+        emit,
+        log: (line) => {
+            stderr.write(`${line}\n`);
+        },
+        progress: (phase, message) => emit({ phase, status: "progress", message }),
+    };
+}

package/dist/version.js

@@ -0,0 +1,105 @@
+/**
+ * Version arithmetic without a semver dependency — the connector ships with
+ * zero runtime dependencies so the desktop can bundle `dist/` alone.
+ *
+ * Evaluates the server catalog's `runtime.nodeRange`
+ * (`">=22.22.3 <23 || >=24.15.0 <25 || >=25.9.0"`) and `runtime.minVersion`
+ * (docs/agent/EXTERNAL_RUNTIME.md §6.1·6.2). Ranges are `||`-joined clauses;
+ * each clause is whitespace-separated comparators (`>=X.Y.Z`, optional `<M`).
+ */
+const FULL_VERSION_PATTERN = /(\d+)\.(\d+)\.(\d+)/;
+const COMPARATOR_PATTERN = /^(>=|<=|>|<|=)?v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/;
+/** First `X.Y.Z` inside the input (`v26.0.0`, `OpenClaw 2026.8.2 (0965053)`). */
+export function parseVersion(input) {
+    if (!input)
+        return null;
+    const match = FULL_VERSION_PATTERN.exec(input);
+    if (!match)
+        return null;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+    };
+}
+export function formatVersion(version) {
+    return `${version.major}.${version.minor}.${version.patch}`;
+}
+function toParsed(value) {
+    if (typeof value !== "string")
+        return value;
+    const parsed = parseVersion(value);
+    if (!parsed)
+        throw new Error(`Not a version: "${value}"`);
+    return parsed;
+}
+/** -1 / 0 / 1 like `Array.prototype.sort` comparators. */
+export function compareVersions(left, right) {
+    const a = toParsed(left);
+    const b = toParsed(right);
+    for (const key of ["major", "minor", "patch"]) {
+        if (a[key] < b[key])
+            return -1;
+        if (a[key] > b[key])
+            return 1;
+    }
+    return 0;
+}
+/**
+ * OpenClaw prints `OpenClaw 2026.8.2 (0965053)`; older builds may print the
+ * bare version. Returns the `X.Y.Z` string or null when nothing parses.
+ */
+export function parseOpenClawVersion(output) {
+    const parsed = parseVersion(output);
+    return parsed ? formatVersion(parsed) : null;
+}
+function parseComparator(token, clause) {
+    const match = COMPARATOR_PATTERN.exec(token);
+    if (!match) {
+        throw new Error(`Unsupported node range clause "${clause}" (token "${token}")`);
+    }
+    const operator = (match[1] ?? "=");
+    return {
+        operator,
+        version: {
+            major: Number(match[2]),
+            minor: Number(match[3] ?? 0),
+            patch: Number(match[4] ?? 0),
+        },
+    };
+}
+function matchesComparator(version, comparator) {
+    const order = compareVersions(version, comparator.version);
+    switch (comparator.operator) {
+        case ">=":
+            return order >= 0;
+        case "<=":
+            return order <= 0;
+        case ">":
+            return order > 0;
+        case "<":
+            return order < 0;
+        case "=":
+            return order === 0;
+    }
+}
+/**
+ * True when `version` satisfies any `||` clause of `range`. An empty range
+ * means "no constraint". Malformed clauses throw so a server-side typo is
+ * loud instead of silently provisioning the wrong Node.
+ */
+export function satisfiesNodeRange(version, range) {
+    const parsed = typeof version === "string" ? parseVersion(version) : version;
+    if (!parsed)
+        return false;
+    const clauses = range
+        .split("||")
+        .map((clause) => clause.trim())
+        .filter(Boolean);
+    if (clauses.length === 0)
+        return true;
+    return clauses.some((clause) => clause
+        .split(/\s+/)
+        .map((token) => parseComparator(token, clause))
+        .every((comparator) => matchesComparator(parsed, comparator)));
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "pllla-connect",
+  "version": "0.1.0",
+  "description": "Connect a self-hosted agent runtime (OpenClaw, …) to a PLLLA agent with one command",
+  "type": "module",
+  "bin": {
+    "pllla-connect": "./dist/main.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "typescript": "^5.5.0"
+  }
+}