Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
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
21 changes: 9 additions & 12 deletions controller/cli.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -224,21 +224,18 @@ async function cmdSessions(s, [vm, flag]) {
say(rows.length ? `[\n${rows.join(",\n")}\n]` : "[]");
}

/** prompt NAME "task" — a headless pi task in a detached tmux window, logged to ~/project/.boxery/ @param {Selected} s @param {string[]} args @returns {Promise<void>} */
/** What prompt runs in the VM (pi's print mode) and the job-log flag it points at: constants, so the flags are not prompt's own. */
const PI_PRINT = ["pi", "-p"], LOG_FOLLOW = "-f";
/** prompt NAME "task" — a headless pi task, started as a background job (pi -p TASK in ~/project) @param {Selected} s @param {string[]} args @returns {Promise<void>} */
async function cmdPrompt(s, [name = "", ...words]) {
needVm(name);
const prompt = words.join(" ");
if (!prompt) usage("prompt");
await needPiGrant(s, name);
const d = new Date(), p2 = (/** @type {number} */ n) => String(n).padStart(2, "0");
const id = `task-${d.getFullYear()}${p2(d.getMonth() + 1)}${p2(d.getDate())}-${p2(d.getHours())}${p2(d.getMinutes())}${p2(d.getSeconds())}`;
const b64 = Buffer.from(prompt).toString("base64");
// Ship the prompt base64-encoded and write a tiny runner script: no nested shell quoting.
const script = `set -e; d=~/project/.boxery; mkdir -p $d; echo ${b64} | base64 -d > $d/${id}.prompt
printf '%s\\n' '#!/bin/bash -l' 'cd ~/project' 'pi -p "$(cat .boxery/${id}.prompt)" </dev/null 2>&1 | tee .boxery/${id}.log' 'echo "[boxery] task finished (exit \${PIPESTATUS[0]})" | tee -a .boxery/${id}.log' 'exec bash -l' > $d/${id}.sh
chmod +x $d/${id}.sh; tmux new-session -d -s ${id} -c ~/project $d/${id}.sh`;
await exitWith(vmSsh(s, [`${name}.boxery`, script]));
say(`started ${id} on ${name} — watch: ${hint("attach", [name, "pi", id])} log: ${hint("run", [name, "cat", `.boxery/${id}.log`])}`);
// A job, like run --bg: job ls, job logs -f, job wait (it exits with pi's status) and job kill work on it.
const { startJob } = await import("./jobs.mjs");
const id = await startJob(s, name, [...PI_PRINT, prompt].map((w) => Buffer.from(w)), null);
say(`started ${id} on ${name} — wait: ${hint("job wait", [name, id])} logs: ${hint("job logs", [name, id, LOG_FOLLOW])}`);
}

