From 7848b9b4aee73555332654bd781ed5e32c16c693 Mon Sep 17 00:00:00 2001 From: Ben Vinegar <2153+benvinegar@users.noreply.github.com> Date: Mon, 9 Nov 2026 14:47:32 -0500 Subject: [PATCH] feat(controller): prompt starts its task as a background job (#254) --- controller/cli.mjs | 21 +++++++++------------ docs/cli.md | 8 ++++---- test/cli-families.test.mjs | 15 ++++++++++----- test/fixtures/boxery-help-all.txt | 4 ++-- test/fixtures/boxery-help.txt | 2 +- test/jobs.test.mjs | 19 +++++++++++++++++++ test/parity.test.mjs | 4 ++-- test/shell/common/controller-local.sh | 22 +++++++++++++++++----- 8 files changed, 64 insertions(+), 31 deletions(-) diff --git a/controller/cli.mjs b/controller/cli.mjs index 13200e78..a25a1820 100644 --- a/controller/cli.mjs +++ b/controller/cli.mjs @@ -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} */ +/** 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} */ 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)" &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 @@ -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" }, }, @@ -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", }, diff --git a/docs/cli.md b/docs/cli.md index 03e901aa..c4ff8017 100644 --- a/docs/cli.md +++ b/docs/cli.md @@ -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 ``` @@ -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 @@ -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)** @@ -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)** diff --git a/test/cli-families.test.mjs b/test/cli-families.test.mjs index 52e0e141..7ffcebd8 100644 --- a/test/cli-families.test.mjs +++ b/test/cli-families.test.mjs @@ -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) { @@ -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); @@ -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); } diff --git a/test/fixtures/boxery-help-all.txt b/test/fixtures/boxery-help-all.txt index 82a55688..60fd2d79 100644 --- a/test/fixtures/boxery-help-all.txt +++ b/test/fixtures/boxery-help-all.txt @@ -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 @@ -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): diff --git a/test/fixtures/boxery-help.txt b/test/fixtures/boxery-help.txt index 8ffb4f47..646179de 100644 --- a/test/fixtures/boxery-help.txt +++ b/test/fixtures/boxery-help.txt @@ -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 diff --git a/test/jobs.test.mjs b/test/jobs.test.mjs index 248e8e2c..b969f31c 100644 --- a/test/jobs.test.mjs +++ b/test/jobs.test.mjs @@ -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"]); diff --git a/test/parity.test.mjs b/test/parity.test.mjs index c91a900a..3bce5c47 100644 --- a/test/parity.test.mjs +++ b/test/parity.test.mjs @@ -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", @@ -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, diff --git a/test/shell/common/controller-local.sh b/test/shell/common/controller-local.sh index 6e78d811..5c23f907 100755 --- a/test/shell/common/controller-local.sh +++ b/test/shell/common/controller-local.sh @@ -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.