forge-openclaw-plugin 0.2.12 → 0.2.15

package/README.md

@@ -201,7 +201,7 @@ The skill is entity-format-driven. It teaches the agent how to:
 - ask only for missing fields
 - capture goals, projects, tasks, values, patterns, behaviors, beliefs, and trigger reports
 
-For local use, set the plugin origin to `http://127.0.0.1` or `http://localhost` and the plugin will bring Forge up on the configured port automatically.
+For local use, set the plugin origin to `http://127.0.0.1` or `http://localhost` and the plugin will bring Forge up automatically. If you leave the default localhost setup alone and `4317` is already taken, Forge now moves to the next free local port and remembers that choice for future runs.
 
 If you want to manage that plugin-managed local runtime cleanly, use:
 
@@ -214,6 +214,16 @@ openclaw forge status
 
 These commands only manage the runtime when it was auto-started by the OpenClaw plugin. If Forge was started manually some other way, they tell you that instead of killing unrelated processes.
 
+If the local runtime fails to come up, check the plugin-managed runtime log at:
+
+```bash
+~/.openclaw/logs/forge-openclaw-plugin/<host>-<port>.log
+```
+
+On clean installs, the plugin now also repairs missing bundled runtime dependencies on first local start before it launches Forge.
+
+The startup error now points at that log file when the child process exits before Forge becomes healthy.
+
 ## Publishing and listing
 
 The reliable publication path for the Forge plugin is:

package/dist/openclaw/api-client.d.ts