/** A VM has no LLM access until it is granted, and pi without it fails at once: say so before starting a
Expand Down Expand Up @@ -605,7 +602,7 @@ export const COMMANDS = {
contract: { terminal: "stdin", payload: "agent" },
},
prompt: {
help: { group: "use", summary: "start a headless pi task in its own tmux session", usage: ['prompt NAME "TASK"'], details: ["It logs to ~/project/.boxery/task-*.log in the VM; attach with boxery attach NAME pi task-…", "pi needs the llm: grant for its provider (llm:chatgpt by default); without it prompt starts nothing and says what to grant."] },
help: { group: "use", summary: "start a headless pi task as a background job", usage: ['prompt NAME "TASK"'], details: ["It runs pi -p TASK in ~/project as a background job and prints its id: job ls, job logs -f, job wait (exits with pi's status) and job kill work on it. pi -p prints its answer when it finishes, so the log can stay empty until then.", "pi needs the llm: grant for its provider (llm:chatgpt by default); without it prompt starts nothing and says what to grant."] },
run: async (s, args) => { needHost(s); await cmdPrompt(s, args); },
contract: { payload: "task" },
},
Expand All @@ -617,7 +614,7 @@ export const COMMANDS = {
agent: {
help: {
group: "families", summary: "persistent coding-agent sessions in a VM", usage: [],
details: ["Sessions are tmux sessions in the VM: they keep running when you detach or disconnect. attach and prompt are also top-level commands, for everyday use."],
details: ["attach and ls work on tmux sessions in the VM: they keep running when you detach or disconnect. prompt starts a headless task as a background job (see job). attach and prompt are also top-level commands, for everyday use."],
examples: [["Attach to pi (the same as: boxery attach demo)", "boxery agent attach demo"], ["opencode instead", "boxery agent attach demo opencode"], ["A headless task (the same as: boxery prompt …)", "boxery agent prompt demo TASK"], ["The VM's sessions", "boxery agent ls demo"]],
seeAlso: ["job"], docs: "cli.md#shell-and-in-vm-agents",
},
Expand Down
8 changes: 4 additions & 4 deletions docs/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -122,7 +122,7 @@ boxery run demo --cwd app pnpm test # in ~/project/app
boxery run demo bash -c 'make test 2>&1 | tail' # a shell line: bash -c
boxery attach demo # pi in tmux. Ctrl-b d detaches; it keeps running.
boxery attach demo opencode # or: shell
boxery prompt demo "fix the failing tests and commit" # headless pi task in its own tmux session
boxery prompt demo "fix the failing tests and commit" # headless pi task, as a background job (job wait/logs)
boxery agent ls demo [--json] # list tmux sessions
```

Expand Down Expand Up @@ -150,7 +150,7 @@ boxery --host hornet cp local:notes.md ci-1:~/notes.md

`boxery sync demo [--from DIR] [--to PATH] [--json]` pushes a local git checkout into a VM so its tree matches exactly (commits by `git push` over the VM's ssh connection, plus uncommitted and untracked changes); it is the `vm_sync` tool's own code ([sync](sync.md)).

`attach` starts pi, opencode or a shell (nothing else) and needs a terminal; without one it says to use `prompt` or `run --bg`, which work headless. `prompt` logs to `~/project/.boxery/task-*.log` in the VM. Attach to a task with `boxery attach demo pi task-…`. pi needs the `llm:` grant for its provider (`llm:chatgpt` unless you changed pi's settings in the VM), and a new VM has none: `prompt` checks first and, if it's missing, starts nothing and prints the `boxery grant` command to run (the older spelling of `boxery access grant`).
`attach` starts pi, opencode or a shell (nothing else) and needs a terminal; without one it says to use `prompt` or `run --bg`, which work headless. `prompt` starts `pi -p TASK` in `~/project` as a background job and prints its id, so `job ls`, `job logs -f`, `job wait` (exits with pi's status) and `job kill` work on it; `pi -p` prints its answer when it finishes, so the log can stay empty until then. pi needs the `llm:` grant for its provider (`llm:chatgpt` unless you changed pi's settings in the VM), and a new VM has none: `prompt` checks first and, if it's missing, starts nothing and prints the `boxery grant` command to run (the older spelling of `boxery access grant`).

### Background command jobs

Expand Down Expand Up @@ -316,7 +316,7 @@ Generated from the help `boxery help --all` shows (`controller/cli.mjs`); edit i
| `boxery desktop NAME [--no-open]` | Open a VM's desktop in your browser (noVNC over ssh) [→](#desktop-and-ports) |
| `boxery forward NAME PORT [LOCAL_PORT]` | Forward a VM port to localhost |
| `boxery attach NAME [pi\|opencode\|shell] [SESSION]` | Attach to an agent in a persistent tmux session (= agent attach) |
| `boxery prompt NAME "TASK"` | Start a headless pi task in its own tmux session (= agent prompt) |
| `boxery prompt NAME "TASK"` | Start a headless pi task as a background job (= agent prompt) |

**Command families (boxery FAMILY --help)**

Expand Down Expand Up @@ -362,7 +362,7 @@ Generated from the help `boxery help --all` shows (`controller/cli.mjs`); edit i
| Command | What it does |
|---|---|
| `boxery agent attach NAME [pi\|opencode\|shell] [SESSION]` | Attach to an agent in a persistent tmux session |
| `boxery agent prompt NAME "TASK"` | Start a headless pi task in its own tmux session |
| `boxery agent prompt NAME "TASK"` | Start a headless pi task as a background job |
| `boxery agent ls NAME [--json]` | List a VM's tmux sessions |

**boxery job — background jobs in a VM (run --bg starts one)**
Expand Down
15 changes: 10 additions & 5 deletions test/cli-families.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,13 @@ const run = (args, extra = {}) => {
};
const sshCalls = () => (existsSync(sshLog) ? readFileSync(sshLog, "utf8").trim().split("\n").filter(Boolean).map((l) => JSON.parse(l)) : []);
const calls = () => hostCalls(root);
/** The words a started job runs: the NUL-separated, base64 argv that `start` sends the VM helper. @param {{ args: string[] }} call */
const jobArgv = (call) => {
const m = /\bstart (\S+) \S+ \S+ --text$/.exec(call.args.at(-1) ?? "");
assert.ok(m, `not a job start: ${call.args.at(-1)}`);
return Buffer.from(m[1], "base64").toString().split("\0").slice(0, -1);
};

