Skip to content
Merged
Show file tree
Hide file tree
Changes from 1 commit
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 17 additions & 0 deletions docs/reference/commands-nemohermes.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <seconds>` | Timeout in seconds (`0` means no timeout) |

### `nemohermes <name> 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":"<onboarded-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.
Expand Down
44 changes: 44 additions & 0 deletions docs/reference/commands.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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 <seconds>` | Timeout in seconds (`0` means no timeout) |

### `$$nemoclaw <name> 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.

<AgentOnly variant="openclaw">

The prompt is forwarded to `openclaw agent --agent <profile> -m <text>` inside the sandbox, where `<profile>` 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 <path>` 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 <profile>` | OpenClaw agent profile to address (default: `main`) |
| `--workdir <dir>` | Working directory inside the sandbox |
| `--timeout <seconds>` | Timeout in seconds (`0` means no timeout) |
| `--prompt-file <path\|->` | Read the prompt body from a file path, or `-` for stdin |

</AgentOnly>
<AgentOnly variant="hermes">

`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":"<onboarded-model>","messages":[{"role":"user","content":"What is 2+2?"}],"stream":true}'
```

</AgentOnly>

### 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.
Expand Down
71 changes: 71 additions & 0 deletions src/commands/sandbox/prompt.test.ts
Original file line number Diff line number Diff line change
@@ -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: "-",
});
});
});
53 changes: 53 additions & 0 deletions src/commands/sandbox/prompt.ts
Original file line number Diff line number Diff line change
@@ -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 = [
"<name> [--agent <profile>] [--workdir <dir>] [--timeout <s>] [--prompt-file <path|->] [<text>]",
];
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<void> {
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"],
});
}
}
177 changes: 177 additions & 0 deletions src/lib/actions/sandbox/prompt.test.ts
Original file line number Diff line number Diff line change
@@ -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/);
});
});
Loading
Loading