lobstah-openclaw-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 aequitas labs LLC
+
+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,15 @@
+# lobstah-openclaw-plugin
+
+OpenClaw plugin for [lobstah](https://www.npmjs.com/package/lobstah), the
+supervisor for local coding agents. Fleet agents get four tools —
+`lobstah_dispatch`, `lobstah_status`, `lobstah_send`, `lobstah_cancel` —
+and operators get a `/lobstah` chat command. Calls translate into the same
+file queue the CLI writes.
+
+Install into a gateway host that also runs `lobstah daemon`:
+
+```bash
+openclaw plugins install lobstah-openclaw-plugin
+```
+
+Docs: https://github.com/aequitas-labs/lobstah/blob/main/docs/openclaw.md

package/dist/index.js

@@ -0,0 +1,327 @@
+// apps/node/src/index.ts
+import { definePluginEntry } from "openclaw/plugin-sdk/core";
+
+// apps/node/src/tools.ts
+import * as fs6 from "node:fs";
+import * as path4 from "node:path";
+import { randomUUID } from "node:crypto";
+
+// packages/core/dist/types.js
+var VERBS = ["working", "needs-decision", "blocked", "paused", "done", "failed"];
+var TERMINAL_VERBS = ["done", "failed"];
+
+// packages/core/dist/paths.js
+import * as os from "node:os";
+import * as path from "node:path";
+import * as fs from "node:fs";
+function lobstahHome() {
+  return process.env.LOBSTAH_HOME ?? path.join(os.homedir(), ".lobstah");
+}
+function laneRoot(lane) {
+  return lane === "work" ? lobstahHome() : path.join(lobstahHome(), "chores");
+}
+function laneDirs(lane) {
+  const root = laneRoot(lane);
+  return {
+    queue: path.join(root, "queue"),
+    active: path.join(root, "active"),
+    done: path.join(root, "done"),
+    state: path.join(root, "state"),
+    inbox: path.join(root, "inbox")
+  };
+}
+function ensureLayout() {
+  for (const lane of ["work", "chore"]) {
+    for (const dir of Object.values(laneDirs(lane)))
+      fs.mkdirSync(dir, { recursive: true });
+  }
+  fs.mkdirSync(path.join(lobstahHome(), "worktrees"), { recursive: true });
+}
+function statusPath(id, lane) {
+  return path.join(laneDirs(lane).state, `${id}.status`);
+}
+function eventsPath(id, lane) {
+  return path.join(laneDirs(lane).state, `${id}.events`);
+}
+
+// packages/core/dist/queue.js
+import * as fs2 from "node:fs";
+import * as path2 from "node:path";
+function atomicWrite(file, content) {
+  const tmp = `${file}.tmp-${process.pid}-${Date.now()}`;
+  fs2.writeFileSync(tmp, content);
+  fs2.renameSync(tmp, file);
+}
+function enqueue(d, lane = "work") {
+  if (!d.id || !d.repo || !d.brief) {
+    throw new Error("descriptor requires id, repo, and brief");
+  }
+  atomicWrite(path2.join(laneDirs(lane).queue, `${d.id}.json`), JSON.stringify(d, null, 2));
+}
+function requestCancel(id, lane) {
+  fs2.writeFileSync(path2.join(laneDirs(lane).active, id, "cancel"), (/* @__PURE__ */ new Date()).toISOString());
+}
+
+// packages/core/dist/status.js
+import * as fs3 from "node:fs";
+function isVerb(v) {
+  return VERBS.includes(v);
+}
+function readStatusLog(id, lane) {
+  const file = statusPath(id, lane);
+  if (!fs3.existsSync(file))
+    return [];
+  return fs3.readFileSync(file, "utf8").split("\n").filter(Boolean).flatMap((line) => {
+    try {
+      const parsed = JSON.parse(line);
+      return isVerb(parsed.verb) ? [parsed] : [];
+    } catch {
+      return [];
+    }
+  });
+}
+function reconcile({ log, lastEventAt: lastEventAt2, now = Date.now(), busyThresholdMs = 12e4 }) {
+  const last = log[log.length - 1];
+  if (last && TERMINAL_VERBS.includes(last.verb))
+    return last.verb;
+  const busy = lastEventAt2 !== void 0 && now - lastEventAt2 < busyThresholdMs;
+  if (busy)
+    return last && last.verb !== "working" ? last.verb : "working";
+  if (last)
+    return last.verb;
+  return "unknown";
+}
+
+// packages/core/dist/events.js
+import * as fs4 from "node:fs";
+function lastEventAt(id, lane) {
+  try {
+    return fs4.statSync(eventsPath(id, lane)).mtimeMs;
+  } catch {
+    return void 0;
+  }
+}
+
+// packages/core/dist/inbox.js
+import * as fs5 from "node:fs";
+import * as path3 from "node:path";
+function inboxDir(id, lane) {
+  return path3.join(laneDirs(lane).inbox, id);
+}
+function sendMessage(id, lane, text2) {
+  const dir = inboxDir(id, lane);
+  fs5.mkdirSync(path3.join(dir, "handled"), { recursive: true });
+  const existing = fs5.readdirSync(dir).filter((f) => f.endsWith(".msg")).length;
+  const handled = fs5.readdirSync(path3.join(dir, "handled")).length;
+  const name = `${String(existing + handled + 1).padStart(3, "0")}.msg`;
+  const tmp = path3.join(dir, `.tmp-${process.pid}-${Date.now()}`);
+  fs5.writeFileSync(tmp, text2);
+  fs5.renameSync(tmp, path3.join(dir, name));
+  return name;
+}
+
+// packages/core/dist/toon.js
+function cell(v) {
+  if (v === void 0 || v === null)
+    return "";
+  const s = String(v);
+  return s.includes(",") || s.includes("\n") ? JSON.stringify(s) : s;
+}
+function toonKV(obj) {
+  return Object.entries(obj).filter(([, v]) => v !== void 0).map(([k, v]) => `${k}: ${cell(v)}`).join("\n");
+}
+function toonTable(name, rows, cols) {
+  const header = `${name}[${rows.length}]{${cols.join(",")}}:`;
+  if (rows.length === 0)
+    return header;
+  return [header, ...rows.map((r) => `  ${cols.map((c) => cell(r[c])).join(",")}`)].join("\n");
+}
+
+// apps/node/src/tools.ts
+function text(payload, details = {}) {
+  return { content: [{ type: "text", text: payload }], details };
+}
+function findLane(id) {
+  for (const lane of ["work", "chore"]) {
+    const d = laneDirs(lane);
+    if (fs6.existsSync(path4.join(d.active, id)) || fs6.existsSync(path4.join(d.queue, `${id}.json`)) || fs6.existsSync(path4.join(d.done, id)) || fs6.existsSync(path4.join(d.state, `${id}.status`))) {
+      return lane;
+    }
+  }
+  throw new Error(`unknown dispatch ${id}`);
+}
+function stateOf(id, lane) {
+  return reconcile({ log: readStatusLog(id, lane), lastEventAt: lastEventAt(id, lane) });
+}
+function param(params, key) {
+  const v = params[key];
+  return typeof v === "string" && v.length > 0 ? v : void 0;
+}
+function dispatchTool() {
+  return {
+    name: "lobstah_dispatch",
+    label: "Lobstah dispatch",
+    description: "Queue a supervised coding-agent dispatch on this host. The lobstah daemon claims it, allocates an isolated git worktree, runs the agent, and reports status to disk. Returns the dispatch id.",
+    parameters: {
+      type: "object",
+      properties: {
+        repo: { type: "string", description: "Lobstah repo key from the host config" },
+        brief: { type: "string", description: "The full work brief for the dispatched agent" },
+        harness: { type: "string", enum: ["claude", "codex"] },
+        model: { type: "string" },
+        effort: { type: "string" },
+        followUp: { type: "string", description: "Earlier dispatch UUID whose session to fork" }
+      },
+      required: ["repo", "brief"],
+      additionalProperties: false
+    },
+    async execute(_id, params) {
+      ensureLayout();
+      const repo = param(params, "repo");
+      const brief = param(params, "brief");
+      if (!repo || !brief) throw new Error("lobstah_dispatch requires repo and brief");
+      const d = {
+        id: randomUUID(),
+        repo,
+        brief,
+        harness: param(params, "harness"),
+        model: param(params, "model"),
+        effort: param(params, "effort"),
+        followUp: param(params, "followUp")
+      };
+      enqueue(d, "work");
+      return text(toonKV({ id: d.id, repo, queued: (/* @__PURE__ */ new Date()).toISOString() }), { id: d.id });
+    }
+  };
+}
+function statusTool() {
+  return {
+    name: "lobstah_status",
+    label: "Lobstah status",
+    description: "Reconciled state of one dispatch (by id) or every active dispatch on this host. States: working, needs-decision, blocked, paused, done, failed, unknown.",
+    parameters: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      additionalProperties: false
+    },
+    async execute(_id, params) {
+      ensureLayout();
+      const id = param(params, "id");
+      if (id) {
+        const lane = findLane(id);
+        const log = readStatusLog(id, lane);
+        const state = stateOf(id, lane);
+        return text(toonKV({ id, lane, state, lastNote: log.at(-1)?.note }), { id, state });
+      }
+      const rows = ["work", "chore"].flatMap(
+        (lane) => fs6.readdirSync(laneDirs(lane).active).filter((f) => !f.startsWith(".")).map((did) => ({ id: did, lane, state: stateOf(did, lane) }))
+      );
+      return text(toonTable("active", rows, ["id", "lane", "state"]), { count: rows.length });
+    }
+  };
+}
+function sendTool() {
+  return {
+    name: "lobstah_send",
+    label: "Lobstah send",
+    description: "Send an instruction to a running dispatch. Delivered into its inbox between agent turns.",
+    parameters: {
+      type: "object",
+      properties: { id: { type: "string" }, message: { type: "string" } },
+      required: ["id", "message"],
+      additionalProperties: false
+    },
+    async execute(_id, params) {
+      const id = param(params, "id");
+      const message = param(params, "message");
+      if (!id || !message) throw new Error("lobstah_send requires id and message");
+      const name = sendMessage(id, findLane(id), message);
+      return text(toonKV({ id, queued: name }), { id });
+    }
+  };
+}
+function cancelTool() {
+  return {
+    name: "lobstah_cancel",
+    label: "Lobstah cancel",
+    description: "Request cancellation of an active dispatch. The supervisor kills it between polls.",
+    parameters: {
+      type: "object",
+      properties: { id: { type: "string" } },
+      required: ["id"],
+      additionalProperties: false
+    },
+    async execute(_id, params) {
+      const id = param(params, "id");
+      if (!id) throw new Error("lobstah_cancel requires id");
+      requestCancel(id, findLane(id));
+      return text(toonKV({ id, cancel: "requested" }), { id });
+    }
+  };
+}
+
+// apps/node/src/index.ts
+var index_default = definePluginEntry({
+  id: "lobstah",
+  name: "Lobstah",
+  description: "Dispatch supervised local coding-agent work through the lobstah daemon on this host.",
+  register(api) {
+    api.registerTool(dispatchTool(), { optional: true });
+    api.registerTool(statusTool(), { optional: true });
+    api.registerTool(sendTool(), { optional: true });
+    api.registerTool(cancelTool(), { optional: true });
+    api.registerCommand({
+      name: "lobstah",
+      description: "Lobstah dispatch status on this host (/lobstah [id])",
+      acceptsArgs: true,
+      async handler(ctx) {
+        const tool = statusTool();
+        const arg = ctx.args?.trim();
+        const result = await tool.execute("cmd", arg ? { id: arg } : {});
+        return { text: result.content[0]?.text ?? "no output" };
+      }
+    });
+  }
+});
+export {
+  index_default as default
+};
+/*! Bundled license information:
+
+smol-toml/dist/date.js:
+smol-toml/dist/error.js:
+smol-toml/dist/util.js:
+smol-toml/dist/primitive.js:
+smol-toml/dist/extract.js:
+smol-toml/dist/struct.js:
+smol-toml/dist/parse.js:
+smol-toml/dist/stringify.js:
+smol-toml/dist/index.js:
+  (*!
+   * Copyright (c) Squirrel Chat et al., All rights reserved.
+   * SPDX-License-Identifier: BSD-3-Clause
+   *
+   * Redistribution and use in source and binary forms, with or without
+   * modification, are permitted provided that the following conditions are met:
+   *
+   * 1. Redistributions of source code must retain the above copyright notice, this
+   *    list of conditions and the following disclaimer.
+   * 2. Redistributions in binary form must reproduce the above copyright notice,
+   *    this list of conditions and the following disclaimer in the
+   *    documentation and/or other materials provided with the distribution.
+   * 3. Neither the name of the copyright holder nor the names of its contributors
+   *    may be used to endorse or promote products derived from this software without
+   *    specific prior written permission.
+   *
+   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
+   * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
+   * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
+   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
+   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
+   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
+   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+   *)
+*/

