feat: add OpenClaw agent invocation (#118)

CHANGELOG.md

@@ -4,6 +4,8 @@ All notable changes to Lobster will be documented in this file.
 
 ## Unreleased
 
+- Add first-class `openclaw.agent` workflow turns with configured agent, session, model, thinking, and timeout selection delegated to OpenClaw. Thanks to [@Stoff81](https://github.com/Stoff81) (Issue [#117](https://github.com/openclaw/lobster/issues/117)).
+
 ## 2026.6.11
 
 - Add command-level `ctx.requestInput(...)` for CLI/tool/SDK pipeline commands, with state-backed same-command resume, bounded command-input replay, and workflow `pipeline:` propagation (Issue [#101](https://github.com/openclaw/lobster/issues/101)).

README.md

@@ -275,9 +275,20 @@ Workflow `_meta.cost` and `cost_limit` use a static pricing table plus optional
 
 `llm_task.invoke` remains available as a backward-compatible alias for the OpenClaw provider.
 
+### Calling configured OpenClaw agents
+
+Use `openclaw.agent` when a workflow needs a configured OpenClaw agent rather than a direct model call:
+
+```bash
+openclaw.agent --agent ops --prompt 'Summarize these logs'
+openclaw.agent --agent ops --session-key incident-42 --model openai/gpt-5.4 --prompt 'Continue the investigation'
+```
+
+The command delegates agent identity, model defaults and overrides, sessions, authentication, and execution to the installed `openclaw agent` CLI. It accepts `--agent`, `--session-key`, `--session-id`, `--model`, `--thinking`, `--timeout`, and `--local`, and returns OpenClaw's structured `--json` response. Pipeline input is appended to the prompt as labeled JSONL.
+
 ### `pipeline:` vs `run:` for LLM calls
 
-- Use `pipeline:` for `llm.invoke` and `llm_task.invoke` (they are Lobster pipeline stages, not shell executables).
+- Use `pipeline:` for `openclaw.agent`, `llm.invoke`, and `llm_task.invoke` (they are Lobster pipeline stages, not shell executables).
 - Use `run:` only for real binaries in your shell (for example `openclaw.invoke`).
 
 Example (`stdin` from a prior step is passed to the LLM as artifacts):

src/cli.ts

@@ -856,7 +856,7 @@ function helpText() {
     `  lobster 'exec --json "echo [1,2,3]" | json'\n` +
     `  lobster run --mode tool 'exec --json "echo [1]" | approve --prompt "ok?"'\n\n` +
     `Commands:\n` +
-    `  exec, head, json, pick, table, where, approve, ask, openclaw.invoke, llm.invoke, llm_task.invoke, state.get, state.set, diff.last, commands.list, workflows.list, workflows.run, graph\n`
+    `  exec, head, json, pick, table, where, approve, ask, openclaw.agent, openclaw.invoke, llm.invoke, llm_task.invoke, state.get, state.set, diff.last, commands.list, workflows.list, workflows.run, graph\n`
   );
 }
 

src/commands/registry.ts

@@ -12,6 +12,7 @@ import { groupByCommand } from "./stdlib/group_by.js";
 import { approveCommand } from "./stdlib/approve.js";
 import { askCommand } from "./stdlib/ask.js";
 import { clawdInvokeCommand, openclawInvokeCommand } from "./stdlib/openclaw_invoke.js";
+import { openclawAgentCommand } from "./stdlib/openclaw_agent.js";
 import { llmInvokeCommand } from "./stdlib/llm_invoke.js";
 import { llmTaskInvokeCommand } from "./stdlib/llm_task_invoke.js";
 import { stateGetCommand, stateSetCommand } from "./stdlib/state.js";
@@ -42,6 +43,7 @@ export function createDefaultRegistry() {
     askCommand,
     openclawInvokeCommand,
     clawdInvokeCommand,
+    openclawAgentCommand,
     llmInvokeCommand,
     llmTaskInvokeCommand,
     stateGetCommand,

src/commands/stdlib/openclaw_agent.ts

@@ -0,0 +1,167 @@
+import { execFile } from "node:child_process";
+import type { LobsterCommand } from "../types.js";
+
+type AgentCliRunner = (params: {
+  executable: string;
+  argv: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+}) => Promise<unknown>;
+
+export const openclawAgentCommand = createOpenClawAgentCommand();
+
+export function createOpenClawAgentCommand(
+  runCli: AgentCliRunner = runOpenClawAgentCli,
+): LobsterCommand {
+  return {
+    name: "openclaw.agent",
+    meta: {
+      description: "Run a configured OpenClaw agent turn",
+      argsSchema: {
+        type: "object",
+        properties: {
+          agent: { type: "string", description: "Configured OpenClaw agent id" },
+          prompt: { type: "string", description: "Message for the agent" },
+          message: { type: "string", description: "Alias for prompt" },
+          model: { type: "string", description: "OpenClaw model override for this turn" },
+          sessionKey: { type: "string", description: "OpenClaw session key" },
+          "session-key": { type: "string", description: "Alias for sessionKey" },
+          sessionId: { type: "string", description: "OpenClaw session id" },
+          "session-id": { type: "string", description: "Alias for sessionId" },
+          thinking: { type: "string", description: "OpenClaw thinking level" },
+          timeout: { type: "number", description: "Agent timeout in seconds" },
+          local: { type: "boolean", description: "Force OpenClaw embedded execution" },
+          _: { type: "array", items: { type: "string" } },
+        },
+        required: [],
+      },
+      sideEffects: ["calls_openclaw_agent"],
+    },
+    help() {
+      return (
+        `openclaw.agent — run a configured OpenClaw agent turn\n\n` +
+        `Usage:\n` +
+        `  openclaw.agent --agent ops --prompt "Summarize logs"\n` +
+        `  openclaw.agent --agent ops --session-key incident-42 --model openai/gpt-5.4 --prompt "Continue"\n` +
+        `  ... | openclaw.agent --agent ops --prompt "Review this input"\n\n` +
+        `Notes:\n` +
+        `  - Delegates agent, session, model, and auth behavior to the installed OpenClaw CLI.\n` +
+        `  - Requires --agent, --session-key, or --session-id.\n` +
+        `  - Pipeline input is appended to the message as JSONL under a labeled section.\n` +
+        `  - Returns the structured OpenClaw --json response unchanged.\n`
+      );
+    },
+    async run({ input, args, ctx }) {
+      const prompt = extractPrompt(args);
+      if (!prompt) {
+        throw new Error("openclaw.agent requires --prompt, --message, or positional text");
+      }
+
+      const agent = optionalString(args.agent);
+      const sessionKey = optionalString(args.sessionKey ?? args["session-key"]);
+      const sessionId = optionalString(args.sessionId ?? args["session-id"]);
+      if (!agent && !sessionKey && !sessionId) {
+        throw new Error("openclaw.agent requires --agent, --session-key, or --session-id");
+      }
+
+      const inputItems: unknown[] = [];
+      for await (const item of input) inputItems.push(item);
+
+      const argv = ["agent", "--json", "--message", appendPipelineInput(prompt, inputItems)];
+      pushOption(argv, "--agent", agent);
+      pushOption(argv, "--model", optionalString(args.model));
+      pushOption(argv, "--session-key", sessionKey);
+      pushOption(argv, "--session-id", sessionId);
+      pushOption(argv, "--thinking", optionalString(args.thinking));
+
+      if (args.timeout !== undefined && args.timeout !== null) {
+        const timeout = Number(args.timeout);
+        if (!Number.isInteger(timeout) || timeout < 0) {
+          throw new Error("openclaw.agent --timeout must be a non-negative integer in seconds");
+        }
+        pushOption(argv, "--timeout", String(timeout));
+      }
+      if (args.local === true) argv.push("--local");
+
+      const env = (ctx?.env ?? process.env) as NodeJS.ProcessEnv;
+      const executable = optionalString(env.LOBSTER_OPENCLAW_BIN) ?? "openclaw";
+      const response = await runCli({
+        executable,
+        argv,
+        cwd: ctx?.cwd ?? process.cwd(),
+        env,
+        signal: ctx?.signal,
+      });
+      return { output: streamOf([response]) };
+    },
+  };
+}
+
+export function runOpenClawAgentCli(params: {
+  executable: string;
+  argv: string[];
+  cwd: string;
+  env: NodeJS.ProcessEnv;
+  signal?: AbortSignal;
+}): Promise<unknown> {
+  return new Promise((resolve, reject) => {
+    execFile(
+      params.executable,
+      params.argv,
+      {
+        cwd: params.cwd,
+        env: params.env,
+        signal: params.signal,
+        encoding: "utf8",
+        maxBuffer: 10 * 1024 * 1024,
+      },
+      (error, stdout, stderr) => {
+        if (error) {
+          if (error.name === "AbortError") {
+            reject(error);
+            return;
+          }
+          const detail = String(stderr || stdout || error.message).trim();
+          reject(new Error(`openclaw.agent failed: ${detail}`));
+          return;
+        }
+        try {
+          const parsed = JSON.parse(String(stdout).trim() || "null");
+          if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+            throw new Error("response must be an object");
+          }
+          resolve(parsed);
+        } catch {
+          reject(new Error("openclaw.agent expected JSON output from `openclaw agent --json`"));
+        }
+      },
+    );
+  });
+}
+
+function extractPrompt(args: Record<string, unknown>): string {
+  const explicit = optionalString(args.prompt ?? args.message);
+  if (explicit) return explicit;
+  return Array.isArray(args._) ? args._.map(String).join(" ").trim() : "";
+}
+
+function appendPipelineInput(prompt: string, items: unknown[]): string {
+  if (items.length === 0) return prompt;
+  const jsonl = items.map((item) => JSON.stringify(item)).join("\n");
+  return `${prompt}\n\nPipeline input (JSONL):\n${jsonl}`;
+}
+
+function optionalString(value: unknown): string | undefined {
+  if (value === undefined || value === null) return undefined;
+  const text = String(value).trim();
+  return text || undefined;
+}
+
+function pushOption(argv: string[], name: string, value: string | undefined): void {
+  if (value !== undefined) argv.push(name, value);
+}
+
+async function* streamOf(items: unknown[]) {
+  for (const item of items) yield item;
+}

test/fixtures/mock-openclaw-agent.mjs

@@ -0,0 +1,15 @@
+const writeResponse = () => {
+  process.stdout.write(
+    JSON.stringify({
+      runId: "fixture-run",
+      status: "ok",
+      result: { payloads: [{ text: "fixture reply" }] },
+    }),
+  );
+};
+
+if (process.argv.includes("--sleep")) {
+  setTimeout(writeResponse, 10_000);
+} else {
+  writeResponse();
+}

test/openclaw_agent.test.ts

@@ -0,0 +1,119 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import path from "node:path";
+import {
+  createOpenClawAgentCommand,
+  runOpenClawAgentCli,
+} from "../src/commands/stdlib/openclaw_agent.js";
+
+function streamOf(items: unknown[]) {
+  return (async function* () {
+    for (const item of items) yield item;
+  })();
+}
+
+test("openclaw.agent delegates agent, session, and model selection to OpenClaw", async () => {
+  const calls: Array<Record<string, unknown>> = [];
+  const cmd = createOpenClawAgentCommand(async (params) => {
+    calls.push(params);
+    return {
+      runId: "run-1",
+      status: "ok",
+      result: { payloads: [{ text: "done" }] },
+    };
+  });
+
+  const result = await cmd.run({
+    input: streamOf([{ path: "src/index.ts" }, "plain text"]),
+    args: {
+      _: [],
+      agent: "ops",
+      prompt: "Review this",
+      model: "openai/gpt-5.4",
+      "session-key": "incident-42",
+      thinking: "high",
+      timeout: 45,
+    },
+    ctx: { env: {}, cwd: "/tmp" },
+  });
+
+  const items: unknown[] = [];
+  for await (const item of result.output) items.push(item);
+  assert.deepEqual(items, [
+    {
+      runId: "run-1",
+      status: "ok",
+      result: { payloads: [{ text: "done" }] },
+    },
+  ]);
+  assert.equal(calls.length, 1);
+  assert.deepEqual(calls[0]?.argv, [
+    "agent",
+    "--json",
+    "--message",
+    'Review this\n\nPipeline input (JSONL):\n{"path":"src/index.ts"}\n"plain text"',
+    "--agent",
+    "ops",
+    "--model",
+    "openai/gpt-5.4",
+    "--session-key",
+    "incident-42",
+    "--thinking",
+    "high",
+    "--timeout",
+    "45",
+  ]);
+});
+
+test("openclaw.agent requires a message and agent or session target", async () => {
+  const cmd = createOpenClawAgentCommand(async () => ({}));
+  const ctx = { env: {}, cwd: "/tmp" };
+
+  await assert.rejects(
+    cmd.run({ input: streamOf([]), args: { _: [], agent: "main" }, ctx }),
+    /requires --prompt/,
+  );
+  await assert.rejects(
+    cmd.run({ input: streamOf([]), args: { _: [], prompt: "hello" }, ctx }),
+    /requires --agent/,
+  );
+  await assert.rejects(
+    cmd.run({
+      input: streamOf([]),
+      args: { _: [], agent: "main", prompt: "hello", timeout: 1.5 },
+      ctx,
+    }),
+    /non-negative integer/,
+  );
+});
+
+test("OpenClaw CLI runner parses structured JSON output", async () => {
+  const fixturePath = path.join(process.cwd(), "test", "fixtures", "mock-openclaw-agent.mjs");
+  const output = await runOpenClawAgentCli({
+    executable: process.execPath,
+    argv: [fixturePath, "agent", "--json", "--message", "hello"],
+    cwd: process.cwd(),
+    env: process.env,
+  });
+
+  assert.deepEqual(output, {
+    runId: "fixture-run",
+    status: "ok",
+    result: { payloads: [{ text: "fixture reply" }] },
+  });
+});
+
+test("OpenClaw CLI runner preserves workflow cancellation", async () => {
+  const fixturePath = path.join(process.cwd(), "test", "fixtures", "mock-openclaw-agent.mjs");
+  const controller = new AbortController();
+  const pending = runOpenClawAgentCli({
+    executable: process.execPath,
+    argv: [fixturePath, "--sleep"],
+    cwd: process.cwd(),
+    env: process.env,
+    signal: controller.signal,
+  });
+  controller.abort();
+
+  await assert.rejects(pending, (error: Error) => error.name === "AbortError");
+});