@@ -5,6 +5,7 @@ export type ForgePluginConfig = {
     port: number;
     baseUrl: string;
     webAppUrl: string;
+    portSource: "configured" | "default" | "preferred";
     dataRoot: string;
     apiToken: string;
     actorLabel: string;

package/dist/openclaw/local-runtime.js

@@ -1,5 +1,6 @@
 import { spawn } from "node:child_process";
-import { existsSync } from "node:fs";
+import { closeSync, existsSync, mkdirSync, openSync } from "node:fs";
+import net from "node:net";
 import { homedir } from "node:os";
 import path from "node:path";
 import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
@@ -8,15 +9,79 @@ const LOCAL_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1"]);
 const STARTUP_TIMEOUT_MS = 15_000;
 const HEALTHCHECK_TIMEOUT_MS = 1_500;
 const HEALTHCHECK_INTERVAL_MS = 250;
+const EXISTING_RUNTIME_GRACE_MS = 3_000;
+const MAX_PORT_SCAN_ATTEMPTS = 20;
+const FORGE_PLUGIN_ID = "forge-openclaw-plugin";
 let managedRuntimeChild = null;
 let managedRuntimeKey = null;
+let managedRuntimeLogPath = null;
+let lastRuntimeExitDetails = null;
 let startupPromise = null;
+let startupRuntimeKey = null;
+const dependencyInstallPromises = new Map();
 function runtimeKey(config) {
     return `${config.origin}:${config.port}`;
 }
+function buildForgeBaseUrl(origin, port) {
+    const url = new URL(origin.endsWith("/") ? origin : `${origin}/`);
+    url.port = String(port);
+    url.pathname = "/";
+    url.search = "";
+    url.hash = "";
+    return url.origin;
+}
+function buildForgeWebAppUrl(origin, port) {
+    return `${buildForgeBaseUrl(origin, port)}/forge/`;
+}
 function getRuntimeStatePath(config) {
     const origin = new URL(config.origin).hostname.toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
-    return path.join(homedir(), ".openclaw", "run", "forge-openclaw-plugin", `${origin}-${config.port}.json`);
+    return path.join(homedir(), ".openclaw", "run", FORGE_PLUGIN_ID, `${origin}-${config.port}.json`);
+}
+function getPreferredPortStatePath(origin) {
+    const hostname = new URL(origin).hostname.toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+    return path.join(homedir(), ".openclaw", "run", FORGE_PLUGIN_ID, `${hostname}-preferred-port.json`);
+}
+function applyPortToConfig(config, port, portSource) {
+    config.port = port;
+    config.baseUrl = buildForgeBaseUrl(config.origin, port);
+    config.webAppUrl = buildForgeWebAppUrl(config.origin, port);
+    config.portSource = portSource;
+}
+async function writePreferredPortState(config, port) {
+    const statePath = getPreferredPortStatePath(config.origin);
+    await mkdir(path.dirname(statePath), { recursive: true });
+    await writeFile(statePath, `${JSON.stringify({ origin: config.origin, port, updatedAt: new Date().toISOString() }, null, 2)}\n`, "utf8");
+}
+async function isPortAvailable(host, port) {
+    return await new Promise((resolve) => {
+        const server = net.createServer();
+        server.unref();
+        server.once("error", (error) => {
+            resolve(error.code !== "EADDRINUSE");
+        });
+        server.listen({ host, port, exclusive: true }, () => {
+            server.close(() => resolve(true));
+        });
+    });
+}
+async function findAvailableLocalPort(host, startPort) {
+    for (let candidate = Math.max(1, startPort), attempts = 0; candidate <= 65_535 && attempts < MAX_PORT_SCAN_ATTEMPTS; candidate += 1, attempts += 1) {
+        if (await isPortAvailable(host, candidate)) {
+            return candidate;
+        }
+    }
+    return null;
+}
+async function relocateLocalRuntimePort(config) {
+    if (config.portSource === "configured") {
+        throw new Error(`Configured Forge port ${config.port} is already in use on ${new URL(config.origin).hostname}. Set a different plugin port or stop the process using it.`);
+    }
+    const nextPort = await findAvailableLocalPort("127.0.0.1", config.port + 1);
+    if (nextPort === null) {
+        throw new Error(`Forge could not find a free localhost port after ${config.port}.`);
+    }
+    applyPortToConfig(config, nextPort, "preferred");
+    await writePreferredPortState(config, nextPort);
 }
 async function writeRuntimeState(config, pid) {
     const statePath = getRuntimeStatePath(config);
@@ -26,7 +91,8 @@ async function writeRuntimeState(config, pid) {
         origin: config.origin,
         port: config.port,
         baseUrl: config.baseUrl,
-        startedAt: new Date().toISOString()
+        startedAt: new Date().toISOString(),
+        logPath: managedRuntimeLogPath
     };
     await writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
 }
@@ -45,7 +111,8 @@ async function readRuntimeState(config) {
             origin: typeof parsed.origin === "string" ? parsed.origin : config.origin,
             port: typeof parsed.port === "number" ? parsed.port : config.port,
             baseUrl: typeof parsed.baseUrl === "string" ? parsed.baseUrl : config.baseUrl,
-            startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : new Date(0).toISOString()
+            startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : new Date(0).toISOString(),
+            logPath: typeof parsed.logPath === "string" ? parsed.logPath : null
         };
     }
     catch {
@@ -82,6 +149,86 @@ function isLocalOrigin(origin) {
 function getCurrentModuleRoot() {
     return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
 }
+function getRuntimeLogPath(config) {
+    const origin = new URL(config.origin).hostname.toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+    return path.join(homedir(), ".openclaw", "logs", FORGE_PLUGIN_ID, `${origin}-${config.port}.log`);
+}
+function openRuntimeLogFile(logPath) {
+    mkdirSync(path.dirname(logPath), { recursive: true });
+    return openSync(logPath, "a");
+}
+function isPackagedServerPlan(plan) {
+    return plan.entryFile.endsWith(path.join("dist", "server", "index.js"));
+}
+function getNpmInvocation() {
+    const binDir = path.dirname(process.execPath);
+    const npmCli = process.platform === "win32" ? path.join(binDir, "npm.cmd") : path.join(binDir, "npm");
+    if (existsSync(npmCli)) {
+        return {
+            command: process.execPath,
+            args: [npmCli]
+        };
+    }
+    return {
+        command: "npm",
+        args: []
+    };
+}
+async function getMissingRuntimeDependencies(packageRoot) {
+    const packageJsonPath = path.join(packageRoot, "package.json");
+    const packageJson = JSON.parse(await readFile(packageJsonPath, "utf8"));
+    const dependencyNames = Object.keys(packageJson.dependencies ?? {});
+    return dependencyNames.filter((dependencyName) => !existsSync(path.join(packageRoot, "node_modules", dependencyName, "package.json")));
+}
+async function installMissingRuntimeDependencies(packageRoot, logPath) {
+    const { command, args } = getNpmInvocation();
+    const logFd = openRuntimeLogFile(logPath);
+    try {
+        await new Promise((resolve, reject) => {
+            const child = spawn(command, [...args, "install", "--omit=dev", "--silent", "--ignore-scripts"], {
+                cwd: packageRoot,
+                env: process.env,
+                stdio: ["ignore", logFd, logFd]
+            });
+            child.once("error", reject);
+            child.once("exit", (code, signal) => {
+                if (code === 0) {
+                    resolve();
+                    return;
+                }
+                reject(new Error(`npm dependency install exited with ${signal ? `signal ${signal}` : `code ${code ?? "unknown"}`}`));
+            });
+        });
+    }
+    finally {
+        closeSync(logFd);
+    }
+}
+async function ensurePackagedRuntimeDependencies(plan, config) {
+    if (!isPackagedServerPlan(plan)) {
+        return;
+    }
+    const missingDependencies = await getMissingRuntimeDependencies(plan.packageRoot);
+    if (missingDependencies.length === 0) {
+        return;
+    }
+    const logPath = getRuntimeLogPath(config);
+    managedRuntimeLogPath = logPath;
+    const installKey = plan.packageRoot;
+    const existingInstall = dependencyInstallPromises.get(installKey);
+    if (existingInstall) {
+        return existingInstall;
+    }
+    const installPromise = installMissingRuntimeDependencies(plan.packageRoot, logPath)
+        .catch((error) => {
+        throw new Error(`Forge runtime dependencies are missing (${missingDependencies.join(", ")}) and automatic install failed. Check logs at ${logPath}. Cause: ${error instanceof Error ? error.message : String(error)}`);
+    })
+        .finally(() => {
+        dependencyInstallPromises.delete(installKey);
+    });
+    dependencyInstallPromises.set(installKey, installPromise);
+    return installPromise;
+}
 function resolveLaunchPlan() {
     const moduleRoot = getCurrentModuleRoot();
     // Published or linked plugin package runtime.
@@ -125,9 +272,11 @@ async function isForgeHealthy(config, timeoutMs) {
         clearTimeout(timeout);
     }
 }
-function spawnManagedRuntime(config, plan) {
-    const isPackagedServer = plan.entryFile.endsWith(path.join("dist", "server", "index.js"));
+async function spawnManagedRuntime(config, plan) {
+    const isPackagedServer = isPackagedServerPlan(plan);
     const args = isPackagedServer ? [plan.entryFile] : [plan.entryFile, path.join(plan.packageRoot, "server", "src", "index.ts")];
+    const logPath = getRuntimeLogPath(config);
+    const logFd = openRuntimeLogFile(logPath);
     const child = spawn(process.execPath, args, {
         cwd: plan.packageRoot,
         env: {
@@ -137,11 +286,20 @@ function spawnManagedRuntime(config, plan) {
             FORGE_BASE_PATH: "/forge/",
             ...(config.dataRoot ? { FORGE_DATA_ROOT: config.dataRoot } : {})
         },
-        stdio: "ignore",
+        stdio: ["ignore", logFd, logFd],
         detached: true
     });
+    closeSync(logFd);
     child.unref();
-    child.once("exit", () => {
+    managedRuntimeLogPath = logPath;
+    lastRuntimeExitDetails = null;
+    child.once("exit", (code, signal) => {
+        lastRuntimeExitDetails = {
+            pid: child.pid ?? -1,
+            code,
+            signal,
+            logPath
+        };
         if (managedRuntimeChild === child) {
             managedRuntimeChild = null;
             managedRuntimeKey = null;
@@ -150,19 +308,46 @@ function spawnManagedRuntime(config, plan) {
     });
     managedRuntimeChild = child;
     managedRuntimeKey = runtimeKey(config);
-    void writeRuntimeState(config, child.pid).catch(() => {
-        // State tracking is best effort. Runtime health checks remain authoritative.
-    });
+    try {
+        await writeRuntimeState(config, child.pid);
+    }
+    catch (error) {
+        managedRuntimeChild = null;
+        managedRuntimeKey = null;
+        try {
+            process.kill(child.pid, "SIGTERM");
+        }
+        catch {
+            // If the child already exited we still want to surface the state-write failure.
+        }
+        throw new Error(`Forge local runtime started on ${config.baseUrl}, but the plugin could not persist its state. ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function formatRuntimeFailure(details, config) {
+    if (!details) {
+        return `Forge local runtime did not become healthy at ${config.baseUrl} within ${STARTUP_TIMEOUT_MS}ms`;
+    }
+    const suffix = details.logPath ? ` Check logs at ${details.logPath}.` : "";
+    if (details.signal) {
+        return `Forge local runtime exited before becoming healthy at ${config.baseUrl} (signal ${details.signal}).${suffix}`;
+    }
+    if (typeof details.code === "number") {
+        return `Forge local runtime exited before becoming healthy at ${config.baseUrl} (code ${details.code}).${suffix}`;
+    }
+    return `Forge local runtime exited before becoming healthy at ${config.baseUrl}.${suffix}`;
 }
-async function waitForRuntime(config, timeoutMs) {
+async function waitForRuntime(config, timeoutMs, expectedPid) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
         if (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS)) {
             return;
         }
+        if (expectedPid !== null && lastRuntimeExitDetails?.pid === expectedPid) {
+            throw new Error(formatRuntimeFailure(lastRuntimeExitDetails, config));
+        }
         await new Promise((resolve) => setTimeout(resolve, HEALTHCHECK_INTERVAL_MS));
     }
-    throw new Error(`Forge local runtime did not become healthy at ${config.baseUrl} within ${timeoutMs}ms`);
+    throw new Error(formatRuntimeFailure(lastRuntimeExitDetails, config));
 }
 export async function ensureForgeRuntimeReady(config) {
     if (!isLocalOrigin(config.origin)) {
@@ -171,8 +356,21 @@ export async function ensureForgeRuntimeReady(config) {
     if (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS)) {
         return;
     }
+    const savedState = await readRuntimeState(config);
+    if (savedState && !processExists(savedState.pid)) {
+        await clearRuntimeState(config);
+    }
+    else if (savedState && processExists(savedState.pid)) {
+        try {
+            await waitForRuntime(config, EXISTING_RUNTIME_GRACE_MS, null);
+            return;
+        }
+        catch {
+            await stopForgeRuntime(config);
+        }
+    }
     const key = runtimeKey(config);
-    if (startupPromise && managedRuntimeKey === key) {
+    if (startupPromise && (startupRuntimeKey === null || startupRuntimeKey === key)) {
         return startupPromise;
     }
     const plan = resolveLaunchPlan();
@@ -183,12 +381,22 @@ export async function ensureForgeRuntimeReady(config) {
         if (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS)) {
             return;
         }
+        startupRuntimeKey = runtimeKey(config);
+        if (!(await isPortAvailable("127.0.0.1", config.port))) {
+            await relocateLocalRuntimePort(config);
+            startupRuntimeKey = runtimeKey(config);
+            if (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS)) {
+                return;
+            }
+        }
+        await ensurePackagedRuntimeDependencies(plan, config);
         if (!managedRuntimeChild || managedRuntimeKey !== key || managedRuntimeChild.killed) {
-            spawnManagedRuntime(config, plan);
+            await spawnManagedRuntime(config, plan);
         }
-        await waitForRuntime(config, STARTUP_TIMEOUT_MS);
+        await waitForRuntime(config, STARTUP_TIMEOUT_MS, managedRuntimeChild?.pid ?? null);
     })().finally(() => {
         startupPromise = null;
+        startupRuntimeKey = null;
     });
     return startupPromise;
 }
@@ -204,6 +412,16 @@ export async function startForgeRuntime(config) {
         };
     }
     const existingState = await readRuntimeState(config);
+    if (!existingState && (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))) {
+        return {
+            ok: true,
+            started: false,
+            managed: false,
+            message: `Forge is already running on ${config.baseUrl}, but it does not look like a plugin-managed runtime.`,
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
     if (existingState && processExists(existingState.pid) && (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))) {
         return {
             ok: true,
@@ -216,6 +434,16 @@ export async function startForgeRuntime(config) {
     }
     await ensureForgeRuntimeReady(config);
     const state = await readRuntimeState(config);
+    if (!state && (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))) {
+        return {
+            ok: true,
+            started: false,
+            managed: false,
+            message: `Forge is healthy on ${config.baseUrl}, but it does not look like a plugin-managed runtime.`,
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
     return {
         ok: true,
         started: true,

package/dist/openclaw/plugin-entry-shared.js

@@ -1,3 +1,6 @@
+import { existsSync, readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
 import { buildForgeBaseUrl, buildForgeWebAppUrl } from "./api-client.js";
 import { primeForgeRuntime } from "./local-runtime.js";
 import { registerForgePluginCli, registerForgePluginRoutes } from "./routes.js";
@@ -7,6 +10,7 @@ export const FORGE_PLUGIN_NAME = "Forge";
 export const FORGE_PLUGIN_DESCRIPTION = "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.";
 export const DEFAULT_FORGE_ORIGIN = "http://127.0.0.1";
 export const DEFAULT_FORGE_PORT = 4317;
+const LOCAL_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1"]);
 function normalizeString(value, fallback) {
     return typeof value === "string" && value.trim().length > 0 ? value.trim() : fallback;
 }
@@ -36,15 +40,46 @@ function normalizeTimeout(value, fallback) {
     }
     return Math.min(120_000, Math.max(1000, Math.round(value)));
 }
+function isLocalOrigin(origin) {
+    try {
+        return LOCAL_HOSTNAMES.has(new URL(origin).hostname.toLowerCase());
+    }
+    catch {
+        return false;
+    }
+}
+function getPreferredLocalPortPath(origin) {
+    const hostname = new URL(origin).hostname.toLowerCase().replace(/[^a-z0-9._-]+/g, "-");
+    return path.join(homedir(), ".openclaw", "run", FORGE_PLUGIN_ID, `${hostname}-preferred-port.json`);
+}
+function readPreferredLocalPort(origin) {
+    if (!isLocalOrigin(origin)) {
+        return null;
+    }
+    try {
+        const preferredPortPath = getPreferredLocalPortPath(origin);
+        if (!existsSync(preferredPortPath)) {
+            return null;
+        }
+        const payload = JSON.parse(readFileSync(preferredPortPath, "utf8"));
+        return typeof payload.port === "number" && Number.isFinite(payload.port) ? payload.port : null;
+    }
+    catch {
+        return null;
+    }
+}
 export function resolveForgePluginConfig(pluginConfig) {
     const raw = (pluginConfig ?? {});
     const origin = normalizeOrigin(raw.origin, DEFAULT_FORGE_ORIGIN);
-    const port = normalizePort(raw.port, DEFAULT_FORGE_PORT);
+    const hasConfiguredPort = typeof raw.port === "number" && Number.isFinite(raw.port);
+    const preferredPort = hasConfiguredPort ? null : readPreferredLocalPort(origin);
+    const port = normalizePort(hasConfiguredPort ? raw.port : preferredPort ?? DEFAULT_FORGE_PORT, DEFAULT_FORGE_PORT);
     return {
         origin,
         port,
         baseUrl: buildForgeBaseUrl(origin, port),
         webAppUrl: buildForgeWebAppUrl(origin, port),
+        portSource: hasConfiguredPort ? "configured" : preferredPort !== null ? "preferred" : "default",
         dataRoot: typeof raw.dataRoot === "string" ? raw.dataRoot.trim() : "",
         apiToken: typeof raw.apiToken === "string" ? raw.apiToken.trim() : "",
         actorLabel: normalizeString(raw.actorLabel, "aurel"),
@@ -69,7 +104,7 @@ export const forgePluginConfigSchema = {
                 default: DEFAULT_FORGE_PORT,
                 minimum: 1,
                 maximum: 65535,
-                description: "Forge server port. Override this when your local machine uses a different port."
+                description: "Forge server port. Override this only when you want to pin a specific port. Default localhost installs can move to the next free port automatically if 4317 is already taken."
             },
             dataRoot: {
                 type: "string",
@@ -103,7 +138,7 @@ export const forgePluginConfigSchema = {
         },
         port: {
             label: "Forge Port",
-            help: "Forge server port. Change this if your local machine uses another port.",
+            help: "Forge server port. Change this only when you want to pin a specific port. Default localhost installs can move to the next free port automatically if 4317 is busy.",
             placeholder: "4317"
         },
         dataRoot: {

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "forge-openclaw-plugin",
   "name": "Forge",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
-  "version": "0.2.12",
+  "version": "0.2.15",
   "skills": [
     "./skills"
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "forge-openclaw-plugin",
-  "version": "0.2.12",
+  "version": "0.2.15",
   "description": "Curated OpenClaw adapter for the Forge collaboration API, UI entrypoint, and localhost auto-start runtime.",
   "type": "module",
   "license": "MIT",