forge-openclaw-plugin 0.2.10 → 0.2.12

package/README.md

@@ -72,21 +72,22 @@ Current OpenClaw builds should use package discovery:
 
 ```bash
 openclaw plugins install forge-openclaw-plugin
-openclaw gateway restart
-```
-
-If your OpenClaw install does not enable it automatically, run:
-
-```bash
 openclaw plugins enable forge-openclaw-plugin
+node -e 'const fs=require("fs"); const p=process.env.HOME+"/.openclaw/openclaw.json"; const j=JSON.parse(fs.readFileSync(p,"utf8")); j.plugins ??= {}; j.plugins.allow = Array.from(new Set([...(j.plugins.allow || []), "forge-openclaw-plugin"])); fs.writeFileSync(p, JSON.stringify(j, null, 2)+"\n");'
 openclaw gateway restart
+openclaw forge health
 ```
 
+`openclaw plugins enable forge-openclaw-plugin` marks the plugin enabled, but it does not guarantee that `plugins.allow` was repaired. The `node -e ...` command above preserves the current allow list and appends `"forge-openclaw-plugin"` if it is missing.
+
 For release-parity local development from this repo:
 
 ```bash
 openclaw plugins install ./projects/forge/openclaw-plugin
+openclaw plugins enable forge-openclaw-plugin
+node -e 'const fs=require("fs"); const p=process.env.HOME+"/.openclaw/openclaw.json"; const j=JSON.parse(fs.readFileSync(p,"utf8")); j.plugins ??= {}; j.plugins.allow = Array.from(new Set([...(j.plugins.allow || []), "forge-openclaw-plugin"])); fs.writeFileSync(p, JSON.stringify(j, null, 2)+"\n");'
 openclaw gateway restart
+openclaw forge health
 ```
 
 Equivalent config:
@@ -202,6 +203,17 @@ The skill is entity-format-driven. It teaches the agent how to:
 
 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.
 
