clawjobs 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,42 @@
+# ClawJobs
+
+ClawJobs is an OpenClaw plugin for peer-powered task collaboration.
+
+The assignee contributes reasoning on their own machine, while every real command still executes on the task owner's machine.
+
+## Install
+
+```bash
+openclaw plugins install clawjobs
+openclaw config set plugins.allow '["clawjobs"]' --strict-json
+openclaw config set plugins.entries.clawjobs.enabled true
+```
+
+Then write `plugins.entries.clawjobs.config`.
+
+## Minimal config
+
+```json
+{
+  "hubUrl": "https://your-hub.example.com",
+  "hubToken": "your-shared-token",
+  "nickname": "Your Nickname",
+  "workspaceDir": "/your/workspace"
+}
+```
+
+## Task page
+
+```text
+http://127.0.0.1:18789/plugins/clawjobs
+```
+
+## Requirements
+
+- every participating machine installs the plugin
+- one central hub is reachable by all peers
+- the assignee machine has a usable OpenClaw model configuration
+
+## License
+
+MIT

package/README_CN.md

@@ -0,0 +1,42 @@
+# ClawJobs
+
+`ClawJobs` 是一个 `OpenClaw` 插件，用来做多台小龙虾之间的任务协作。
+
+接单人负责推理，真实命令始终只在任务发起人的本机执行。
+
+## 安装
+
+```bash
+openclaw plugins install clawjobs
+openclaw config set plugins.allow '["clawjobs"]' --strict-json
+openclaw config set plugins.entries.clawjobs.enabled true
+```
+
+然后写入 `plugins.entries.clawjobs.config`。
+
+## 最小配置
+
+```json
+{
+  "hubUrl": "https://你的-hub-地址",
+  "hubToken": "共享口令",
+  "nickname": "你的昵称",
+  "workspaceDir": "/你的工作目录"
+}
+```
+
+## 任务页
+
+```text
+http://127.0.0.1:18789/plugins/clawjobs
+```
+
+## 依赖
+
+- 每台参与机器都安装插件
+- 所有机器都能访问同一个中心 hub
+- 接单机器本地有可用的 OpenClaw 模型配置
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,4 @@
+import register from "./src/plugin.js";
+
+export default register;
+

package/openclaw.plugin.json

@@ -0,0 +1,95 @@
+{
+  "id": "clawjobs",
+  "name": "ClawJobs",
+  "description": "Peer-powered jobs for OpenClaw, with remote reasoning and owner-side execution.",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "hubUrl": {
+        "type": "string"
+      },
+      "hubToken": {
+        "type": "string"
+      },
+      "nickname": {
+        "type": "string"
+      },
+      "peerId": {
+        "type": "string"
+      },
+      "workspaceDir": {
+        "type": "string"
+      },
+      "brain": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "provider": {
+            "type": "string"
+          },
+          "model": {
+            "type": "string"
+          },
+          "maxSteps": {
+            "type": "number"
+          },
+          "timeoutMs": {
+            "type": "number"
+          }
+        }
+      },
+      "execution": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "defaultCwd": {
+            "type": "string"
+          },
+          "maxCommandMs": {
+            "type": "number"
+          },
+          "maxOutputChars": {
+            "type": "number"
+          }
+        }
+      }
+    }
+  },
+  "uiHints": {
+    "hubUrl": {
+      "label": "Hub URL"
+    },
+    "hubToken": {
+      "label": "Hub Token",
+      "sensitive": true
+    },
+    "nickname": {
+      "label": "Nickname"
+    },
+    "workspaceDir": {
+      "label": "Default Workspace"
+    },
+    "brain.provider": {
+      "label": "Brain Provider"
+    },
+    "brain.model": {
+      "label": "Brain Model"
+    },
+    "brain.maxSteps": {
+      "label": "Max Reasoning Steps"
+    },
+    "brain.timeoutMs": {
+      "label": "Reasoning Timeout (ms)"
+    },
+    "execution.defaultCwd": {
+      "label": "Default Execution CWD"
+    },
+    "execution.maxCommandMs": {
+      "label": "Command Timeout (ms)"
+    },
+    "execution.maxOutputChars": {
+      "label": "Max Output Characters"
+    }
+  }
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "clawjobs",
+  "version": "0.2.0",
+  "description": "Peer-powered jobs for OpenClaw: remote reasoning with execution kept on the task owner's machine.",
+  "private": false,
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "openclaw",
+    "plugin",
+    "clawjobs",
+    "peer-to-peer",
+    "tasks",
+    "local-execution"
+  ],
+  "openclaw": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "files": [
+    "index.ts",
+    "openclaw.plugin.json",
+    "src",
+    "README.md",
+    "README_CN.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/gtoadio-cyber/openclaw-clawjobs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/gtoadio-cyber/openclaw-clawjobs/issues"
+  },
+  "homepage": "https://github.com/gtoadio-cyber/openclaw-clawjobs#readme"
+}

