@gakr-gakr/lobster 0.1.0

package/README.md

@@ -0,0 +1,74 @@
+# Lobster (plugin)
+
+Adds the `lobster` agent tool as an **optional** plugin tool.
+
+## What this is
+
+- Lobster is a standalone workflow shell (typed JSON-first pipelines + approvals/resume).
+- This plugin integrates Lobster with AutoBot _without core changes_.
+
+## Enable
+
+Because this tool can trigger side effects (via workflows), it is registered with `optional: true`.
+
+Enable it in an agent allowlist:
+
+```json
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": [
+            "lobster" // plugin id (enables all tools from this plugin)
+          ]
+        }
+      }
+    ]
+  }
+}
+```
+
+## Using `autobot.invoke` (Lobster → AutoBot tools)
+
+Some Lobster pipelines may include a `autobot.invoke` step to call back into AutoBot tools/plugins (for example: `gog` for Google Workspace, `gh` for GitHub, `message.send`, etc.).
+
+For this to work, the AutoBot Gateway must expose the tool bridge endpoint and the target tool must be allowed by policy:
+
+- AutoBot provides an HTTP endpoint: `POST /tools/invoke`.
+- The request is gated by **gateway auth** (e.g. `Authorization: Bearer …` when token auth is enabled).
+- The invoked tool is gated by **tool policy** (global + per-agent + provider + group policy). If the tool is not allowed, AutoBot returns `404 Tool not available`.
+
+### Allowlisting recommended
+
+To avoid letting workflows call arbitrary tools, set a tight allowlist on the agent that will be used by `autobot.invoke`.
+
+Example (allow only a small set of tools):
+
+```jsonc
+{
+  "agents": {
+    "list": [
+      {
+        "id": "main",
+        "tools": {
+          "allow": ["lobster", "web_fetch", "web_search", "gog", "gh"],
+          "deny": ["gateway"],
+        },
+      },
+    ],
+  },
+}
+```
+
+Notes:
+
+- If `tools.allow` is omitted or empty, it behaves like "allow everything (except denied)". For a real allowlist, set a **non-empty** `allow`.
+- Tool names depend on which plugins you have installed/enabled.
+
+## Security
+
+- 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.

package/SKILL.md

@@ -0,0 +1,97 @@
+# Lobster
+
+Lobster executes multi-step workflows with approval checkpoints. Use it when:
+
+- User wants a repeatable automation (triage, monitor, sync)
+- Actions need human approval before executing (send, post, delete)
+- Multiple tool calls should run as one deterministic operation
+
+## When to use Lobster
+
+| User intent                                            | Use Lobster?                                  |
+| ------------------------------------------------------ | --------------------------------------------- |
+| "Triage my email"                                      | Yes — multi-step, may send replies            |
+| "Send a message"                                       | No — single action, use message tool directly |
+| "Check my email every morning and ask before replying" | Yes — scheduled workflow with approval        |
+| "What's the weather?"                                  | No — simple query                             |
+| "Monitor this PR and notify me of changes"             | Yes — stateful, recurring                     |
+
+## Basic usage
+
+### Run a pipeline
+
+```json
+{
+  "action": "run",
+  "pipeline": "gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage"
+}
+```
+
+Returns structured result:
+
+```json
+{
+  "protocolVersion": 1,
+  "ok": true,
+  "status": "ok",
+  "output": [{ "summary": {...}, "items": [...] }],
+  "requiresApproval": null
+}
+```
+
+### Handle approval
+
+If the workflow needs approval:
+
+```json
+{
+  "status": "needs_approval",
+  "output": [],
+  "requiresApproval": {
+    "prompt": "Send 3 draft replies?",
+    "items": [...],
+    "resumeToken": "..."
+  }
+}
+```
+
+Present the prompt to the user. If they approve:
+
+```json
+{
+  "action": "resume",
+  "token": "<resumeToken>",
+  "approve": true
+}
+```
+
+## Example workflows
+
+### Email triage
+
+```
+gog.gmail.search --query 'newer_than:1d' --max 20 | email.triage
+```
+
+Fetches recent emails, classifies into buckets (needs_reply, needs_action, fyi).
+
+### Email triage with approval gate
+
+```
+gog.gmail.search --query 'newer_than:1d' | email.triage | approve --prompt 'Process these?'
+```
+
+Same as above, but halts for approval before returning.
+
+## Key behaviors
+
+- **Deterministic**: Same input → same output (no LLM variance in pipeline execution)
+- **Approval gates**: `approve` command halts execution, returns token
+- **Resumable**: Use `resume` action with token to continue
+- **Structured output**: Always returns JSON envelope with `protocolVersion`
+
+## Don't use Lobster for
+
+- Simple single-action requests (just use the tool directly)
+- Queries that need LLM interpretation mid-flow
+- One-off tasks that won't be repeated

package/autobot.plugin.json

@@ -0,0 +1,21 @@
+{
+  "id": "lobster",
+  "activation": {
+    "onStartup": true
+  },
+  "name": "Lobster",
+  "description": "Typed workflow tool with resumable approvals.",
+  "contracts": {
+    "tools": ["lobster"]
+  },
+  "toolMetadata": {
+    "lobster": {
+      "optional": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/index.ts

@@ -0,0 +1,24 @@
+import { definePluginEntry } from "autobot/plugin-sdk/plugin-entry";
+import type { AnyAgentTool, AutoBotPluginApi, AutoBotPluginToolFactory } from "./runtime-api.js";
+import { createLobsterTool } from "./src/lobster-tool.js";
+
+export default definePluginEntry({
+  id: "lobster",
+  name: "Lobster",
+  description: "Optional local shell helper tools",
+  register(api: AutoBotPluginApi) {
+    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 AutoBotPluginToolFactory,
+      { optional: true },
+    );
+  },
+});

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@gakr-gakr/lobster",
+  "version": "0.1.0",
+  "description": "Lobster workflow tool plugin (typed pipelines + resumable approvals)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/autobot/autobot"
+  },
+  "type": "module",
+  "dependencies": {
+    "@clawdbot/lobster": "2026.4.6",
+    "ajv": "8.20.0",
+    "typebox": "1.1.38"
+  },
+  "devDependencies": {
+    "@gakr-gakr/plugin-sdk": "workspace:*"
+  },
+  "autobot": {
+    "extensions": [
+      "./index.ts"
+    ],
+    "install": {
+      "npmSpec": "@gakr-gakr/lobster",
+      "defaultChoice": "npm",
+      "minHostVersion": ">=2026.4.25"
+    },
+    "compat": {
+      "pluginApi": ">=2026.5.19"
+    },
+    "build": {
+      "autobotVersion": "2026.5.19"
+    },
+    "release": {
+      "publishToClawHub": true,
+      "publishToNpm": true
+    }
+  }
+}

package/runtime-api.ts

@@ -0,0 +1,12 @@
+export { definePluginEntry } from "autobot/plugin-sdk/core";
+export type {
+  AnyAgentTool,
+  AutoBotPluginApi,
+  AutoBotPluginToolContext,
+  AutoBotPluginToolFactory,
+} from "autobot/plugin-sdk/core";
+export {
+  applyWindowsSpawnProgramPolicy,
+  materializeWindowsSpawnProgram,
+  resolveWindowsSpawnProgramCandidate,
+} from "autobot/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("autobot.lobster.ajv-compile-cache.installed");
+const cacheSymbol = Symbol.for("autobot.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>;
+}