package/openclaw.plugin.json

@@ -0,0 +1,10 @@
+{
+  "id": "lobstah",
+  "name": "Lobstah",
+  "description": "Dispatch supervised local coding-agent work through the lobstah daemon on this host.",
+  "activation": { "onStartup": true },
+  "contracts": {
+    "tools": ["lobstah_dispatch", "lobstah_status", "lobstah_send", "lobstah_cancel"]
+  },
+  "configSchema": { "type": "object", "properties": {}, "additionalProperties": false }
+}

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "lobstah-openclaw-plugin",
+  "version": "0.1.0",
+  "description": "OpenClaw plugin for lobstah: gives fleet agents dispatch/status/send/cancel tools and operators a /lobstah command.",
+  "license": "MIT",
+  "author": "aequitas labs LLC",
+  "type": "module",
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "openclaw.plugin.json",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "openclaw",
+    "openclaw-plugin",
+    "lobstah",
+    "coding-agents"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/aequitas-labs/lobstah.git"
+  },
+  "peerDependencies": {
+    "openclaw": ">=2026.8.2"
+  },
+  "peerDependenciesMeta": {
+    "openclaw": {
+      "optional": true
+    }
+  },
+  "openclaw": {
+    "extensions": [
+      "./dist/index.js"
+    ]
+  }
+}