package/src/json-agent.ts

@@ -0,0 +1,290 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { spawnSync } from "node:child_process";
+
+type RunJsonTaskParams = {
+  api: {
+    config: Record<string, unknown>;
+    logger: {
+      warn: (message: string) => void;
+    };
+  };
+  workspaceDir: string;
+  provider?: string;
+  model?: string;
+  authProfileId?: string;
+  timeoutMs: number;
+  prompt: string;
+  input: unknown;
+};
+
+export type BrainDecision =
+  | {
+      action: "owner_exec";
+      note: string;
+      command: string;
+      cwd?: string | null;
+      timeoutMs?: number;
+    }
+  | {
+      action: "finish";
+      note: string;
+      resultText: string;
+    }
+  | {
+      action: "fail";
+      note: string;
+      errorText: string;
+    };
+
+type RunEmbeddedPiAgentFn = (params: Record<string, unknown>) => Promise<{
+  payloads?: Array<{ text?: string; isError?: boolean }>;
+}>;
+
+function collectAssistantText(payloads: Array<{ text?: string; isError?: boolean }> | undefined) {
+  return (payloads || [])
+    .filter((item) => !item.isError && typeof item.text === "string")
+    .map((item) => item.text || "")
+    .join("\n")
+    .trim();
+}
+
+function stripCodeFence(value: string) {
+  const trimmed = value.trim();
+  const matched = trimmed.match(/^```(?:json)?\s*([\s\S]*?)\s*```$/i);
+  return matched ? (matched[1] || "").trim() : trimmed;
+}
+
+function validateDecision(value: unknown): BrainDecision {
+  if (!value || typeof value !== "object") {
+    throw new Error("The model did not return an object.");
+  }
+  const action = typeof value.action === "string" ? value.action : "";
+  const note = typeof value.note === "string" ? value.note.trim() : "";
+  if (!note) {
+    throw new Error("The model response is missing note.");
+  }
+  if (action === "owner_exec") {
+    const command = typeof value.command === "string" ? value.command.trim() : "";
+    if (!command) {
+      throw new Error("owner_exec is missing command.");
+    }
+    return {
+      action,
+      note,
+      command,
+      cwd: typeof value.cwd === "string" ? value.cwd : null,
+      timeoutMs:
+        typeof value.timeoutMs === "number" && Number.isFinite(value.timeoutMs)
+          ? value.timeoutMs
+          : undefined,
+    };
+  }
+  if (action === "finish") {
+    const resultText = typeof value.resultText === "string" ? value.resultText.trim() : "";
+    if (!resultText) {
+      throw new Error("finish is missing resultText.");
+    }
+    return {
+      action,
+      note,
+      resultText,
+    };
+  }
+  if (action === "fail") {
+    const errorText = typeof value.errorText === "string" ? value.errorText.trim() : "";
+    if (!errorText) {
+      throw new Error("fail is missing errorText.");
+    }
+    return {
+      action,
+      note,
+      errorText,
+    };
+  }
+  throw new Error(`Unknown action: ${action || "<empty>"}`);
+}
+
+async function pathExists(targetPath: string) {
+  try {
+    await fs.access(targetPath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function addCandidate(candidatePaths: Set<string>, basePath: string) {
+  const normalizedBase = path.resolve(basePath);
+  let current = normalizedBase;
+
+  while (true) {
+    candidatePaths.add(path.join(current, "dist", "extensionAPI.js"));
+    const parent = path.dirname(current);
+    if (parent === current) {
+      break;
+    }
+    current = parent;
+  }
+}
+
+async function tryAddRealPathCandidates(candidatePaths: Set<string>, inputPath: string) {
+  if (!inputPath || typeof inputPath !== "string") {
+    return;
+  }
+  try {
+    const realPath = await fs.realpath(inputPath);
+    addCandidate(candidatePaths, path.dirname(realPath));
+  } catch {
+    addCandidate(candidatePaths, path.dirname(inputPath));
+  }
+}
+
+function resolveCliPathFromShell() {
+  const lookup = process.platform === "win32" ? "where" : "which";
+  const result = spawnSync(lookup, ["openclaw"], {
+    encoding: "utf8",
+    windowsHide: true,
+  });
+  if (result.status !== 0) {
+    return null;
+  }
+  const firstLine = String(result.stdout || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .find(Boolean);
+  return firstLine || null;
+}
+
+async function resolveExtensionApiPath(): Promise<string> {
+  const candidatePaths = new Set<string>();
+
+  for (const runtimePath of [process.argv[1], process.execPath]) {
+    if (!runtimePath || typeof runtimePath !== "string") {
+      continue;
+    }
+    await tryAddRealPathCandidates(candidatePaths, runtimePath);
+  }
+
+  const cliPath = resolveCliPathFromShell();
+  if (cliPath) {
+    await tryAddRealPathCandidates(candidatePaths, cliPath);
+  }
+
+  for (const candidatePath of candidatePaths) {
+    if (await pathExists(candidatePath)) {
+      return candidatePath;
+    }
+  }
+
+  throw new Error("Unable to locate OpenClaw extensionAPI.js.");
+}
+
+async function loadRunEmbeddedPiAgent(): Promise<RunEmbeddedPiAgentFn> {
+  const extensionApiPath = await resolveExtensionApiPath();
+  const mod = (await import(pathToFileURL(extensionApiPath).href)) as {
+    runEmbeddedPiAgent?: unknown;
+  };
+  if (typeof mod.runEmbeddedPiAgent !== "function") {
+    throw new Error("OpenClaw extensionAPI does not expose runEmbeddedPiAgent.");
+  }
+  return mod.runEmbeddedPiAgent as RunEmbeddedPiAgentFn;
+}
+
+export async function runJsonTask(params: RunJsonTaskParams): Promise<BrainDecision> {
+  const inputJson = JSON.stringify(params.input ?? null, null, 2);
+  const schemaText = JSON.stringify(
+    {
+      type: "object",
+      additionalProperties: false,
+      required: ["action", "note"],
+      properties: {
+        action: {
+          type: "string",
+          enum: ["owner_exec", "finish", "fail"],
+        },
+        note: {
+          type: "string",
+        },
+        command: {
+          type: "string",
+        },
+        cwd: {
+          type: ["string", "null"],
+        },
+        timeoutMs: {
+          type: "number",
+        },
+        resultText: {
+          type: "string",
+        },
+        errorText: {
+          type: "string",
+        },
+      },
+    },
+    null,
+    2,
+  );
+
+  const prompt = [
+    "You are the assignee brain for a remote ClawJobs task.",
+    "You cannot execute commands yourself and you must not pretend that local execution already happened.",
+    "All real execution must be sent back to the task owner through owner_exec.",
+    "Return exactly one action at a time.",
+    "If more information is needed, return owner_exec.",
+    "If the answer is ready, return finish.",
+    "If the task cannot continue safely, return fail.",
+    "Return strict JSON only, with no markdown or extra commentary.",
+    "",
+    "TASK_PROMPT:",
+    params.prompt,
+    "",
+    "OUTPUT_SCHEMA_JSON:",
+    schemaText,
+    "",
+    "INPUT_JSON:",
+    inputJson,
+  ].join("\n");
+
+  const tmpDir = await fs.mkdtemp(path.join(process.env.TMPDIR || "/tmp", "clawjobs-"));
+  const sessionId = `clawjobs-${Date.now()}-${Math.random().toString(16).slice(2, 8)}`;
+  const sessionFile = path.join(tmpDir, "session.json");
+  const runEmbeddedPiAgent = await loadRunEmbeddedPiAgent();
+
+  try {
+    for (let attempt = 0; attempt < 2; attempt += 1) {
+      const runResult = await runEmbeddedPiAgent({
+        sessionId: `${sessionId}-${attempt}`,
+        sessionFile,
+        workspaceDir: params.workspaceDir,
+        config: params.api.config,
+        prompt:
+          attempt === 0
+            ? prompt
+            : `${prompt}\n\nYour last response was not valid JSON. Return valid JSON only this time.`,
+        timeoutMs: params.timeoutMs,
+        runId: `${sessionId}-run-${attempt}`,
+        provider: params.provider,
+        model: params.model,
+        authProfileId: params.authProfileId,
+        authProfileIdSource: params.authProfileId ? "user" : "auto",
+        disableTools: true,
+      });
+
+      const text = collectAssistantText(runResult.payloads);
+      if (!text) {
+        continue;
+      }
+      try {
+        return validateDecision(JSON.parse(stripCodeFence(text)));
+      } catch (error) {
+        params.api.logger.warn(`clawjobs json parse failed: ${error.message || String(error)}`);
+      }
+    }
+    throw new Error("The model returned invalid JSON twice in a row.");
+  } finally {
+    await fs.rm(tmpDir, { recursive: true, force: true }).catch(() => {});
+  }
+}