From 9064cef0c44e68d0b2b1804817dba3026de0e1c2 Mon Sep 17 00:00:00 2001 From: Tinson Lai Date: Sat, 13 Jun 2026 18:33:19 +0000 Subject: [PATCH 1/4] feat(sandbox): add prompt subcommand for non-interactive openclaw access Signed-off-by: Tinson Lai --- docs/reference/commands-nemohermes.mdx | 17 +++ docs/reference/commands.mdx | 44 ++++++ src/commands/sandbox/prompt.test.ts | 71 ++++++++++ src/commands/sandbox/prompt.ts | 53 ++++++++ src/lib/actions/sandbox/prompt.test.ts | 177 +++++++++++++++++++++++++ src/lib/actions/sandbox/prompt.ts | 134 +++++++++++++++++++ src/lib/cli/public-display-defaults.ts | 7 + 7 files changed, 503 insertions(+) create mode 100644 src/commands/sandbox/prompt.test.ts create mode 100644 src/commands/sandbox/prompt.ts create mode 100644 src/lib/actions/sandbox/prompt.test.ts create mode 100644 src/lib/actions/sandbox/prompt.ts diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index c3fdd39cec3..2342e306a28 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -432,6 +432,23 @@ The exit code is the remote command's exit code. | `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) | | `--timeout ` | Timeout in seconds (`0` means no timeout) | +### `nemohermes prompt` + +Send a single prompt to the agent running inside a sandbox and stream the response to stdout. +The prompt runs non-interactively over the same OpenShell exec transport as `exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. +Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal. + +`prompt` is currently supported only on OpenClaw sandboxes. Hermes already exposes an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. + +Forward the port and POST chat completions directly: + +```bash +openshell forward start --background 8642 my-hermes +curl -sN http://127.0.0.1:8642/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{"model":"","messages":[{"role":"user","content":"What is 2+2?"}],"stream":true}' +``` + ### Advanced Sandbox Maintenance Commands The following commands are available for targeted host-side maintenance, but they are not part of the top-level public command list. diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index ee29b93ae2d..998d030c586 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -530,6 +530,50 @@ The exit code is the remote command's exit code. | `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) | | `--timeout ` | Timeout in seconds (`0` means no timeout) | +### `$$nemoclaw prompt` + +Send a single prompt to the agent running inside a sandbox and stream the response to stdout. +The prompt runs non-interactively over the same OpenShell exec transport as `exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. +Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal. + + + +The prompt is forwarded to `openclaw agent --agent -m ` inside the sandbox, where `` defaults to `main` and can be overridden with `--agent`. + +```bash +$$nemoclaw my-assistant prompt "Summarise README.md" +$$nemoclaw my-assistant prompt --agent chess-bot "Best opening for Black?" +$$nemoclaw my-assistant prompt --prompt-file ./question.txt +echo "What is 2+2?" | $$nemoclaw my-assistant prompt --prompt-file - +``` + +Supply the prompt body in one of two ways: as a positional argument (one quoted string), or via `--prompt-file ` where `-` reads from stdin. Passing both at once is an error; passing neither is an error. + +Streaming follows whatever `openclaw agent` already emits on stdout; no additional buffering is added. The exit code is the remote command's exit code, so pipelines can branch on it. + +| Flag | Description | +|------|-------------| +| `--agent ` | OpenClaw agent profile to address (default: `main`) | +| `--workdir ` | Working directory inside the sandbox | +| `--timeout ` | Timeout in seconds (`0` means no timeout) | +| `--prompt-file ` | Read the prompt body from a file path, or `-` for stdin | + + + + +`prompt` is currently supported only on OpenClaw sandboxes. Hermes already exposes an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. + +Forward the port and POST chat completions directly: + +```bash +openshell forward start --background 8642 my-hermes +curl -sN http://127.0.0.1:8642/v1/chat/completions \ + -H 'Content-Type: application/json' \ + -d '{"model":"","messages":[{"role":"user","content":"What is 2+2?"}],"stream":true}' +``` + + + ### Advanced Sandbox Maintenance Commands The following commands are available for targeted host-side maintenance, but they are not part of the top-level public command list. diff --git a/src/commands/sandbox/prompt.test.ts b/src/commands/sandbox/prompt.test.ts new file mode 100644 index 00000000000..d1762970349 --- /dev/null +++ b/src/commands/sandbox/prompt.test.ts @@ -0,0 +1,71 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import { beforeEach, describe, expect, it, vi } from "vitest"; + +const promptSandboxMock = vi.hoisted(() => vi.fn(async () => {})); +vi.mock("../../lib/actions/sandbox/prompt", () => ({ + promptSandbox: promptSandboxMock, +})); + +import SandboxPromptCommand from "./prompt"; + +const rootDir = process.cwd(); + +describe("SandboxPromptCommand oclif parse path", () => { + beforeEach(() => { + promptSandboxMock.mockReset(); + }); + + it("forwards the positional prompt text and default flags", async () => { + await SandboxPromptCommand.run(["alpha", "What is 2+2?"], rootDir); + expect(promptSandboxMock).toHaveBeenCalledWith("alpha", "What is 2+2?", { + agentProfile: undefined, + workdir: undefined, + timeoutSeconds: undefined, + promptFile: undefined, + }); + }); + + it("parses --agent, --workdir and --timeout into typed options", async () => { + await SandboxPromptCommand.run( + [ + "alpha", + "--agent", + "chess-bot", + "--workdir", + "/sandbox/workspace", + "--timeout", + "30", + "Best opening?", + ], + rootDir, + ); + expect(promptSandboxMock).toHaveBeenCalledWith("alpha", "Best opening?", { + agentProfile: "chess-bot", + workdir: "/sandbox/workspace", + timeoutSeconds: 30, + promptFile: undefined, + }); + }); + + it("supports --prompt-file with no positional text", async () => { + await SandboxPromptCommand.run(["alpha", "--prompt-file", "/tmp/q.txt"], rootDir); + expect(promptSandboxMock).toHaveBeenCalledWith("alpha", undefined, { + agentProfile: undefined, + workdir: undefined, + timeoutSeconds: undefined, + promptFile: "/tmp/q.txt", + }); + }); + + it("supports --prompt-file - for stdin", async () => { + await SandboxPromptCommand.run(["alpha", "--prompt-file", "-"], rootDir); + expect(promptSandboxMock).toHaveBeenCalledWith("alpha", undefined, { + agentProfile: undefined, + workdir: undefined, + timeoutSeconds: undefined, + promptFile: "-", + }); + }); +}); diff --git a/src/commands/sandbox/prompt.ts b/src/commands/sandbox/prompt.ts new file mode 100644 index 00000000000..d77bba5f76b --- /dev/null +++ b/src/commands/sandbox/prompt.ts @@ -0,0 +1,53 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import { Args, Flags } from "@oclif/core"; +import { promptSandbox } from "../../lib/actions/sandbox/prompt"; +import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command"; + +export default class SandboxPromptCommand extends NemoClawCommand { + static id = "sandbox:prompt"; + static strict = false; + static summary = "Send a single prompt to a running sandbox's agent non-interactively"; + static description = + "Send one prompt to the OpenClaw agent inside a running sandbox and stream the response to stdout. The command runs inside the sandbox via the OpenShell exec transport, with HOME=/sandbox so the selected agent profile resolves the same way as `connect`. Supply the prompt as a positional argument, or read it from a file (or stdin via '-') with --prompt-file. Currently supported on OpenClaw sandboxes only; for Hermes, POST to its OpenAI-compatible API on port 8642 inside the sandbox."; + static usage = [ + " [--agent ] [--workdir ] [--timeout ] [--prompt-file ] []", + ]; + static examples = [ + '<%= config.bin %> sandbox prompt alpha "Summarise README.md"', + "<%= config.bin %> sandbox prompt alpha --prompt-file ./question.txt", + '<%= config.bin %> sandbox prompt alpha --agent chess-bot "Best opening for Black?"', + '<%= config.bin %> sandbox prompt alpha --prompt-file - <<<"What is 2+2?"', + ]; + static args = { + sandboxName: Args.string({ name: "sandbox", description: "Sandbox name", required: true }), + text: Args.string({ + name: "text", + description: "Prompt text. Omit when supplying --prompt-file.", + }), + }; + static flags = { + agent: Flags.string({ + description: "OpenClaw agent profile to address (default: main)", + }), + workdir: Flags.string({ description: "Working directory inside the sandbox" }), + timeout: Flags.integer({ + min: 0, + description: "Timeout in seconds (0 = no timeout)", + }), + "prompt-file": Flags.string({ + description: "Read prompt body from a file path, or '-' for stdin", + }), + }; + + public async run(): Promise { + const { args, flags } = await this.parse(SandboxPromptCommand); + await promptSandbox(args.sandboxName, args.text, { + agentProfile: flags.agent, + workdir: flags.workdir, + timeoutSeconds: flags.timeout, + promptFile: flags["prompt-file"], + }); + } +} diff --git a/src/lib/actions/sandbox/prompt.test.ts b/src/lib/actions/sandbox/prompt.test.ts new file mode 100644 index 00000000000..062ff9dd52d --- /dev/null +++ b/src/lib/actions/sandbox/prompt.test.ts @@ -0,0 +1,177 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import { mkdtempSync, writeFileSync } from "node:fs"; +import { tmpdir } from "node:os"; +import { join } from "node:path"; + +import { describe, expect, it, vi } from "vitest"; + +import { + buildOpenclawAgentArgs, + promptSandbox, + readPromptText, +} from "./prompt"; + +describe("buildOpenclawAgentArgs", () => { + it("defaults to the 'main' agent profile when none is supplied", () => { + expect(buildOpenclawAgentArgs("hi")).toEqual([ + "openclaw", + "agent", + "--agent", + "main", + "-m", + "hi", + ]); + }); + + it("honours an explicit agent profile", () => { + expect(buildOpenclawAgentArgs("hello", { agentProfile: "chess-bot" })).toEqual([ + "openclaw", + "agent", + "--agent", + "chess-bot", + "-m", + "hello", + ]); + }); + + it("falls back to the default profile when the supplied value is empty", () => { + expect(buildOpenclawAgentArgs("hi", { agentProfile: "" })).toEqual([ + "openclaw", + "agent", + "--agent", + "main", + "-m", + "hi", + ]); + }); + + it("preserves the prompt body verbatim, including shell metacharacters", () => { + const text = 'Summarise $HOME && echo "done"'; + expect(buildOpenclawAgentArgs(text)).toContain(text); + }); +}); + +describe("readPromptText", () => { + it("returns the inline text when supplied", () => { + expect(readPromptText("hello", undefined)).toBe("hello"); + }); + + it("reads from a file path when --prompt-file is a real path", () => { + const dir = mkdtempSync(join(tmpdir(), "prompt-")); + const path = join(dir, "p.txt"); + writeFileSync(path, "file body\n"); + expect(readPromptText(undefined, path)).toBe("file body\n"); + }); + + it("rejects both inline text and --prompt-file together", () => { + expect(() => readPromptText("inline", "/tmp/x")).toThrow(/either a positional prompt or --prompt-file/); + }); + + it("rejects neither inline nor --prompt-file", () => { + expect(() => readPromptText(undefined, undefined)).toThrow(/positional argument or via --prompt-file/); + }); +}); + +describe("promptSandbox", () => { + function makeDeps(agent: string | null) { + const writes: string[] = []; + const exit = vi.fn((code: number) => { + throw new Error(`__exit:${code}`); + }); + const spawn = vi.fn((..._args: unknown[]) => ({ status: 0 })); + return { + writes, + exit, + spawn, + deps: { + getSandbox: vi.fn(() => (agent ? ({ name: "alpha", agent } as any) : null)), + getOpenshellBinary: () => "/usr/local/bin/openshell", + spawn: spawn as unknown as typeof import("node:child_process").spawnSync, + process: { + exit: exit as unknown as (code: number) => never, + stderr: { write: (s: string) => writes.push(s) }, + }, + }, + }; + } + + it("rejects Hermes sandboxes with a redirect to the OpenAI-compatible API", async () => { + const { writes, exit, spawn, deps } = makeDeps("hermes"); + await expect(promptSandbox("alpha", "hi", {}, deps)).rejects.toThrow("__exit:2"); + expect(spawn).not.toHaveBeenCalled(); + expect(exit).toHaveBeenCalledWith(2); + expect(writes.join("")).toMatch(/supported only on OpenClaw sandboxes \(got 'hermes'\)/); + expect(writes.join("")).toMatch(/port 8642/); + }); + + it("invokes openshell sandbox exec with the openclaw agent argv for OpenClaw sandboxes", async () => { + const { spawn, deps } = makeDeps("openclaw"); + await expect(promptSandbox("alpha", "hi", {}, deps)).rejects.toThrow("__exit:0"); + expect(spawn).toHaveBeenCalledTimes(1); + const [bin, argv, options] = spawn.mock.calls[0] as [string, string[], unknown]; + expect(bin).toBe("/usr/local/bin/openshell"); + expect(argv).toEqual([ + "sandbox", + "exec", + "--name", + "alpha", + "--no-tty", + "--", + "openclaw", + "agent", + "--agent", + "main", + "-m", + "hi", + ]); + expect(options).toEqual({ stdio: "inherit" }); + }); + + it("propagates --agent, --workdir and --timeout into the inner argv", async () => { + const { spawn, deps } = makeDeps("openclaw"); + await expect( + promptSandbox( + "alpha", + "list", + { + agentProfile: "chess-bot", + workdir: "/sandbox/workspace", + timeoutSeconds: 30, + }, + deps, + ), + ).rejects.toThrow("__exit:0"); + const [, rawArgv] = spawn.mock.calls[0] as [string, string[]]; + const argv = rawArgv; + expect(argv).toContain("--workdir"); + expect(argv).toContain("/sandbox/workspace"); + expect(argv).toContain("--timeout"); + expect(argv).toContain("30"); + expect(argv).toContain("--no-tty"); + const dashDash = argv.indexOf("--"); + expect(argv.slice(dashDash + 1)).toEqual([ + "openclaw", + "agent", + "--agent", + "chess-bot", + "-m", + "list", + ]); + }); + + it("treats an unknown sandbox as OpenClaw (registry miss should not block)", async () => { + const { spawn, deps } = makeDeps(null); + await expect(promptSandbox("ghost", "hi", {}, deps)).rejects.toThrow("__exit:0"); + expect(spawn).toHaveBeenCalledTimes(1); + }); + + it("exits 2 with a clear message when no prompt body is supplied", async () => { + const { writes, exit, spawn, deps } = makeDeps("openclaw"); + await expect(promptSandbox("alpha", undefined, {}, deps)).rejects.toThrow("__exit:2"); + expect(spawn).not.toHaveBeenCalled(); + expect(exit).toHaveBeenCalledWith(2); + expect(writes.join("")).toMatch(/positional argument or via --prompt-file/); + }); +}); diff --git a/src/lib/actions/sandbox/prompt.ts b/src/lib/actions/sandbox/prompt.ts new file mode 100644 index 00000000000..7a4c332bee3 --- /dev/null +++ b/src/lib/actions/sandbox/prompt.ts @@ -0,0 +1,134 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import { spawnSync } from "node:child_process"; +import { readFileSync } from "node:fs"; +import os from "node:os"; + +import * as registry from "../../state/registry"; +import { buildOpenshellExecArgs, computeExitCode } from "./exec"; + +export type SandboxPromptOptions = { + agentProfile?: string; + workdir?: string; + timeoutSeconds?: number; + promptFile?: string; +}; + +type SpawnLikeResult = { + status: number | null; + signal?: NodeJS.Signals | null; + error?: Error; +}; + +const DEFAULT_AGENT_PROFILE = "main"; + +export function buildOpenclawAgentArgs( + text: string, + options: SandboxPromptOptions = {}, +): string[] { + return [ + "openclaw", + "agent", + "--agent", + options.agentProfile || DEFAULT_AGENT_PROFILE, + "-m", + text, + ]; +} + +export function readPromptText(text: string | undefined, promptFile: string | undefined): string { + const hasInline = typeof text === "string" && text.length > 0; + const hasFile = typeof promptFile === "string" && promptFile.length > 0; + if (hasInline && hasFile) { + throw new Error("Pass either a positional prompt or --prompt-file, not both."); + } + if (hasInline) return text as string; + if (hasFile) { + const source = promptFile === "-" ? 0 : (promptFile as string); + return readFileSync(source, "utf8"); + } + throw new Error("Provide a prompt as a positional argument or via --prompt-file ."); +} + +function exitWithSpawnResult( + result: SpawnLikeResult, + proc: PromptProcess, +): never { + const { code, errorMessage } = computeExitCode(result); + if (errorMessage) { + proc.stderr.write(` Failed to invoke openshell: ${errorMessage}\n`); + proc.stderr.write(" Ensure 'openshell' is installed and on PATH.\n"); + } + proc.exit(code); +} + +type PromptProcess = { + exit(code: number): never; + stderr: { write(s: string): unknown }; +}; + +function resolveSandboxAgent( + sandboxName: string, + getSandbox: typeof registry.getSandbox = registry.getSandbox, +): string | null { + try { + const sandbox = getSandbox(sandboxName); + return sandbox?.agent ?? null; + } catch { + return null; + } +} + +export type PromptDeps = { + getSandbox?: typeof registry.getSandbox; + getOpenshellBinary?: () => string; + spawn?: typeof spawnSync; + process?: PromptProcess; +}; + +export async function promptSandbox( + sandboxName: string, + text: string | undefined, + options: SandboxPromptOptions = {}, + deps: PromptDeps = {}, +): Promise { + const proc = deps.process ?? process; + const agent = resolveSandboxAgent(sandboxName, deps.getSandbox); + if (agent && agent !== "openclaw") { + proc.stderr.write( + ` prompt is currently supported only on OpenClaw sandboxes (got '${agent}').\n`, + ); + proc.stderr.write( + " Hermes exposes an OpenAI-compatible API on port 8642 inside the sandbox;\n", + ); + proc.stderr.write( + ` forward it with 'openshell forward start --background 8642 ${sandboxName}'\n`, + ); + proc.stderr.write(" and POST to http://127.0.0.1:8642/v1/chat/completions instead.\n"); + proc.exit(2); + } + + let body: string; + try { + body = readPromptText(text, options.promptFile); + } catch (error) { + proc.stderr.write(` ${(error as Error).message}\n`); + return proc.exit(2); + } + + const innerCommand = buildOpenclawAgentArgs(body, options); + const argv = buildOpenshellExecArgs(sandboxName, innerCommand, { + workdir: options.workdir, + tty: false, + timeoutSeconds: options.timeoutSeconds, + }); + const openshellBinary = + deps.getOpenshellBinary?.() ?? require("../../adapters/openshell/runtime").getOpenshellBinary(); + const spawn = deps.spawn ?? spawnSync; + const result = spawn(openshellBinary, argv, { stdio: "inherit" }); + if (result.status === null && !result.error && !result.signal) { + proc.stderr.write(` openshell exited without status (uname=${os.type()}).\n`); + } + exitWithSpawnResult(result, proc); +} diff --git a/src/lib/cli/public-display-defaults.ts b/src/lib/cli/public-display-defaults.ts index 33632c7ef19..8c3d7037c49 100644 --- a/src/lib/cli/public-display-defaults.ts +++ b/src/lib/cli/public-display-defaults.ts @@ -250,6 +250,13 @@ const PUBLIC_DISPLAY_LAYOUT: Record = { flags: "[--workdir ] [--tty|--no-tty] [--timeout ] -- [args...]", }, ], + "sandbox:prompt": [ + { + group: "Sandbox Management", + order: 4.6, + flags: "[--agent ] [--workdir ] [--timeout ] [--prompt-file ] []", + }, + ], "sandbox:upload": [ { group: "Sandbox Management", From ed5f3e6d33a1485193813b0d2af31f1497b25fff Mon Sep 17 00:00:00 2001 From: Tinson Lai Date: Sat, 13 Jun 2026 19:42:50 +0000 Subject: [PATCH 2/4] refactor(sandbox): replace prompt wrapper with openclaw agent passthrough Signed-off-by: Tinson Lai --- docs/reference/commands-nemohermes.mdx | 8 +- docs/reference/commands.mdx | 29 ++- src/commands/sandbox/agent.test.ts | 52 +++++ src/commands/sandbox/agent.ts | 43 +++++ src/commands/sandbox/prompt.test.ts | 71 ------- src/commands/sandbox/prompt.ts | 53 ------ .../sandbox/agent/passthrough-help.test.ts | 22 +++ .../actions/sandbox/agent/passthrough-help.ts | 31 +++ .../actions/sandbox/agent/passthrough.test.ts | 81 ++++++++ src/lib/actions/sandbox/agent/passthrough.ts | 72 +++++++ src/lib/actions/sandbox/prompt.test.ts | 177 ------------------ src/lib/actions/sandbox/prompt.ts | 134 ------------- src/lib/cli/public-display-defaults.ts | 4 +- 13 files changed, 318 insertions(+), 459 deletions(-) create mode 100644 src/commands/sandbox/agent.test.ts create mode 100644 src/commands/sandbox/agent.ts delete mode 100644 src/commands/sandbox/prompt.test.ts delete mode 100644 src/commands/sandbox/prompt.ts create mode 100644 src/lib/actions/sandbox/agent/passthrough-help.test.ts create mode 100644 src/lib/actions/sandbox/agent/passthrough-help.ts create mode 100644 src/lib/actions/sandbox/agent/passthrough.test.ts create mode 100644 src/lib/actions/sandbox/agent/passthrough.ts delete mode 100644 src/lib/actions/sandbox/prompt.test.ts delete mode 100644 src/lib/actions/sandbox/prompt.ts diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index 2342e306a28..da9a84af96d 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -432,13 +432,13 @@ The exit code is the remote command's exit code. | `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) | | `--timeout ` | Timeout in seconds (`0` means no timeout) | -### `nemohermes prompt` +### `nemohermes agent` -Send a single prompt to the agent running inside a sandbox and stream the response to stdout. -The prompt runs non-interactively over the same OpenShell exec transport as `exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. +Run one OpenClaw agent turn non-interactively in a running sandbox. +The command is a thin pass-through to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal. -`prompt` is currently supported only on OpenClaw sandboxes. Hermes already exposes an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. +`agent` is currently supported only on OpenClaw sandboxes. Hermes already exposes an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. Forward the port and POST chat completions directly: diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 998d030c586..699e654cbc1 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -530,38 +530,31 @@ The exit code is the remote command's exit code. | `--tty` / `--no-tty` | Allocate a pseudo-terminal; defaults to auto-detection (on when stdin and stdout are terminals) | | `--timeout ` | Timeout in seconds (`0` means no timeout) | -### `$$nemoclaw prompt` +### `$$nemoclaw agent` -Send a single prompt to the agent running inside a sandbox and stream the response to stdout. -The prompt runs non-interactively over the same OpenShell exec transport as `exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. +Run one OpenClaw agent turn non-interactively in a running sandbox. +The command is a thin pass-through to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal. -The prompt is forwarded to `openclaw agent --agent -m ` inside the sandbox, where `` defaults to `main` and can be overridden with `--agent`. +All flags accepted by the in-sandbox OpenClaw CLI are forwarded verbatim, so the upstream surface stays the single source of truth. ```bash -$$nemoclaw my-assistant prompt "Summarise README.md" -$$nemoclaw my-assistant prompt --agent chess-bot "Best opening for Black?" -$$nemoclaw my-assistant prompt --prompt-file ./question.txt -echo "What is 2+2?" | $$nemoclaw my-assistant prompt --prompt-file - +$$nemoclaw my-assistant agent -m "Summarise README.md" +$$nemoclaw my-assistant agent --agent work -m "Status update?" +$$nemoclaw my-assistant agent --session-id review-42 -m "Any new findings?" +$$nemoclaw my-assistant agent --json -m 'ping' ``` -Supply the prompt body in one of two ways: as a positional argument (one quoted string), or via `--prompt-file ` where `-` reads from stdin. Passing both at once is an error; passing neither is an error. +The exit code is the remote command's exit code, so host-side pipelines can branch on it. Streaming follows whatever `openclaw agent` already emits on stdout; no additional buffering is added. -Streaming follows whatever `openclaw agent` already emits on stdout; no additional buffering is added. The exit code is the remote command's exit code, so pipelines can branch on it. - -| Flag | Description | -|------|-------------| -| `--agent ` | OpenClaw agent profile to address (default: `main`) | -| `--workdir ` | Working directory inside the sandbox | -| `--timeout ` | Timeout in seconds (`0` means no timeout) | -| `--prompt-file ` | Read the prompt body from a file path, or `-` for stdin | +Common upstream flags include `-m `, `--session-id `, `--agent `, `--model `, `--thinking `, `--json`, `--deliver`, `--reply-channel `, and `--timeout `. Run `$$nemoclaw agent --help` for the wrapper-level summary, or invoke `$$nemoclaw exec -- openclaw agent --help` to view the upstream OpenClaw help text directly. -`prompt` is currently supported only on OpenClaw sandboxes. Hermes already exposes an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. +`agent` is currently supported only on OpenClaw sandboxes. Hermes already exposes an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. Forward the port and POST chat completions directly: diff --git a/src/commands/sandbox/agent.test.ts b/src/commands/sandbox/agent.test.ts new file mode 100644 index 00000000000..5731ab9a2af --- /dev/null +++ b/src/commands/sandbox/agent.test.ts @@ -0,0 +1,52 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import { afterEach, beforeEach, describe, expect, it, vi } from "vitest"; + +const runAgentPassthroughMock = vi.hoisted(() => vi.fn(async () => {})); +vi.mock("../../lib/actions/sandbox/agent/passthrough", () => ({ + runAgentPassthrough: runAgentPassthroughMock, +})); + +import SandboxAgentCommand from "./agent"; + +const rootDir = process.cwd(); + +describe("SandboxAgentCommand oclif parse path", () => { + let logSpy: ReturnType; + + beforeEach(() => { + runAgentPassthroughMock.mockReset(); + logSpy = vi.spyOn(console, "log").mockImplementation(() => {}); + }); + + afterEach(() => { + logSpy.mockRestore(); + }); + + it("forwards the OpenClaw argv verbatim to runAgentPassthrough", async () => { + await SandboxAgentCommand.run(["alpha", "--agent", "work", "-m", "hi"], rootDir); + expect(runAgentPassthroughMock).toHaveBeenCalledWith("alpha", { + extraArgs: ["--agent", "work", "-m", "hi"], + }); + }); + + it("does not call runAgentPassthrough when --help follows the sandbox name", async () => { + await SandboxAgentCommand.run(["alpha", "--help"], rootDir); + expect(runAgentPassthroughMock).not.toHaveBeenCalled(); + const help = logSpy.mock.calls.map((c: unknown[]) => String(c[0])).join("\n"); + expect(help).toMatch(/openclaw agent/); + }); + + it("does not call runAgentPassthrough when no sandbox name is supplied", async () => { + await SandboxAgentCommand.run([], rootDir); + expect(runAgentPassthroughMock).not.toHaveBeenCalled(); + const help = logSpy.mock.calls.map((c: unknown[]) => String(c[0])).join("\n"); + expect(help).toMatch(/Pass-through to/); + }); + + it("treats sandbox name '--help' as a help request, not a name", async () => { + await SandboxAgentCommand.run(["--help"], rootDir); + expect(runAgentPassthroughMock).not.toHaveBeenCalled(); + }); +}); diff --git a/src/commands/sandbox/agent.ts b/src/commands/sandbox/agent.ts new file mode 100644 index 00000000000..89a4bcc349a --- /dev/null +++ b/src/commands/sandbox/agent.ts @@ -0,0 +1,43 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import { + hasAgentPassthroughHelpToken, + printAgentPassthroughHelp, +} from "../../lib/actions/sandbox/agent/passthrough-help"; +import { runAgentPassthrough } from "../../lib/actions/sandbox/agent/passthrough"; +import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command"; + +export default class SandboxAgentCommand extends NemoClawCommand { + static id = "sandbox:agent"; + static strict = false; + static summary = "Run one OpenClaw agent turn non-interactively in a sandbox"; + static description = + "Pass through to `openclaw agent` inside the sandbox via `openshell sandbox exec`. Stream the agent's response back to stdout without owning a TTY; useful for driving the sandbox from another process (CI job, multi-agent platform, evaluation harness). All flags accepted by the in-sandbox OpenClaw CLI are forwarded verbatim, including `-m `, `--session-id `, `--agent `, `--json`, `--thinking `, `--deliver`, and `--reply-channel`. Currently supported on OpenClaw sandboxes only; Hermes sandboxes exit non-zero with a redirect to the OpenAI-compatible API on port 8642 inside the sandbox."; + static usage = [" [openclaw-agent-flags...]"]; + static examples = [ + '<%= config.bin %> sandbox agent alpha -m "Summarise README.md"', + '<%= config.bin %> sandbox agent alpha --agent work -m "Status update?"', + '<%= config.bin %> sandbox agent alpha --session-id review-42 -m "Any new findings?"', + "<%= config.bin %> sandbox agent alpha --json -m 'ping'", + ]; + + public async run(): Promise { + this.parsed = true; + const [sandboxName, ...extraArgs] = this.argv; + if ( + !sandboxName || + sandboxName.trim() === "" || + sandboxName === "--help" || + sandboxName === "-h" + ) { + printAgentPassthroughHelp(); + return; + } + if (hasAgentPassthroughHelpToken(extraArgs)) { + printAgentPassthroughHelp(); + return; + } + await runAgentPassthrough(sandboxName, { extraArgs }); + } +} diff --git a/src/commands/sandbox/prompt.test.ts b/src/commands/sandbox/prompt.test.ts deleted file mode 100644 index d1762970349..00000000000 --- a/src/commands/sandbox/prompt.test.ts +++ /dev/null @@ -1,71 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -import { beforeEach, describe, expect, it, vi } from "vitest"; - -const promptSandboxMock = vi.hoisted(() => vi.fn(async () => {})); -vi.mock("../../lib/actions/sandbox/prompt", () => ({ - promptSandbox: promptSandboxMock, -})); - -import SandboxPromptCommand from "./prompt"; - -const rootDir = process.cwd(); - -describe("SandboxPromptCommand oclif parse path", () => { - beforeEach(() => { - promptSandboxMock.mockReset(); - }); - - it("forwards the positional prompt text and default flags", async () => { - await SandboxPromptCommand.run(["alpha", "What is 2+2?"], rootDir); - expect(promptSandboxMock).toHaveBeenCalledWith("alpha", "What is 2+2?", { - agentProfile: undefined, - workdir: undefined, - timeoutSeconds: undefined, - promptFile: undefined, - }); - }); - - it("parses --agent, --workdir and --timeout into typed options", async () => { - await SandboxPromptCommand.run( - [ - "alpha", - "--agent", - "chess-bot", - "--workdir", - "/sandbox/workspace", - "--timeout", - "30", - "Best opening?", - ], - rootDir, - ); - expect(promptSandboxMock).toHaveBeenCalledWith("alpha", "Best opening?", { - agentProfile: "chess-bot", - workdir: "/sandbox/workspace", - timeoutSeconds: 30, - promptFile: undefined, - }); - }); - - it("supports --prompt-file with no positional text", async () => { - await SandboxPromptCommand.run(["alpha", "--prompt-file", "/tmp/q.txt"], rootDir); - expect(promptSandboxMock).toHaveBeenCalledWith("alpha", undefined, { - agentProfile: undefined, - workdir: undefined, - timeoutSeconds: undefined, - promptFile: "/tmp/q.txt", - }); - }); - - it("supports --prompt-file - for stdin", async () => { - await SandboxPromptCommand.run(["alpha", "--prompt-file", "-"], rootDir); - expect(promptSandboxMock).toHaveBeenCalledWith("alpha", undefined, { - agentProfile: undefined, - workdir: undefined, - timeoutSeconds: undefined, - promptFile: "-", - }); - }); -}); diff --git a/src/commands/sandbox/prompt.ts b/src/commands/sandbox/prompt.ts deleted file mode 100644 index d77bba5f76b..00000000000 --- a/src/commands/sandbox/prompt.ts +++ /dev/null @@ -1,53 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -import { Args, Flags } from "@oclif/core"; -import { promptSandbox } from "../../lib/actions/sandbox/prompt"; -import { NemoClawCommand } from "../../lib/cli/nemoclaw-oclif-command"; - -export default class SandboxPromptCommand extends NemoClawCommand { - static id = "sandbox:prompt"; - static strict = false; - static summary = "Send a single prompt to a running sandbox's agent non-interactively"; - static description = - "Send one prompt to the OpenClaw agent inside a running sandbox and stream the response to stdout. The command runs inside the sandbox via the OpenShell exec transport, with HOME=/sandbox so the selected agent profile resolves the same way as `connect`. Supply the prompt as a positional argument, or read it from a file (or stdin via '-') with --prompt-file. Currently supported on OpenClaw sandboxes only; for Hermes, POST to its OpenAI-compatible API on port 8642 inside the sandbox."; - static usage = [ - " [--agent ] [--workdir ] [--timeout ] [--prompt-file ] []", - ]; - static examples = [ - '<%= config.bin %> sandbox prompt alpha "Summarise README.md"', - "<%= config.bin %> sandbox prompt alpha --prompt-file ./question.txt", - '<%= config.bin %> sandbox prompt alpha --agent chess-bot "Best opening for Black?"', - '<%= config.bin %> sandbox prompt alpha --prompt-file - <<<"What is 2+2?"', - ]; - static args = { - sandboxName: Args.string({ name: "sandbox", description: "Sandbox name", required: true }), - text: Args.string({ - name: "text", - description: "Prompt text. Omit when supplying --prompt-file.", - }), - }; - static flags = { - agent: Flags.string({ - description: "OpenClaw agent profile to address (default: main)", - }), - workdir: Flags.string({ description: "Working directory inside the sandbox" }), - timeout: Flags.integer({ - min: 0, - description: "Timeout in seconds (0 = no timeout)", - }), - "prompt-file": Flags.string({ - description: "Read prompt body from a file path, or '-' for stdin", - }), - }; - - public async run(): Promise { - const { args, flags } = await this.parse(SandboxPromptCommand); - await promptSandbox(args.sandboxName, args.text, { - agentProfile: flags.agent, - workdir: flags.workdir, - timeoutSeconds: flags.timeout, - promptFile: flags["prompt-file"], - }); - } -} diff --git a/src/lib/actions/sandbox/agent/passthrough-help.test.ts b/src/lib/actions/sandbox/agent/passthrough-help.test.ts new file mode 100644 index 00000000000..80b26719ddd --- /dev/null +++ b/src/lib/actions/sandbox/agent/passthrough-help.test.ts @@ -0,0 +1,22 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import { describe, expect, it } from "vitest"; + +import { hasAgentPassthroughHelpToken } from "./passthrough-help"; + +describe("hasAgentPassthroughHelpToken", () => { + it("returns true for --help before the OpenClaw argv separator", () => { + expect(hasAgentPassthroughHelpToken(["--help"])).toBe(true); + expect(hasAgentPassthroughHelpToken(["-h", "-m", "hi"])).toBe(true); + }); + + it("ignores --help that appears after the OpenClaw argv separator", () => { + expect(hasAgentPassthroughHelpToken(["--", "--help"])).toBe(false); + }); + + it("returns false for unrelated flags", () => { + expect(hasAgentPassthroughHelpToken(["-m", "hi"])).toBe(false); + expect(hasAgentPassthroughHelpToken([])).toBe(false); + }); +}); diff --git a/src/lib/actions/sandbox/agent/passthrough-help.ts b/src/lib/actions/sandbox/agent/passthrough-help.ts new file mode 100644 index 00000000000..bc97dc76ead --- /dev/null +++ b/src/lib/actions/sandbox/agent/passthrough-help.ts @@ -0,0 +1,31 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import { CLI_NAME } from "../../../cli/branding"; + +export function hasAgentPassthroughHelpToken(args: readonly string[]): boolean { + for (const arg of args) { + if (arg === "--") break; + if (arg === "--help" || arg === "-h") return true; + } + return false; +} + +export function printAgentPassthroughHelp(): void { + console.log(""); + console.log(` Usage: ${CLI_NAME} agent [openclaw-agent-flags...]`); + console.log(""); + console.log( + " Pass-through to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`.", + ); + console.log(" All flags accepted by the in-sandbox OpenClaw CLI are forwarded verbatim."); + console.log( + " Common flags: -m , --session-id , --agent , --json, --thinking .", + ); + console.log(""); + console.log( + " Currently supported on OpenClaw sandboxes only; Hermes sandboxes are rejected with a", + ); + console.log(" redirect to the OpenAI-compatible API on port 8642 inside the sandbox."); + console.log(""); +} diff --git a/src/lib/actions/sandbox/agent/passthrough.test.ts b/src/lib/actions/sandbox/agent/passthrough.test.ts new file mode 100644 index 00000000000..7f5b7bc0f7c --- /dev/null +++ b/src/lib/actions/sandbox/agent/passthrough.test.ts @@ -0,0 +1,81 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import { describe, expect, it, vi } from "vitest"; + +const execMock = vi.hoisted(() => vi.fn(async () => {})); +const ensureLiveMock = vi.hoisted(() => vi.fn(async () => ({}))); +const getSandboxMock = vi.hoisted(() => vi.fn(() => null as { agent?: string } | null)); + +vi.mock("../exec", () => ({ execSandbox: execMock })); +vi.mock("../gateway-state", () => ({ ensureLiveSandboxOrExit: ensureLiveMock })); +vi.mock("../../../state/registry", () => ({ getSandbox: getSandboxMock })); + +import { runAgentPassthrough } from "./passthrough"; + +describe("runAgentPassthrough", () => { + function makeProcMock() { + const writes: string[] = []; + const exit = vi.fn((code: number) => { + throw new Error(`__exit:${code}`); + }); + return { + writes, + exit, + proc: { + exit: exit as unknown as (code: number) => never, + stderr: { write: (s: string) => writes.push(s) }, + }, + }; + } + + it("rejects Hermes sandboxes with a redirect to the OpenAI-compatible API", async () => { + execMock.mockClear(); + ensureLiveMock.mockClear(); + getSandboxMock.mockReturnValueOnce({ agent: "hermes" }); + const { writes, exit, proc } = makeProcMock(); + await expect( + runAgentPassthrough("alpha", { extraArgs: ["-m", "hi"] }, { process: proc }), + ).rejects.toThrow("__exit:2"); + expect(execMock).not.toHaveBeenCalled(); + expect(ensureLiveMock).not.toHaveBeenCalled(); + expect(exit).toHaveBeenCalledWith(2); + expect(writes.join("")).toMatch(/supported only on OpenClaw sandboxes \(got 'hermes'\)/); + expect(writes.join("")).toMatch(/port 8642/); + }); + + it("forwards extraArgs verbatim to `openclaw agent` for OpenClaw sandboxes", async () => { + execMock.mockClear(); + ensureLiveMock.mockClear(); + getSandboxMock.mockReturnValueOnce({ agent: "openclaw" }); + await runAgentPassthrough("alpha", { + extraArgs: ["--agent", "work", "--session-id", "s-1", "-m", "ping", "--json"], + }); + expect(ensureLiveMock).toHaveBeenCalledWith("alpha", { allowNonReadyPhase: true }); + expect(execMock).toHaveBeenCalledWith("alpha", [ + "openclaw", + "agent", + "--agent", + "work", + "--session-id", + "s-1", + "-m", + "ping", + "--json", + ]); + }); + + it("treats an unknown sandbox as OpenClaw (registry miss should not block)", async () => { + execMock.mockClear(); + getSandboxMock.mockReturnValueOnce(null); + await runAgentPassthrough("ghost", { extraArgs: ["-m", "hi"] }); + expect(execMock).toHaveBeenCalledWith("ghost", ["openclaw", "agent", "-m", "hi"]); + }); + + it("works with no extraArgs (prints upstream openclaw agent help inside the sandbox)", async () => { + execMock.mockClear(); + getSandboxMock.mockReturnValueOnce({ agent: "openclaw" }); + await runAgentPassthrough("alpha"); + expect(execMock).toHaveBeenCalledWith("alpha", ["openclaw", "agent"]); + }); +}); diff --git a/src/lib/actions/sandbox/agent/passthrough.ts b/src/lib/actions/sandbox/agent/passthrough.ts new file mode 100644 index 00000000000..2183c2e6fe2 --- /dev/null +++ b/src/lib/actions/sandbox/agent/passthrough.ts @@ -0,0 +1,72 @@ +// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. +// SPDX-License-Identifier: Apache-2.0 + +import * as registry from "../../../state/registry"; +import { execSandbox } from "../exec"; +import { ensureLiveSandboxOrExit } from "../gateway-state"; + +export { + hasAgentPassthroughHelpToken, + printAgentPassthroughHelp, +} from "./passthrough-help"; + +export interface AgentPassthroughOptions { + extraArgs?: readonly string[]; +} + +export interface AgentPassthroughDeps { + getSandbox?: typeof registry.getSandbox; + ensureLive?: typeof ensureLiveSandboxOrExit; + exec?: typeof execSandbox; + process?: { + exit(code: number): never; + stderr: { write(s: string): unknown }; + }; +} + +function resolveSandboxAgent( + sandboxName: string, + getSandbox: typeof registry.getSandbox = registry.getSandbox, +): string | null { + try { + const sandbox = getSandbox(sandboxName); + return sandbox?.agent ?? null; + } catch { + return null; + } +} + +function rejectNonOpenclawAgent( + sandboxName: string, + agent: string, + proc: NonNullable, +): never { + proc.stderr.write( + ` agent is currently supported only on OpenClaw sandboxes (got '${agent}').\n`, + ); + proc.stderr.write( + " Hermes exposes an OpenAI-compatible API on port 8642 inside the sandbox;\n", + ); + proc.stderr.write( + ` forward it with 'openshell forward start --background 8642 ${sandboxName}'\n`, + ); + proc.stderr.write(" and POST to http://127.0.0.1:8642/v1/chat/completions instead.\n"); + return proc.exit(2); +} + +export async function runAgentPassthrough( + sandboxName: string, + { extraArgs = [] }: AgentPassthroughOptions = {}, + deps: AgentPassthroughDeps = {}, +): Promise { + const proc = deps.process ?? process; + const agent = resolveSandboxAgent(sandboxName, deps.getSandbox); + if (agent && agent !== "openclaw") { + rejectNonOpenclawAgent(sandboxName, agent, proc); + } + const ensureLive = deps.ensureLive ?? ensureLiveSandboxOrExit; + await ensureLive(sandboxName, { allowNonReadyPhase: true }); + const command = ["openclaw", "agent", ...extraArgs]; + const exec = deps.exec ?? execSandbox; + await exec(sandboxName, command); +} diff --git a/src/lib/actions/sandbox/prompt.test.ts b/src/lib/actions/sandbox/prompt.test.ts deleted file mode 100644 index 062ff9dd52d..00000000000 --- a/src/lib/actions/sandbox/prompt.test.ts +++ /dev/null @@ -1,177 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -import { mkdtempSync, writeFileSync } from "node:fs"; -import { tmpdir } from "node:os"; -import { join } from "node:path"; - -import { describe, expect, it, vi } from "vitest"; - -import { - buildOpenclawAgentArgs, - promptSandbox, - readPromptText, -} from "./prompt"; - -describe("buildOpenclawAgentArgs", () => { - it("defaults to the 'main' agent profile when none is supplied", () => { - expect(buildOpenclawAgentArgs("hi")).toEqual([ - "openclaw", - "agent", - "--agent", - "main", - "-m", - "hi", - ]); - }); - - it("honours an explicit agent profile", () => { - expect(buildOpenclawAgentArgs("hello", { agentProfile: "chess-bot" })).toEqual([ - "openclaw", - "agent", - "--agent", - "chess-bot", - "-m", - "hello", - ]); - }); - - it("falls back to the default profile when the supplied value is empty", () => { - expect(buildOpenclawAgentArgs("hi", { agentProfile: "" })).toEqual([ - "openclaw", - "agent", - "--agent", - "main", - "-m", - "hi", - ]); - }); - - it("preserves the prompt body verbatim, including shell metacharacters", () => { - const text = 'Summarise $HOME && echo "done"'; - expect(buildOpenclawAgentArgs(text)).toContain(text); - }); -}); - -describe("readPromptText", () => { - it("returns the inline text when supplied", () => { - expect(readPromptText("hello", undefined)).toBe("hello"); - }); - - it("reads from a file path when --prompt-file is a real path", () => { - const dir = mkdtempSync(join(tmpdir(), "prompt-")); - const path = join(dir, "p.txt"); - writeFileSync(path, "file body\n"); - expect(readPromptText(undefined, path)).toBe("file body\n"); - }); - - it("rejects both inline text and --prompt-file together", () => { - expect(() => readPromptText("inline", "/tmp/x")).toThrow(/either a positional prompt or --prompt-file/); - }); - - it("rejects neither inline nor --prompt-file", () => { - expect(() => readPromptText(undefined, undefined)).toThrow(/positional argument or via --prompt-file/); - }); -}); - -describe("promptSandbox", () => { - function makeDeps(agent: string | null) { - const writes: string[] = []; - const exit = vi.fn((code: number) => { - throw new Error(`__exit:${code}`); - }); - const spawn = vi.fn((..._args: unknown[]) => ({ status: 0 })); - return { - writes, - exit, - spawn, - deps: { - getSandbox: vi.fn(() => (agent ? ({ name: "alpha", agent } as any) : null)), - getOpenshellBinary: () => "/usr/local/bin/openshell", - spawn: spawn as unknown as typeof import("node:child_process").spawnSync, - process: { - exit: exit as unknown as (code: number) => never, - stderr: { write: (s: string) => writes.push(s) }, - }, - }, - }; - } - - it("rejects Hermes sandboxes with a redirect to the OpenAI-compatible API", async () => { - const { writes, exit, spawn, deps } = makeDeps("hermes"); - await expect(promptSandbox("alpha", "hi", {}, deps)).rejects.toThrow("__exit:2"); - expect(spawn).not.toHaveBeenCalled(); - expect(exit).toHaveBeenCalledWith(2); - expect(writes.join("")).toMatch(/supported only on OpenClaw sandboxes \(got 'hermes'\)/); - expect(writes.join("")).toMatch(/port 8642/); - }); - - it("invokes openshell sandbox exec with the openclaw agent argv for OpenClaw sandboxes", async () => { - const { spawn, deps } = makeDeps("openclaw"); - await expect(promptSandbox("alpha", "hi", {}, deps)).rejects.toThrow("__exit:0"); - expect(spawn).toHaveBeenCalledTimes(1); - const [bin, argv, options] = spawn.mock.calls[0] as [string, string[], unknown]; - expect(bin).toBe("/usr/local/bin/openshell"); - expect(argv).toEqual([ - "sandbox", - "exec", - "--name", - "alpha", - "--no-tty", - "--", - "openclaw", - "agent", - "--agent", - "main", - "-m", - "hi", - ]); - expect(options).toEqual({ stdio: "inherit" }); - }); - - it("propagates --agent, --workdir and --timeout into the inner argv", async () => { - const { spawn, deps } = makeDeps("openclaw"); - await expect( - promptSandbox( - "alpha", - "list", - { - agentProfile: "chess-bot", - workdir: "/sandbox/workspace", - timeoutSeconds: 30, - }, - deps, - ), - ).rejects.toThrow("__exit:0"); - const [, rawArgv] = spawn.mock.calls[0] as [string, string[]]; - const argv = rawArgv; - expect(argv).toContain("--workdir"); - expect(argv).toContain("/sandbox/workspace"); - expect(argv).toContain("--timeout"); - expect(argv).toContain("30"); - expect(argv).toContain("--no-tty"); - const dashDash = argv.indexOf("--"); - expect(argv.slice(dashDash + 1)).toEqual([ - "openclaw", - "agent", - "--agent", - "chess-bot", - "-m", - "list", - ]); - }); - - it("treats an unknown sandbox as OpenClaw (registry miss should not block)", async () => { - const { spawn, deps } = makeDeps(null); - await expect(promptSandbox("ghost", "hi", {}, deps)).rejects.toThrow("__exit:0"); - expect(spawn).toHaveBeenCalledTimes(1); - }); - - it("exits 2 with a clear message when no prompt body is supplied", async () => { - const { writes, exit, spawn, deps } = makeDeps("openclaw"); - await expect(promptSandbox("alpha", undefined, {}, deps)).rejects.toThrow("__exit:2"); - expect(spawn).not.toHaveBeenCalled(); - expect(exit).toHaveBeenCalledWith(2); - expect(writes.join("")).toMatch(/positional argument or via --prompt-file/); - }); -}); diff --git a/src/lib/actions/sandbox/prompt.ts b/src/lib/actions/sandbox/prompt.ts deleted file mode 100644 index 7a4c332bee3..00000000000 --- a/src/lib/actions/sandbox/prompt.ts +++ /dev/null @@ -1,134 +0,0 @@ -// SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. -// SPDX-License-Identifier: Apache-2.0 - -import { spawnSync } from "node:child_process"; -import { readFileSync } from "node:fs"; -import os from "node:os"; - -import * as registry from "../../state/registry"; -import { buildOpenshellExecArgs, computeExitCode } from "./exec"; - -export type SandboxPromptOptions = { - agentProfile?: string; - workdir?: string; - timeoutSeconds?: number; - promptFile?: string; -}; - -type SpawnLikeResult = { - status: number | null; - signal?: NodeJS.Signals | null; - error?: Error; -}; - -const DEFAULT_AGENT_PROFILE = "main"; - -export function buildOpenclawAgentArgs( - text: string, - options: SandboxPromptOptions = {}, -): string[] { - return [ - "openclaw", - "agent", - "--agent", - options.agentProfile || DEFAULT_AGENT_PROFILE, - "-m", - text, - ]; -} - -export function readPromptText(text: string | undefined, promptFile: string | undefined): string { - const hasInline = typeof text === "string" && text.length > 0; - const hasFile = typeof promptFile === "string" && promptFile.length > 0; - if (hasInline && hasFile) { - throw new Error("Pass either a positional prompt or --prompt-file, not both."); - } - if (hasInline) return text as string; - if (hasFile) { - const source = promptFile === "-" ? 0 : (promptFile as string); - return readFileSync(source, "utf8"); - } - throw new Error("Provide a prompt as a positional argument or via --prompt-file ."); -} - -function exitWithSpawnResult( - result: SpawnLikeResult, - proc: PromptProcess, -): never { - const { code, errorMessage } = computeExitCode(result); - if (errorMessage) { - proc.stderr.write(` Failed to invoke openshell: ${errorMessage}\n`); - proc.stderr.write(" Ensure 'openshell' is installed and on PATH.\n"); - } - proc.exit(code); -} - -type PromptProcess = { - exit(code: number): never; - stderr: { write(s: string): unknown }; -}; - -function resolveSandboxAgent( - sandboxName: string, - getSandbox: typeof registry.getSandbox = registry.getSandbox, -): string | null { - try { - const sandbox = getSandbox(sandboxName); - return sandbox?.agent ?? null; - } catch { - return null; - } -} - -export type PromptDeps = { - getSandbox?: typeof registry.getSandbox; - getOpenshellBinary?: () => string; - spawn?: typeof spawnSync; - process?: PromptProcess; -}; - -export async function promptSandbox( - sandboxName: string, - text: string | undefined, - options: SandboxPromptOptions = {}, - deps: PromptDeps = {}, -): Promise { - const proc = deps.process ?? process; - const agent = resolveSandboxAgent(sandboxName, deps.getSandbox); - if (agent && agent !== "openclaw") { - proc.stderr.write( - ` prompt is currently supported only on OpenClaw sandboxes (got '${agent}').\n`, - ); - proc.stderr.write( - " Hermes exposes an OpenAI-compatible API on port 8642 inside the sandbox;\n", - ); - proc.stderr.write( - ` forward it with 'openshell forward start --background 8642 ${sandboxName}'\n`, - ); - proc.stderr.write(" and POST to http://127.0.0.1:8642/v1/chat/completions instead.\n"); - proc.exit(2); - } - - let body: string; - try { - body = readPromptText(text, options.promptFile); - } catch (error) { - proc.stderr.write(` ${(error as Error).message}\n`); - return proc.exit(2); - } - - const innerCommand = buildOpenclawAgentArgs(body, options); - const argv = buildOpenshellExecArgs(sandboxName, innerCommand, { - workdir: options.workdir, - tty: false, - timeoutSeconds: options.timeoutSeconds, - }); - const openshellBinary = - deps.getOpenshellBinary?.() ?? require("../../adapters/openshell/runtime").getOpenshellBinary(); - const spawn = deps.spawn ?? spawnSync; - const result = spawn(openshellBinary, argv, { stdio: "inherit" }); - if (result.status === null && !result.error && !result.signal) { - proc.stderr.write(` openshell exited without status (uname=${os.type()}).\n`); - } - exitWithSpawnResult(result, proc); -} diff --git a/src/lib/cli/public-display-defaults.ts b/src/lib/cli/public-display-defaults.ts index 8c3d7037c49..6947a61cc0a 100644 --- a/src/lib/cli/public-display-defaults.ts +++ b/src/lib/cli/public-display-defaults.ts @@ -250,11 +250,11 @@ const PUBLIC_DISPLAY_LAYOUT: Record = { flags: "[--workdir ] [--tty|--no-tty] [--timeout ] -- [args...]", }, ], - "sandbox:prompt": [ + "sandbox:agent": [ { group: "Sandbox Management", order: 4.6, - flags: "[--agent ] [--workdir ] [--timeout ] [--prompt-file ] []", + flags: "[openclaw-agent-flags...]", }, ], "sandbox:upload": [ From d685e9bc508461d2a8a7fa4272a8bcc80377c14a Mon Sep 17 00:00:00 2001 From: Tinson Lai Date: Sat, 13 Jun 2026 20:36:08 +0000 Subject: [PATCH 3/4] fix(sandbox): fail closed on registry-read error and enforce no-tty for agent passthrough Signed-off-by: Tinson Lai --- docs/reference/commands.mdx | 2 +- .../actions/sandbox/agent/passthrough.test.ts | 47 ++++++++---- src/lib/actions/sandbox/agent/passthrough.ts | 76 ++++++++++++++++--- src/lib/cli/command-registry.test.ts | 16 ++-- src/lib/cli/public-display-defaults.ts | 2 +- 5 files changed, 106 insertions(+), 37 deletions(-) diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 699e654cbc1..7f982979386 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -547,7 +547,7 @@ $$nemoclaw my-assistant agent --session-id review-42 -m "Any new findings?" $$nemoclaw my-assistant agent --json -m 'ping' ``` -The exit code is the remote command's exit code, so host-side pipelines can branch on it. Streaming follows whatever `openclaw agent` already emits on stdout; no additional buffering is added. +The exit code is the remote command's exit code, so host-side pipelines can branch on it. Streaming follows whatever `openclaw agent` already emits on `stdout`; no additional buffering is added. Common upstream flags include `-m `, `--session-id `, `--agent `, `--model `, `--thinking `, `--json`, `--deliver`, `--reply-channel `, and `--timeout `. Run `$$nemoclaw agent --help` for the wrapper-level summary, or invoke `$$nemoclaw exec -- openclaw agent --help` to view the upstream OpenClaw help text directly. diff --git a/src/lib/actions/sandbox/agent/passthrough.test.ts b/src/lib/actions/sandbox/agent/passthrough.test.ts index 7f5b7bc0f7c..d7fc1d55aaa 100644 --- a/src/lib/actions/sandbox/agent/passthrough.test.ts +++ b/src/lib/actions/sandbox/agent/passthrough.test.ts @@ -44,7 +44,7 @@ describe("runAgentPassthrough", () => { expect(writes.join("")).toMatch(/port 8642/); }); - it("forwards extraArgs verbatim to `openclaw agent` for OpenClaw sandboxes", async () => { + it("forwards extraArgs verbatim to `openclaw agent` for OpenClaw sandboxes with --no-tty enforced", async () => { execMock.mockClear(); ensureLiveMock.mockClear(); getSandboxMock.mockReturnValueOnce({ agent: "openclaw" }); @@ -52,30 +52,45 @@ describe("runAgentPassthrough", () => { extraArgs: ["--agent", "work", "--session-id", "s-1", "-m", "ping", "--json"], }); expect(ensureLiveMock).toHaveBeenCalledWith("alpha", { allowNonReadyPhase: true }); - expect(execMock).toHaveBeenCalledWith("alpha", [ - "openclaw", - "agent", - "--agent", - "work", - "--session-id", - "s-1", - "-m", - "ping", - "--json", - ]); + expect(execMock).toHaveBeenCalledWith( + "alpha", + ["openclaw", "agent", "--agent", "work", "--session-id", "s-1", "-m", "ping", "--json"], + { tty: false }, + ); }); - it("treats an unknown sandbox as OpenClaw (registry miss should not block)", async () => { + it("treats a clean registry miss as OpenClaw (preserves bootstrap and recovery paths)", async () => { execMock.mockClear(); getSandboxMock.mockReturnValueOnce(null); await runAgentPassthrough("ghost", { extraArgs: ["-m", "hi"] }); - expect(execMock).toHaveBeenCalledWith("ghost", ["openclaw", "agent", "-m", "hi"]); + expect(execMock).toHaveBeenCalledWith("ghost", ["openclaw", "agent", "-m", "hi"], { + tty: false, + }); + }); + + it("fails closed when the registry read throws and never spawns OpenShell exec", async () => { + execMock.mockClear(); + ensureLiveMock.mockClear(); + getSandboxMock.mockImplementationOnce(() => { + throw new Error("EACCES: permission denied, open '~/.config/nemoclaw/sandboxes.json'"); + }); + const { writes, exit, proc } = makeProcMock(); + await expect( + runAgentPassthrough("alpha", { extraArgs: ["-m", "hi"] }, { process: proc }), + ).rejects.toThrow("__exit:2"); + expect(execMock).not.toHaveBeenCalled(); + expect(ensureLiveMock).not.toHaveBeenCalled(); + expect(exit).toHaveBeenCalledWith(2); + const all = writes.join(""); + expect(all).toMatch(/Could not read the local sandbox registry/); + expect(all).toMatch(/Refusing to forward/); + expect(all).toMatch(/EACCES/); }); - it("works with no extraArgs (prints upstream openclaw agent help inside the sandbox)", async () => { + it("works with no extraArgs and still enforces --no-tty", async () => { execMock.mockClear(); getSandboxMock.mockReturnValueOnce({ agent: "openclaw" }); await runAgentPassthrough("alpha"); - expect(execMock).toHaveBeenCalledWith("alpha", ["openclaw", "agent"]); + expect(execMock).toHaveBeenCalledWith("alpha", ["openclaw", "agent"], { tty: false }); }); }); diff --git a/src/lib/actions/sandbox/agent/passthrough.ts b/src/lib/actions/sandbox/agent/passthrough.ts index 2183c2e6fe2..94af43230e6 100644 --- a/src/lib/actions/sandbox/agent/passthrough.ts +++ b/src/lib/actions/sandbox/agent/passthrough.ts @@ -1,6 +1,36 @@ // SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved. // SPDX-License-Identifier: Apache-2.0 +// Source-of-truth boundary for the `nemoclaw agent` passthrough: +// +// - Invalid state: the local registry is the source of truth for which agent a +// sandbox runs (openclaw vs hermes vs future variants). Forwarding to +// `openclaw agent` against a non-OpenClaw sandbox triggers an in-sandbox +// binary that does not exist (or exists with incompatible flags), and would +// silently bypass the host-side guard intended to redirect Hermes callers to +// the OpenAI-compatible API on port 8642. +// +// - Source boundary: this wrapper owns the host-side guard only; the in-sandbox +// agent invocation, its argv contract, and its streaming behaviour are owned +// by upstream OpenClaw. NemoClaw does not rewrite OpenClaw flags here; it +// forwards them verbatim. +// +// - Source-fix constraint: NemoClaw cannot prove agent type from anywhere +// except the registry, because the OpenShell exec transport has no +// pre-execution probe that reveals the sandbox's configured agent. A +// registry read failure therefore has to fail closed — silently degrading +// to OpenClaw-as-default would let a Hermes-onboarded sandbox dispatch the +// wrong binary on transient I/O errors. +// +// - Regression tests: `passthrough.test.ts` covers the Hermes redirect, the +// forwarded argv, the registry-miss fallback to OpenClaw, the registry-error +// fail-closed path, and the enforced `--no-tty` argv shape. +// +// - Removal condition: when OpenShell exposes a metadata endpoint that returns +// the sandbox's configured agent, drop the registry read and consult that +// endpoint directly. The fail-closed branch can then be retired in favour of +// the live source. + import * as registry from "../../../state/registry"; import { execSandbox } from "../exec"; import { ensureLiveSandboxOrExit } from "../gateway-state"; @@ -24,15 +54,21 @@ export interface AgentPassthroughDeps { }; } -function resolveSandboxAgent( +type RegistryReadResult = + | { kind: "missing" } + | { kind: "agent"; agent: string | null } + | { kind: "error"; message: string }; + +function readSandboxAgentFromRegistry( sandboxName: string, getSandbox: typeof registry.getSandbox = registry.getSandbox, -): string | null { +): RegistryReadResult { try { const sandbox = getSandbox(sandboxName); - return sandbox?.agent ?? null; - } catch { - return null; + if (!sandbox) return { kind: "missing" }; + return { kind: "agent", agent: sandbox.agent ?? null }; + } catch (error) { + return { kind: "error", message: (error as Error).message ?? String(error) }; } } @@ -44,9 +80,7 @@ function rejectNonOpenclawAgent( proc.stderr.write( ` agent is currently supported only on OpenClaw sandboxes (got '${agent}').\n`, ); - proc.stderr.write( - " Hermes exposes an OpenAI-compatible API on port 8642 inside the sandbox;\n", - ); + proc.stderr.write(" Hermes exposes an OpenAI-compatible API on port 8642 inside the sandbox;\n"); proc.stderr.write( ` forward it with 'openshell forward start --background 8642 ${sandboxName}'\n`, ); @@ -54,19 +88,37 @@ function rejectNonOpenclawAgent( return proc.exit(2); } +function rejectRegistryReadError( + sandboxName: string, + message: string, + proc: NonNullable, +): never { + proc.stderr.write( + ` Could not read the local sandbox registry to confirm agent type for '${sandboxName}'.\n`, + ); + proc.stderr.write(` Registry read error: ${message}\n`); + proc.stderr.write( + " Refusing to forward to `openclaw agent` because the agent guard cannot fail closed.\n", + ); + return proc.exit(2); +} + export async function runAgentPassthrough( sandboxName: string, { extraArgs = [] }: AgentPassthroughOptions = {}, deps: AgentPassthroughDeps = {}, ): Promise { const proc = deps.process ?? process; - const agent = resolveSandboxAgent(sandboxName, deps.getSandbox); - if (agent && agent !== "openclaw") { - rejectNonOpenclawAgent(sandboxName, agent, proc); + const lookup = readSandboxAgentFromRegistry(sandboxName, deps.getSandbox); + if (lookup.kind === "error") { + rejectRegistryReadError(sandboxName, lookup.message, proc); + } + if (lookup.kind === "agent" && lookup.agent && lookup.agent !== "openclaw") { + rejectNonOpenclawAgent(sandboxName, lookup.agent, proc); } const ensureLive = deps.ensureLive ?? ensureLiveSandboxOrExit; await ensureLive(sandboxName, { allowNonReadyPhase: true }); const command = ["openclaw", "agent", ...extraArgs]; const exec = deps.exec ?? execSandbox; - await exec(sandboxName, command); + await exec(sandboxName, command, { tty: false }); } diff --git a/src/lib/cli/command-registry.test.ts b/src/lib/cli/command-registry.test.ts index 708dd33a7e3..d756f82bd50 100644 --- a/src/lib/cli/command-registry.test.ts +++ b/src/lib/cli/command-registry.test.ts @@ -55,12 +55,13 @@ describe("command-registry", () => { }); describe("sandboxCommands()", () => { - it("should return exactly 47 entries", () => { - // 41 visible + 6 hidden (shields×3 + config get/set/rotate-token). - // 41 visible includes the sessions group (root + list + reset + delete + - // export), the agents trio (add + delete + list), and the download + + it("should return exactly 48 entries", () => { + // 42 visible + 6 hidden (shields×3 + config get/set/rotate-token). + // 42 visible includes the sessions group (root + list + reset + delete + + // export), the agents trio (add + delete + list), the singular `agent` + // passthrough that forwards to `openclaw agent`, and the download + // upload host-side openshell wrappers. - expect(sandboxCommands()).toHaveLength(47); + expect(sandboxCommands()).toHaveLength(48); }); it("every entry has scope sandbox", () => { @@ -214,11 +215,12 @@ describe("command-registry", () => { }); describe("sandboxActionTokens()", () => { - it("returns exactly 28 unique action tokens including empty string", () => { + it("returns exactly 29 unique action tokens including empty string", () => { const tokens = sandboxActionTokens(); - expect(tokens).toHaveLength(28); + expect(tokens).toHaveLength(29); // Must contain every first-level sandbox action plus the empty default action. const expected = new Set([ + "agent", "agents", "connect", "dashboard-url", diff --git a/src/lib/cli/public-display-defaults.ts b/src/lib/cli/public-display-defaults.ts index 6947a61cc0a..626ef47c9a4 100644 --- a/src/lib/cli/public-display-defaults.ts +++ b/src/lib/cli/public-display-defaults.ts @@ -253,7 +253,7 @@ const PUBLIC_DISPLAY_LAYOUT: Record = { "sandbox:agent": [ { group: "Sandbox Management", - order: 4.6, + order: 4.55, flags: "[openclaw-agent-flags...]", }, ], From 450e543f8727c9d90656edc4966d47302f7ebed4 Mon Sep 17 00:00:00 2001 From: Tinson Lai Date: Sun, 14 Jun 2026 04:12:09 +0000 Subject: [PATCH 4/4] docs(sandbox): tighten agent wrapper voice and disambiguate non-openclaw reject Signed-off-by: Tinson Lai --- docs/reference/commands-nemohermes.mdx | 4 ++-- docs/reference/commands.mdx | 6 +++--- src/lib/actions/sandbox/agent/passthrough.test.ts | 4 +++- src/lib/actions/sandbox/agent/passthrough.ts | 2 +- 4 files changed, 9 insertions(+), 7 deletions(-) diff --git a/docs/reference/commands-nemohermes.mdx b/docs/reference/commands-nemohermes.mdx index da9a84af96d..0f60d3464f9 100644 --- a/docs/reference/commands-nemohermes.mdx +++ b/docs/reference/commands-nemohermes.mdx @@ -435,10 +435,10 @@ The exit code is the remote command's exit code. ### `nemohermes agent` Run one OpenClaw agent turn non-interactively in a running sandbox. -The command is a thin pass-through to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. +This command forwards every argument verbatim to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal. -`agent` is currently supported only on OpenClaw sandboxes. Hermes already exposes an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. +Only OpenClaw sandboxes support the `agent` wrapper today; Hermes sandboxes already expose an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. Forward the port and POST chat completions directly: diff --git a/docs/reference/commands.mdx b/docs/reference/commands.mdx index 7f982979386..268a2d55714 100644 --- a/docs/reference/commands.mdx +++ b/docs/reference/commands.mdx @@ -533,7 +533,7 @@ The exit code is the remote command's exit code. ### `$$nemoclaw agent` Run one OpenClaw agent turn non-interactively in a running sandbox. -The command is a thin pass-through to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. +This command forwards every argument verbatim to `openclaw agent ...` inside the sandbox via `openshell sandbox exec`, with `HOME=/sandbox` so the addressed agent profile resolves the same way as `connect`. Use this when driving the sandbox programmatically from another process (CI job, multi-agent platform, evaluation harness) rather than from an interactive terminal. @@ -547,14 +547,14 @@ $$nemoclaw my-assistant agent --session-id review-42 -m "Any new findings?" $$nemoclaw my-assistant agent --json -m 'ping' ``` -The exit code is the remote command's exit code, so host-side pipelines can branch on it. Streaming follows whatever `openclaw agent` already emits on `stdout`; no additional buffering is added. +The wrapper inherits the remote command's exit code, so host-side pipelines can branch on it. Streaming forwards whatever `openclaw agent` already emits on `stdout`; the wrapper adds no buffering. Common upstream flags include `-m `, `--session-id `, `--agent `, `--model `, `--thinking `, `--json`, `--deliver`, `--reply-channel `, and `--timeout `. Run `$$nemoclaw agent --help` for the wrapper-level summary, or invoke `$$nemoclaw exec -- openclaw agent --help` to view the upstream OpenClaw help text directly. -`agent` is currently supported only on OpenClaw sandboxes. Hermes already exposes an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. +Only OpenClaw sandboxes support the `agent` wrapper today; Hermes sandboxes already expose an OpenAI-compatible HTTP API on port `8642` inside the sandbox, so non-interactive use does not need a wrapper command. Forward the port and POST chat completions directly: diff --git a/src/lib/actions/sandbox/agent/passthrough.test.ts b/src/lib/actions/sandbox/agent/passthrough.test.ts index d7fc1d55aaa..af2169408ef 100644 --- a/src/lib/actions/sandbox/agent/passthrough.test.ts +++ b/src/lib/actions/sandbox/agent/passthrough.test.ts @@ -40,7 +40,9 @@ describe("runAgentPassthrough", () => { expect(execMock).not.toHaveBeenCalled(); expect(ensureLiveMock).not.toHaveBeenCalled(); expect(exit).toHaveBeenCalledWith(2); - expect(writes.join("")).toMatch(/supported only on OpenClaw sandboxes \(got 'hermes'\)/); + expect(writes.join("")).toMatch( + /Only OpenClaw sandboxes support the `sandbox agent` wrapper today \(sandbox 'alpha' runs 'hermes'\)/, + ); expect(writes.join("")).toMatch(/port 8642/); }); diff --git a/src/lib/actions/sandbox/agent/passthrough.ts b/src/lib/actions/sandbox/agent/passthrough.ts index 94af43230e6..80a17dcbbc8 100644 --- a/src/lib/actions/sandbox/agent/passthrough.ts +++ b/src/lib/actions/sandbox/agent/passthrough.ts @@ -78,7 +78,7 @@ function rejectNonOpenclawAgent( proc: NonNullable, ): never { proc.stderr.write( - ` agent is currently supported only on OpenClaw sandboxes (got '${agent}').\n`, + ` Only OpenClaw sandboxes support the \`sandbox agent\` wrapper today (sandbox '${sandboxName}' runs '${agent}').\n`, ); proc.stderr.write(" Hermes exposes an OpenAI-compatible API on port 8642 inside the sandbox;\n"); proc.stderr.write(