@openclaw/lobster 2026.3.13 → 2026.5.1-beta.1

package/README.md

@@ -69,7 +69,6 @@ Notes:
 
 ## Security
 
-- Runs the `lobster` executable as a local subprocess.
+- Runs Lobster in process via the published `@clawdbot/lobster/core` runtime.
 - Does not manage OAuth/tokens.
 - Uses timeouts, stdout caps, and strict JSON envelope parsing.
-- Ensure `lobster` is available on `PATH` for the gateway process.

package/index.ts

@@ -1,18 +1,24 @@
-import type {
-  AnyAgentTool,
-  OpenClawPluginApi,
-  OpenClawPluginToolFactory,
-} from "openclaw/plugin-sdk/lobster";
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import type { AnyAgentTool, OpenClawPluginApi, OpenClawPluginToolFactory } from "./runtime-api.js";
 import { createLobsterTool } from "./src/lobster-tool.js";
 
-export default function register(api: OpenClawPluginApi) {
-  api.registerTool(
-    ((ctx) => {
-      if (ctx.sandboxed) {
-        return null;
-      }
-      return createLobsterTool(api) as AnyAgentTool;
-    }) as OpenClawPluginToolFactory,
-    { optional: true },
-  );
-}
+export default definePluginEntry({
+  id: "lobster",
+  name: "Lobster",
+  description: "Optional local shell helper tools",
+  register(api: OpenClawPluginApi) {
+    api.registerTool(
+      ((ctx) => {
+        if (ctx.sandboxed) {
+          return null;
+        }
+        const taskFlow =
+          api.runtime?.tasks.managedFlows && ctx.sessionKey
+            ? api.runtime.tasks.managedFlows.fromToolContext(ctx)
+            : undefined;
+        return createLobsterTool(api, { taskFlow }) as AnyAgentTool;
+      }) as OpenClawPluginToolFactory,
+      { optional: true },
+    );
+  },
+});

package/openclaw.plugin.json