// (the first call to a host also probes its features with `help`, once: not part of a command)
/** Everything a command can have left in the registry and the profiles. @param {string} dir @returns {string[]} */
function tree(dir) {
Expand Down Expand Up @@ -372,9 +379,8 @@ test("canonical prompt keeps single help flags as task text; the legacy help con
rmSync(sshLog, { force: true });
const r = run(["agent", "prompt", "demo", flag], { BOXERY_SSH_REPLY: "\x1e{}\x1e{}\x1e{}" });
assert.equal(r.status, 0, r.stderr);
assert.match(r.stdout, /started task-/);
const script = sshCalls().at(-1).args.at(-1);
assert.equal(Buffer.from(/echo (\S+) \| base64 -d/.exec(script)?.[1] ?? "", "base64").toString(), flag);
assert.match(r.stdout, /^started \S+ on demo — wait: boxery job wait demo \S+ {3}logs: boxery job logs demo \S+ -f$/m);
assert.deepEqual(jobArgv(sshCalls().at(-1)), ["pi", "-p", flag], "pi -p TASK, started as a job");
rmSync(sshLog, { force: true });
const legacy = run(["prompt", "demo", flag]);
assert.equal(legacy.status, 0, legacy.stderr);
Expand All @@ -389,8 +395,7 @@ test("payload words are not options: prompt text, run and ssh commands keep ever
rmSync(sshLog, { force: true });
const r = run([...head, ...words]);
assert.equal(r.status, 0, r.stderr);
const script = sshCalls().at(-1).args.at(-1);
assert.equal(Buffer.from(/echo (\S+) \| base64 -d/.exec(script)?.[1] ?? "", "base64").toString(), words.join(" "), "the task, exactly");
assert.deepEqual(jobArgv(sshCalls().at(-1)), ["pi", "-p", words.join(" ")], "the task, exactly");
assert.equal(sshCalls().at(-1).profile, profile("alpha"), "--host inside the text selects nothing");
assert.equal(existsSync("pwned"), false);
}
Expand Down
4 changes: 2 additions & 2 deletions test/fixtures/boxery-help-all.txt
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Work in a VM:
desktop NAME Open a VM's desktop in your browser (noVNC over ssh)
forward NAME PORT [LOCAL] Forward a VM port to localhost
attach NAME [AGENT] Attach to an agent in a persistent tmux session (= agent attach)
prompt NAME "TASK" Start a headless pi task in its own tmux session (= agent prompt)
prompt NAME "TASK" Start a headless pi task as a background job (= agent prompt)

Command families (boxery FAMILY --help):
host add|ls|show|use|rm|… Named hosts, and maintenance of the selected host
Expand Down Expand Up @@ -59,7 +59,7 @@ boxery snapshot — saved VM disk states: create, restore, list, delete:

boxery agent — persistent coding-agent sessions in a VM:
agent attach NAME [AGENT] Attach to an agent in a persistent tmux session
agent prompt NAME "TASK" Start a headless pi task in its own tmux session
agent prompt NAME "TASK" Start a headless pi task as a background job
agent ls NAME List a VM's tmux sessions

boxery job — background jobs in a VM (run --bg starts one):
Expand Down
2 changes: 1 addition & 1 deletion test/fixtures/boxery-help.txt
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Work in a VM:
desktop NAME Open a VM's desktop in your browser (noVNC over ssh)
forward NAME PORT [LOCAL] Forward a VM port to localhost
attach NAME [AGENT] Attach to an agent in a persistent tmux session (= agent attach)
prompt NAME "TASK" Start a headless pi task in its own tmux session (= agent prompt)
prompt NAME "TASK" Start a headless pi task as a background job (= agent prompt)

Command families (boxery FAMILY --help):
host add|ls|show|use|rm|… Named hosts, and maintenance of the selected host
Expand Down
19 changes: 19 additions & 0 deletions test/jobs.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -215,6 +215,25 @@ describe("background jobs", { skip }, () => {
await wait(await start(["--", "-x"]), 127);
});

test("prompt starts pi -p TASK as a job: job ls lists it, job wait exits with pi's status, job logs has its output", async () => {
const pi = path.join(bin, "pi");
writeFileSync(pi, "#!/bin/bash\npwd | tr -d '\\n'\nfor a in \"$@\"; do printf '[%s]' \"$a\"; done\nexit 7\n");
chmodSync(pi, 0o755);
try {
const task = "fix the tests; echo $HOME";
const r = await cli(["prompt", "fakevm", task]);
assert.equal(r.code, 0, r.stderr);
const id = /^started (\S+) on fakevm/.exec(r.stdout)?.[1] ?? "";
assert.match(id, ID);
assert.ok(r.stdout.includes(`boxery job wait fakevm ${id}`) && r.stdout.includes(`boxery job logs fakevm ${id} -f`), r.stdout);
await wait(id, 7); // job wait exits with pi's own status
assert.equal((await cli(["logs", "fakevm", id])).stdout, `${path.join(vmhome(), "project")}[-p][${task}]`, "pi -p TASK, the task as one word, in ~/project");
assert.ok((await jobs()).some((j) => j.id === id && j.state === "exited" && j.exit_code === 7), "job ls shows the task");
} finally {
rmSync(pi, { force: true });
}
});

test("--cwd matches run; NAME --bg also works; a missing cwd is a recorded failure", async () => {
for (const [cwd, expected] of [["dir with space", "project/dir with space"], ["~", ""], ["~/project", "project"], [vmhome(), ""]]) {
const r = await cli(["run", "fakevm", "--bg", "--cwd", cwd, "pwd"]);
Expand Down
4 changes: 2 additions & 2 deletions test/parity.test.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ const CLI_ONLY = {
desktop: "opens noVNC in the user's browser (agents use the computer-use tools)",
forward: "binds a port on the user's machine",
prompt: "starts a pi task in the VM; agents run commands with vm_jobs",
sessions: "lists the tmux sessions behind attach/prompt",
sessions: "lists the VM's tmux sessions: attach's, and one per background job (prompt and run --bg)",
"proxy-log": "host-wide LLM/edge request log, for the user",
pool: "host admin",
runners: "host admin: GitHub Actions runners on the pool, with a GitHub token that stays on the host",
Expand Down Expand Up @@ -136,7 +136,7 @@ const NO_STATUS = {
rm: QUICK, pin: QUICK, shapes: QUICK, ls: QUICK, snaps: QUICK, "snap-rm": QUICK, images: QUICK, sessions: QUICK, jobs: QUICK, kill: QUICK,
grant: QUICK, revoke: QUICK, grants: QUICK, "agent-forward": QUICK, renew: QUICK, release: QUICK, leases: QUICK, version: QUICK,
backends: QUICK, capabilities: QUICK, backend: QUICK, "proxy-log": QUICK,
prompt: "starts a detached task and returns; the task isn't this process",
prompt: "starts a background job and returns; the job isn't this process",
ssh: INTERACTIVE, attach: INTERACTIVE, forward: INTERACTIVE, desktop: INTERACTIVE,
host: FAMILY, snapshot: FAMILY, agent: FAMILY, job: FAMILY, access: FAMILY, lease: FAMILY,
setup: BEFORE_HOST, help: BEFORE_HOST,
Expand Down
22 changes: 17 additions & 5 deletions test/shell/common/controller-local.sh
Original file line number Diff line number Diff line change
Expand Up @@ -137,11 +137,23 @@ echo "welcome to the VM" >"$tmp/vms/w1/login-output"
if out=$("$A" prompt w1 say hi 2>&1) || [[ $out != *"needs llm:chatgpt"* ]]; then bad "prompt check with a chatty login: $out"; else ok "prompt's check reads pi's settings after a login script's output"; fi
rm "$tmp/vms/w1/login-output"
"$A" grant w1 llm:chatgpt >/dev/null 2>&1
out=$("$A" prompt w1 say hi 2>&1) && [[ $out == *"started task-"* ]] && ok "prompt with pi's llm grant starts the task" || bad "prompt with the grant: $out"
# The log hint works as printed: run starts in ~/project. (tmux is a stub here, so write the log ourselves.)
log=$(sed -n 's/.*log: boxery run w1 cat \(\.boxery\/task-[0-9-]*\.log\)$/\1/p' <<<"$out")
[[ -n $log ]] && echo "task log" >"$tmp/vms/w1/home/project/$log"
[[ -n $log && $("$A" run w1 cat "$log" 2>&1) == "task log" ]] && ok "prompt's log hint names the log under ~/project" || bad "prompt log hint: $out"
# With the grant, prompt starts pi -p TASK as a job (the same way as run --bg). tmux is a stub here: it only
# records the launch like a runner that has started the command (the job's .pid), without running anything.
cat >"$tmp/bin/tmux" <<'STUB'
#!/bin/sh
if [ "$1" = new-session ]; then
for last; do :; done
set -- $last
jd=$(printf %s "$3" | tr -d "'"); id=$4
echo "$$ " >"$jd/$id.pid"
fi
exit 0
STUB
chmod +x "$tmp/bin/tmux"
out=$("$A" prompt w1 say hi 2>&1) && [[ $out == "started job-"*" on w1 — wait: boxery job wait w1 job-"*" logs: boxery job logs w1 job-"*" -f" ]] && ok "prompt with pi's llm grant starts the task as a job" || bad "prompt with the grant: $out"
job=$(sed -n 's/^started \(job-[0-9a-f-]*\) on w1.*/\1/p' <<<"$out")
# The job runs `pi -p say hi`, the words after the VM name as one task, in ~/project.
[[ $(tr '\0' '|' <"$tmp/vms/w1/home/.boxery/jobs/$job.argv" 2>&1) == "pi|-p|say hi|" ]] && ok "prompt's job runs pi -p with the task as one argument" || bad "prompt job argv: $(tr '\0' '|' <"$tmp/vms/w1/home/.boxery/jobs/$job.argv" 2>&1)"
"$A" revoke w1 llm:chatgpt >/dev/null 2>&1
# attach runs only its three tools, and says what to use instead when there is no terminal. With python3
# (not in every test image), the cases run on a pseudo-terminal too, as a person's attach does.
Expand Down
Loading