+If you want to manage that plugin-managed local runtime cleanly, use:
+
+```bash
+openclaw forge start
+openclaw forge stop
+openclaw forge restart
+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.
+
 ## Publishing and listing
 
 The reliable publication path for the Forge plugin is:

package/dist/openclaw/local-runtime.d.ts

@@ -1,3 +1,39 @@
 import type { ForgePluginConfig } from "./api-client.js";
+export type ForgeRuntimeStopResult = {
+    ok: boolean;
+    stopped: boolean;
+    managed: boolean;
+    message: string;
+    pid: number | null;
+};
+export type ForgeRuntimeStartResult = {
+    ok: boolean;
+    started: boolean;
+    managed: boolean;
+    message: string;
+    pid: number | null;
+    baseUrl: string;
+};
+export type ForgeRuntimeStatusResult = {
+    ok: boolean;
+    running: boolean;
+    healthy: boolean;
+    managed: boolean;
+    message: string;
+    pid: number | null;
+    baseUrl: string;
+};
+export type ForgeRuntimeRestartResult = {
+    ok: boolean;
+    restarted: boolean;
+    managed: boolean;
+    message: string;
+    pid: number | null;
+    baseUrl: string;
+};
 export declare function ensureForgeRuntimeReady(config: ForgePluginConfig): Promise<void>;
+export declare function startForgeRuntime(config: ForgePluginConfig): Promise<ForgeRuntimeStartResult>;
 export declare function primeForgeRuntime(config: ForgePluginConfig): void;
+export declare function stopForgeRuntime(config: ForgePluginConfig): Promise<ForgeRuntimeStopResult>;
+export declare function getForgeRuntimeStatus(config: ForgePluginConfig): Promise<ForgeRuntimeStatusResult>;
+export declare function restartForgeRuntime(config: ForgePluginConfig): Promise<ForgeRuntimeRestartResult>;

package/dist/openclaw/local-runtime.js

@@ -1,6 +1,8 @@
 import { spawn } from "node:child_process";
 import { existsSync } from "node:fs";
+import { homedir } from "node:os";
 import path from "node:path";
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
 import { fileURLToPath } from "node:url";
 const LOCAL_HOSTNAMES = new Set(["127.0.0.1", "localhost", "::1"]);
 const STARTUP_TIMEOUT_MS = 15_000;
@@ -12,6 +14,63 @@ let startupPromise = null;
 function runtimeKey(config) {
     return `${config.origin}:${config.port}`;
 }
+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`);
+}
+async function writeRuntimeState(config, pid) {
+    const statePath = getRuntimeStatePath(config);
+    await mkdir(path.dirname(statePath), { recursive: true });
+    const payload = {
+        pid,
+        origin: config.origin,
+        port: config.port,
+        baseUrl: config.baseUrl,
+        startedAt: new Date().toISOString()
+    };
+    await writeFile(statePath, `${JSON.stringify(payload, null, 2)}\n`, "utf8");
+}
+async function clearRuntimeState(config) {
+    await rm(getRuntimeStatePath(config), { force: true });
+}
+async function readRuntimeState(config) {
+    try {
+        const payload = await readFile(getRuntimeStatePath(config), "utf8");
+        const parsed = JSON.parse(payload);
+        if (typeof parsed.pid !== "number" || !Number.isFinite(parsed.pid)) {
+            return null;
+        }
+        return {
+            pid: Math.trunc(parsed.pid),
+            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()
+        };
+    }
+    catch {
+        return null;
+    }
+}
+function processExists(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return !(error instanceof Error) || !("code" in error) || error.code !== "ESRCH";
+    }
+}
+async function waitForProcessExit(pid, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (!processExists(pid)) {
+            return true;
+        }
+        await new Promise((resolve) => setTimeout(resolve, HEALTHCHECK_INTERVAL_MS));
+    }
+    return !processExists(pid);
+}
 function isLocalOrigin(origin) {
     try {
         return LOCAL_HOSTNAMES.has(new URL(origin).hostname.toLowerCase());
@@ -87,9 +146,13 @@ function spawnManagedRuntime(config, plan) {
             managedRuntimeChild = null;
             managedRuntimeKey = null;
         }
+        void clearRuntimeState(config);
     });
     managedRuntimeChild = child;
     managedRuntimeKey = runtimeKey(config);
+    void writeRuntimeState(config, child.pid).catch(() => {
+        // State tracking is best effort. Runtime health checks remain authoritative.
+    });
 }
 async function waitForRuntime(config, timeoutMs) {
     const deadline = Date.now() + timeoutMs;
@@ -129,8 +192,207 @@ export async function ensureForgeRuntimeReady(config) {
     });
     return startupPromise;
 }