@@ -1,5 +1,8 @@
 {
   "id": "lobster",
+  "activation": {
+    "onStartup": true
+  },
   "name": "Lobster",
   "description": "Typed workflow tool with resumable approvals.",
   "configSchema": {

package/package.json

@@ -1,14 +1,33 @@
 {
   "name": "@openclaw/lobster",
-  "version": "2026.3.13",
+  "version": "2026.5.1-beta.1",
   "description": "Lobster workflow tool plugin (typed pipelines + resumable approvals)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/openclaw/openclaw"
+  },
   "type": "module",
   "dependencies": {
-    "@sinclair/typebox": "0.34.48"
+    "@clawdbot/lobster": "2026.4.6",
+    "ajv": "^8.20.0",
+    "typebox": "1.1.37"
+  },
+  "devDependencies": {
+    "@openclaw/plugin-sdk": "workspace:*"
   },
   "openclaw": {
     "extensions": [
       "./index.ts"
-    ]
+    ],
+    "compat": {
+      "pluginApi": ">=2026.4.25"
+    },
+    "build": {
+      "openclawVersion": "2026.5.1-beta.1"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
   }
 }

package/runtime-api.ts

@@ -0,0 +1,12 @@
+export { definePluginEntry } from "openclaw/plugin-sdk/core";
+export type {
+  AnyAgentTool,
+  OpenClawPluginApi,
+  OpenClawPluginToolContext,
+  OpenClawPluginToolFactory,
+} from "openclaw/plugin-sdk/core";
+export {
+  applyWindowsSpawnProgramPolicy,
+  materializeWindowsSpawnProgram,
+  resolveWindowsSpawnProgramCandidate,
+} from "openclaw/plugin-sdk/windows-spawn";

package/src/lobster-ajv-cache.ts

@@ -0,0 +1,142 @@
+import { createHash } from "node:crypto";
+import AjvPkg, { type AnySchema, type ValidateFunction } from "ajv";
+
+const installedSymbol = Symbol.for("openclaw.lobster.ajv-compile-cache.installed");
+const cacheSymbol = Symbol.for("openclaw.lobster.ajv-compile-cache.entries");
+const maxEntries = 512;
+
+type AjvInstance = import("ajv").default;
+
+type CompileCacheEntry = {
+  schema: AnySchema;
+  validate: ValidateFunction;
+};
+
+const AjvCtor = AjvPkg as unknown as {
+  new (opts?: object): AjvInstance;
+  prototype: AjvInstance;
+};
+
+type AjvWithCompileCache = AjvInstance & {
+  [cacheSymbol]?: Map<string, CompileCacheEntry>;
+};
+
+type AjvPrototypePatch = {
+  [installedSymbol]?: boolean;
+  compile: (schema: AnySchema) => ValidateFunction;
+  removeSchema: (schemaKeyRef?: Parameters<AjvInstance["removeSchema"]>[0]) => AjvInstance;
+};
+
+type JsonLike = null | boolean | number | string | JsonLike[] | { [key: string]: JsonLike };
+
+function stableJsonStringify(value: unknown, seen = new WeakSet<object>()): string {
+  if (value === null || typeof value !== "object") {
+    return JSON.stringify(value);
+  }
+  if (seen.has(value)) {
+    throw new TypeError("Cannot cache cyclic JSON schema");
+  }
+  seen.add(value);
+  if (Array.isArray(value)) {
+    const items = value.map((entry) => stableJsonStringify(entry, seen));
+    seen.delete(value);
+    return `[${items.join(",")}]`;
+  }
+  const record = value as Record<string, unknown>;
+  const keys = Object.keys(record).toSorted();
+  const properties = keys
+    .filter((key) => record[key] !== undefined)
+    .map((key) => `${JSON.stringify(key)}:${stableJsonStringify(record[key], seen)}`);
+  seen.delete(value);
+  return `{${properties.join(",")}}`;
+}
+
+function compileCacheKey(schema: unknown): string | null {
+  try {
+    return createHash("sha256").update(stableJsonStringify(schema)).digest("hex");
+  } catch {
+    return null;
+  }
+}
+
+function readCompileCache(instance: AjvWithCompileCache): Map<string, CompileCacheEntry> {
+  let cache = instance[cacheSymbol];
+  if (!cache) {
+    cache = new Map<string, CompileCacheEntry>();
+    Object.defineProperty(instance, cacheSymbol, {
+      value: cache,
+      configurable: true,
+    });
+  }
+  return cache;
+}
+
+function rememberCompiledValidator(params: {
+  cache: Map<string, CompileCacheEntry>;
+  instance: AjvWithCompileCache;
+  key: string;
+  removeSchema: AjvPrototypePatch["removeSchema"];
+  schema: AnySchema;
+  validate: ValidateFunction;
+}) {
+  const { cache, instance, key, removeSchema, schema, validate } = params;
+  if (!cache.has(key) && cache.size >= maxEntries) {
+    const oldest = cache.keys().next().value;
+    if (oldest !== undefined) {
+      const evicted = cache.get(oldest);
+      cache.delete(oldest);
+      if (evicted) {
+        removeSchema.call(instance, evicted.schema);
+      }
+    }
+  }
+  cache.set(key, { schema, validate });
+}
+
+export function installLobsterAjvCompileCache() {
+  const proto = AjvCtor.prototype as unknown as AjvPrototypePatch;
+  if (proto[installedSymbol]) {
+    return;
+  }
+
+  const originalCompile = proto.compile;
+  const originalRemoveSchema = proto.removeSchema;
+
+  Object.defineProperty(proto, installedSymbol, {
+    value: true,
+    configurable: true,
+  });
+
+  proto.compile = function compileWithContentCache(
+    this: AjvWithCompileCache,
+    schema: AnySchema,
+  ): ValidateFunction<JsonLike> {
+    const key = compileCacheKey(schema);
+    if (!key) {
+      return originalCompile.call(this, schema) as ValidateFunction<JsonLike>;
+    }
+    const cache = readCompileCache(this);
+    const cached = cache.get(key);
+    if (cached) {
+      return cached.validate as ValidateFunction<JsonLike>;
+    }
+    const validate = originalCompile.call(this, schema) as ValidateFunction<JsonLike>;
+    rememberCompiledValidator({
+      cache,
+      instance: this,
+      key,
+      removeSchema: originalRemoveSchema,
+      schema,
+      validate,
+    });
+    return validate;
+  };
+
+  proto.removeSchema = function removeSchemaAndClearContentCache(
+    this: AjvWithCompileCache,
+    schemaKeyRef?: Parameters<AjvInstance["removeSchema"]>[0],
+  ) {
+    this[cacheSymbol]?.clear();
+    return originalRemoveSchema.call(this, schemaKeyRef);
+  };
+}

package/src/lobster-core.d.ts

@@ -0,0 +1,60 @@
+declare module "@clawdbot/lobster/core" {
+  type LobsterApprovalRequest = {
+    type: "approval_request";
+    prompt: string;
+    items: unknown[];
+    resumeToken?: string;
+    approvalId?: string;
+  } | null;
+
+  type LobsterToolContext = {
+    cwd?: string;
+    env?: Record<string, string | undefined>;
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    signal?: AbortSignal;
+    registry?: unknown;
+    llmAdapters?: Record<string, unknown>;
+  };
+
+  type LobsterToolEnvelope =
+    | {
+        protocolVersion: 1;
+        ok: true;
+        status: "ok" | "needs_approval" | "needs_input" | "cancelled";
+        output: unknown[];
+        requiresApproval: LobsterApprovalRequest;
+        requiresInput?: {
+          prompt: string;
+          schema?: unknown;
+          items?: unknown[];
+          resumeToken?: string;
+          approvalId?: string;
+        } | null;
+      }
+    | {
+        protocolVersion: 1;
+        ok: false;
+        error: {
+          type: string;
+          message: string;
+        };
+      };
+
+  export function runToolRequest(params: {
+    pipeline?: string;
+    filePath?: string;
+    args?: Record<string, unknown>;
+    ctx?: LobsterToolContext;
+  }): Promise<LobsterToolEnvelope>;
+
+  export function resumeToolRequest(params: {
+    token?: string;
+    approvalId?: string;
+    approved?: boolean;
+    response?: unknown;
+    cancel?: boolean;
+    ctx?: LobsterToolContext;
+  }): Promise<LobsterToolEnvelope>;
+}