diff --git a/CHANGELOG.md b/CHANGELOG.md index e3238d7..7f0133e 100644 --- a/CHANGELOG.md +++ b/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)). diff --git a/README.md b/README.md index 37c7872..e0a0a9f 100644 --- a/README.md +++ b/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): diff --git a/src/cli.ts b/src/cli.ts index 289ac7e..5426910 100644 --- a/src/cli.ts +++ b/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` ); } diff --git a/src/commands/registry.ts b/src/commands/registry.ts index 8080259..934495b 100644 --- a/src/commands/registry.ts +++ b/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, diff --git a/src/commands/stdlib/openclaw_agent.ts b/src/commands/stdlib/openclaw_agent.ts new file mode 100644 index 0000000..3cbc2f4 --- /dev/null +++ b/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; + +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 { + 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 { + 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; +} diff --git a/test/fixtures/mock-openclaw-agent.mjs b/test/fixtures/mock-openclaw-agent.mjs new file mode 100644 index 0000000..4b4aaa1 --- /dev/null +++ b/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(); +} diff --git a/test/openclaw_agent.test.ts b/test/openclaw_agent.test.ts new file mode 100644 index 0000000..7c24f77 --- /dev/null +++ b/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> = []; + 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"); +});