+export async function startForgeRuntime(config) {
+    if (!isLocalOrigin(config.origin)) {
+        return {
+            ok: false,
+            started: false,
+            managed: false,
+            message: "Forge start only supports local plugin-managed runtimes. Remote Forge targets must be started where they are hosted.",
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    const existingState = await readRuntimeState(config);
+    if (existingState && processExists(existingState.pid) && (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))) {
+        return {
+            ok: true,
+            started: false,
+            managed: true,
+            message: `Forge is already running on ${config.baseUrl}.`,
+            pid: existingState.pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    await ensureForgeRuntimeReady(config);
+    const state = await readRuntimeState(config);
+    return {
+        ok: true,
+        started: true,
+        managed: true,
+        message: `Started the plugin-managed Forge runtime on ${config.baseUrl}.`,
+        pid: state?.pid ?? managedRuntimeChild?.pid ?? null,
+        baseUrl: config.baseUrl
+    };
+}
 export function primeForgeRuntime(config) {
     void ensureForgeRuntimeReady(config).catch(() => {
         // Keep plugin registration non-blocking. Failures surface on first real call.
     });
 }
+export async function stopForgeRuntime(config) {
+    if (!isLocalOrigin(config.origin)) {
+        return {
+            ok: false,
+            stopped: false,
+            managed: false,
+            message: "Forge stop only supports local plugin-managed runtimes. Remote Forge targets must be stopped where they are hosted.",
+            pid: null
+        };
+    }
+    const state = await readRuntimeState(config);
+    if (!state) {
+        return {
+            ok: true,
+            stopped: false,
+            managed: false,
+            message: (await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS))
+                ? "Forge is running, but it does not look like a plugin-managed runtime. Stop it where it was started."
+                : "Forge is not running through the plugin-managed local runtime.",
+            pid: null
+        };
+    }
+    if (!processExists(state.pid)) {
+        await clearRuntimeState(config);
+        return {
+            ok: true,
+            stopped: false,
+            managed: true,
+            message: "The saved Forge runtime PID was stale. The plugin-managed runtime is already stopped.",
+            pid: state.pid
+        };
+    }
+    process.kill(state.pid, "SIGTERM");
+    if (!(await waitForProcessExit(state.pid, 5_000))) {
+        process.kill(state.pid, "SIGKILL");
+        if (!(await waitForProcessExit(state.pid, 2_000))) {
+            return {
+                ok: false,
+                stopped: false,
+                managed: true,
+                message: `Forge runtime pid ${state.pid} did not stop cleanly.`,
+                pid: state.pid
+            };
+        }
+    }
+    if (managedRuntimeChild?.pid === state.pid) {
+        managedRuntimeChild = null;
+        managedRuntimeKey = null;
+    }
+    await clearRuntimeState(config);
+    return {
+        ok: true,
+        stopped: true,
+        managed: true,
+        message: `Stopped the plugin-managed Forge runtime on ${config.baseUrl}.`,
+        pid: state.pid
+    };
+}
+export async function getForgeRuntimeStatus(config) {
+    const healthy = await isForgeHealthy(config, HEALTHCHECK_TIMEOUT_MS);
+    const state = await readRuntimeState(config);
+    const pid = state?.pid ?? null;
+    const managed = Boolean(state);
+    const running = healthy || (pid !== null && processExists(pid));
+    if (!isLocalOrigin(config.origin)) {
+        return {
+            ok: healthy,
+            running: healthy,
+            healthy,
+            managed: false,
+            message: healthy
+                ? `Forge is reachable at ${config.baseUrl}. Runtime lifecycle is managed remotely.`
+                : `Forge is not reachable at ${config.baseUrl}. Runtime lifecycle is managed remotely.`,
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    if (managed && pid !== null && !processExists(pid)) {
+        await clearRuntimeState(config);
+        return {
+            ok: true,
+            running: false,
+            healthy: false,
+            managed: true,
+            message: "The saved Forge runtime PID was stale. The plugin-managed runtime is stopped.",
+            pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    if (healthy && managed) {
+        return {
+            ok: true,
+            running: true,
+            healthy: true,
+            managed: true,
+            message: `Forge is running and healthy on ${config.baseUrl}.`,
+            pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    if (healthy) {
+        return {
+            ok: true,
+            running: true,
+            healthy: true,
+            managed: false,
+            message: `Forge is running on ${config.baseUrl}, but it does not look like a plugin-managed runtime.`,
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    if (managed) {
+        return {
+            ok: true,
+            running: false,
+            healthy: false,
+            managed: true,
+            message: "The plugin-managed Forge runtime is stopped.",
+            pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    return {
+        ok: true,
+        running: false,
+        healthy: false,
+        managed: false,
+        message: "Forge is not running through the plugin-managed local runtime.",
+        pid: null,
+        baseUrl: config.baseUrl
+    };
+}
+export async function restartForgeRuntime(config) {
+    if (!isLocalOrigin(config.origin)) {
+        return {
+            ok: false,
+            restarted: false,
+            managed: false,
+            message: "Forge restart only supports local plugin-managed runtimes. Remote Forge targets must be restarted where they are hosted.",
+            pid: null,
+            baseUrl: config.baseUrl
+        };
+    }
+    const stopResult = await stopForgeRuntime(config);
+    if (!stopResult.ok) {
+        return {
+            ok: false,
+            restarted: false,
+            managed: stopResult.managed,
+            message: stopResult.message,
+            pid: stopResult.pid,
+            baseUrl: config.baseUrl
+        };
+    }
+    const startResult = await startForgeRuntime(config);
+    return {
+        ok: startResult.ok,
+        restarted: startResult.ok,
+        managed: true,
+        message: startResult.ok
+            ? `Restarted the plugin-managed Forge runtime on ${config.baseUrl}.`
+            : startResult.message,
+        pid: startResult.pid,
+        baseUrl: config.baseUrl
+    };
+}

package/dist/openclaw/routes.js

@@ -1,4 +1,5 @@
 import { canBootstrapOperatorSession, callConfiguredForgeApi, expectForgeSuccess, readJsonRequestBody, readSingleHeaderValue, requireApiToken, writeForgeProxyResponse, writePluginError, writeRedirectResponse } from "./api-client.js";
+import { getForgeRuntimeStatus, restartForgeRuntime, startForgeRuntime, stopForgeRuntime } from "./local-runtime.js";
 import { collectSupportedPluginApiRouteKeys, makeApiRouteKey } from "./parity.js";
 function passthroughSearch(path, url) {
     return `${path}${url.search}`;
@@ -374,6 +375,18 @@ export function registerForgePluginCli(api, config) {
         command.command("ui").description("Print the Forge UI entrypoint").action(async () => {
             console.log(JSON.stringify({ webAppUrl: await resolveForgeUiUrl(config), pluginUiRoute: "/forge/v1/ui" }, null, 2));
         });
+        command.command("start").description("Start the local Forge runtime when it is managed by the OpenClaw plugin").action(async () => {
+            console.log(JSON.stringify(await startForgeRuntime(config), null, 2));
+        });
+        command.command("stop").description("Stop the local Forge runtime when it was auto-started by the OpenClaw plugin").action(async () => {
+            console.log(JSON.stringify(await stopForgeRuntime(config), null, 2));
+        });
+        command.command("restart").description("Restart the local Forge runtime when it is managed by the OpenClaw plugin").action(async () => {
+            console.log(JSON.stringify(await restartForgeRuntime(config), null, 2));
+        });
+        command.command("status").description("Report whether the local Forge runtime is running and whether it is plugin-managed").action(async () => {
+            console.log(JSON.stringify(await getForgeRuntimeStatus(config), null, 2));
+        });
         command.command("doctor").description("Run plugin connectivity and curated route diagnostics").action(async () => {
             console.log(JSON.stringify(await runDoctor(config), null, 2));
         });

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.10",
+  "version": "0.2.12",
   "skills": [
     "./skills"
   ],

package/package.json

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

package/skills/forge-openclaw/SKILL.md

@@ -16,6 +16,8 @@ Forge data location rule:
 - on a linked repo-local install, this usually means `<repo>/openclaw-plugin/data/forge.sqlite`
 - if the user wants the data somewhere else for persistence, backup, or manual control, tell them to set `plugins.entries["forge-openclaw-plugin"].config.dataRoot` and restart the OpenClaw gateway
 - if the user asks where the data is stored or how to move it, explain the current default plainly and show the exact config field
+- if the user wants to manage a plugin-managed local Forge runtime cleanly, tell them to run `openclaw forge start`, `openclaw forge stop`, `openclaw forge restart`, or `openclaw forge status`
+- these commands only manage a runtime that the OpenClaw plugin auto-started itself; if Forge was started manually elsewhere, they will say so instead of killing random local processes
 
 Use these exact entity meanings when deciding what the user is describing.