Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
16 commits
Select commit Hold shift + click to select a range
3936b70
Register oxa-work crate for issue #333
n0rpan Nov 15, 2026
fb25b36
Add opt-in work task runner with external acceptance checks (#333)
n0rpan Nov 15, 2026
cfd23d3
Merge remote-tracking branch 'origin/main' into agent/333-work-task-r…
n0rpan Nov 15, 2026
779e689
Merge remote-tracking branch 'origin/main' into agent/333-work-continue
n0rpan Nov 15, 2026
cdfab27
Fix sandbox commits and offline issue lookup in work runner
n0rpan Nov 15, 2026
667f3f6
Merge remote-tracking branch 'origin/main' into agent/333-work-task-r…
n0rpan Nov 15, 2026
e6e30c3
Merge branch 'agent/333-work-task-runner' into agent/333-work-continue
n0rpan Nov 15, 2026
c86fa8b
Continue work branches with ordinary base merges (#333)
n0rpan Nov 15, 2026
d053910
Include the current base when resuming an older merge
n0rpan Nov 15, 2026
1e39172
Preserve offline policy and continue work batches after task failures
n0rpan Nov 15, 2026
6915352
Merge remote-tracking branch 'origin/main' into agent/333-work-task-r…
n0rpan Nov 15, 2026
6c24b5f
Merge branch 'agent/333-work-task-runner' into agent/333-work-continue
n0rpan Nov 15, 2026
d7ab5cf
Keep prompt parsing stable and retain agent failure causes (#333)
n0rpan Nov 15, 2026
e8952cb
Merge remote-tracking branch 'origin/main' into agent/333-work-task-r…
n0rpan Nov 15, 2026
b7cfc06
Merge branch 'agent/333-work-task-runner' into agent/333-work-continue
n0rpan Nov 15, 2026
e898899
Merge remote-tracking branch 'origin/main' into agent/333-work-continue
n0rpan Nov 15, 2026
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
9 changes: 9 additions & 0 deletions oxa/Cargo.lock

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

3 changes: 2 additions & 1 deletion oxa/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -13,7 +13,7 @@ members = [
"oxa-core",
"oxa-tui",
"oxa-interactive", "oxa-rpc", "oxa-export",
"oxa-cli",
"oxa-cli", "oxa-work",
"oxa-fake", "oxa-parity",
]

Expand Down Expand Up @@ -46,6 +46,7 @@ oxa-interactive = { path = "oxa-interactive" }
oxa-rpc = { path = "oxa-rpc" }
oxa-export = { path = "oxa-export" }
oxa-cli = { path = "oxa-cli" }
oxa-work = { path = "oxa-work" }
oxa-fake = { path = "oxa-fake" }
# external (plan sec. 4); no async runtime anywhere
serde = { version = "1", features = ["derive"] }
Expand Down
53 changes: 53 additions & 0 deletions oxa/docs/work.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
# Unattended work

`oxa work tasks.json` opts into sequential tasks in separate git worktrees.
Run it inside the project repository. The JSON file is an array:

```json
[{"id":"docs-fix","model":"your-model","branch":"agent/docs-fix","base":"main","prompt":"Fix documentation links."}]
```

`base` defaults to `main`. IDs contain letters, digits, hyphens or underscores.
IDs and branches must be unique within one file. A new branch starts from `base`;
an existing branch is continued with a normal merge of that base before the agent
starts. No remote fetch happens automatically. For a GitHub issue use
`oxa work --issue 123 --model your-model`. This explicitly invokes your installed,
authenticated `gh` CLI to fetch the issue title and body. Issue lookup is refused
when the environment or user settings enable offline mode.

Each task runs a child `oxa -p` with its model. The installed offline policy,
including a parent `--offline` flag, is passed to every child. Normal agent permission, trust and
sandbox rules apply. Configure project trust before unattended use. The runner
executes the base version of `.oxa/settings.json`'s `done` commands outside the
agent after it exits, even without edits. These are trusted project shell commands:
invoking `work` authorizes their execution as your user. `in subdirectory: command`
runs in that worktree subdirectory; escaping it with the directory is rejected.
Agent-internal done checks may also run when the project is trusted.
On continued branches, acceptance commands are read from the captured base commit,
even when the task branch has changed its own settings.

Failed acceptance output goes to one additional child run with the original prompt,
then acceptance runs once more. JSON lines report `done`, `nothing_to_do` (no
commits or file changes), `red` (checks still fail), or `blocked` (setup or agent
execution failed). Exit codes are 0 for success, 1 if any task is red or blocked,
and 2 for invalid input or output errors. A task setup failure produces a blocked
JSON line and does not skip later tasks. If a task cannot be locked or already has
a receipt, its existing state is preserved; a pre-worktree failure has an empty
`worktree` in the result. Locks use kernel ownership, so an abandoned lock file
after process death does not permanently block a task.

Worktrees and uncommitted changes remain in `.oxa-worktrees/<repository>/<id>`
beside the repository (or the separate git directory). Result receipts live inside
the common git directory at `oxa-work/<id>.json`. Worktrees stay outside that git
directory so the normal sandbox can bind git objects and refs for commits. No automatic
cleanup, commit, push or PR creation is implemented yet.

To continue a task, run the same file again. The retained receipt must match its
ID, branch and worktree. A clean worktree is reused; a branch checked out elsewhere
is blocked. Uncommitted changes are retained and blocked until you commit them.
Merge conflicts are passed to the agent with the merge still in progress, the
conflicted file list and merge output. An unfinished merge can be continued on a
later run. The agent must finish the merge commit and keep the task branch selected;
unresolved or aborted base merges remain blocked even when checks would pass. Inspect
retained work before removing it with `git worktree remove`. Review task prompts
and bases before running them.
1 change: 1 addition & 0 deletions oxa/oxa-cli/Cargo.toml
Original file line number Diff line number Diff line change
Expand Up @@ -17,6 +17,7 @@ name = "oxa"
path = "src/main.rs"

[dependencies]
oxa-work.workspace = true
oxa-proto.workspace = true
oxa-engine.workspace = true
oxa-session.workspace = true
Expand Down
21 changes: 13 additions & 8 deletions oxa/oxa-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,8 @@ pub enum ModeArg {
/// A subcommand (first positional word).
#[derive(Debug, Clone, PartialEq, Eq)]
pub enum Subcommand {
/// `oxa work <taskfile> | --issue N --model MODEL`.
Work(Vec<String>),
/// `oxa mcp add|remove|list|login|logout ..`: the words after `mcp`.
Mcp(Vec<String>),
/// `oxa install|remove|update|list ..`: the verb and the words after it.
Expand Down Expand Up @@ -174,6 +176,10 @@ const COMMANDS: &[(&str, &str)] = &[
"oxa report-issue <draft|submit>",
"Draft a scrubbed ox-llm issue; submit posts it only after you type yes",
),
(
"oxa work <taskfile> | --issue N --model MODEL",
"Run tasks in isolated worktrees with external acceptance checks",
),
(
"oxa wipe --session <id> | --all [--yes] [--engine]",
"Delete one session (or every session) and its spill files; --engine also drops the engine's state",
Expand Down Expand Up @@ -340,6 +346,7 @@ fn subcommand(word: &str, rest: &[String]) -> Result<Option<Subcommand>, OxaErro
"identity" => Subcommand::Identity(rest.to_vec()),
"report-issue" => Subcommand::ReportIssue(rest.to_vec()),
"wipe" => Subcommand::Wipe(rest.to_vec()),
"work" => Subcommand::Work(rest.to_vec()),
"auth" => return Err(OxaError::unsupported("the auth command")),
// pi's provider sign-in (`pi login [--api-key] [--no-browser]`, `pi logout`).
"login" | "logout" => {
Expand Down Expand Up @@ -451,19 +458,17 @@ fn positional(a: &mut Args, word: &str) {
/// `unsupported_in_oxa`.
pub fn parse_args(argv: &[String], ext_flags: &[FlagSpec]) -> Result<Args, OxaError> {
let mut a = Args::default();
if let Some(first) = argv.first() {
if !first.starts_with('-') && !first.starts_with('@') {
if let Some(sub) = subcommand(first, &argv[1..])? {
a.subcommand = Some(sub);
return Ok(a);
}
}
}
let mut i = 0;
let mut stop = false;
while i < argv.len() {
let arg = argv[i].as_str();
i += 1;
if !stop && (i == 1 || (arg == "work" && argv[..i - 1].iter().all(|word| word == "--offline"))) {
if let Some(sub) = subcommand(arg, &argv[i..])? {
a.subcommand = Some(sub);
break;
}
}
if stop || !arg.starts_with('-') {
positional(&mut a, arg);
continue;
Expand Down
1 change: 1 addition & 0 deletions oxa/oxa-cli/src/dispatch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -125,6 +125,7 @@ pub fn run(argv: &[String], env: &Env, io: Stdio) -> i32 {
Err(e) => return report(&mut *stderr, &e),
};
let result = match sub {
Subcommand::Work(words) => return crate::work_cmd::run(&words, &cwd, &mut *stdout, &mut *stderr),
Subcommand::Mcp(words) => run_mcp(&words, &dirs, &cwd, &mut *stdout, &mut *stderr),
Subcommand::Pkg(verb, words) => run_pkg(&verb, &words, &dirs, &cwd, &mut *stdout, &mut *stderr),
Subcommand::Config(words) => run_config(&words, &dirs, &cwd, &mut *stdout),
Expand Down
1 change: 1 addition & 0 deletions oxa/oxa-cli/src/lib.rs
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ mod report_cmd;
mod sandbox_layout;
mod themes;
mod wipe_cmd;
mod work_cmd;

pub use args::{parse_args, usage_text, ApiKey, Args, ModeArg, Subcommand};
pub use config_cmd::run_config;
Expand Down
43 changes: 43 additions & 0 deletions oxa/oxa-cli/src/work_cmd.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,43 @@
use std::io::Write;
use std::path::{Path, PathBuf};

pub(crate) fn run(args: &[String], cwd: &Path, out: &mut dyn Write, err: &mut dyn Write) -> i32 {
let result = (|| -> Result<i32, String> {
let tasks = match args {
[file] if !file.starts_with('-') => oxa_work::read_tasks(&cwd.join(file))?,
[flag, number, model_flag, model] if flag == "--issue" && model_flag == "--model" => {
if oxa_proto::offline() {
return Err("GitHub issue lookup is unavailable in offline mode".into());
}
vec![oxa_work::issue_task(
cwd,
number.parse().map_err(|_| "invalid issue number")?,
model.clone(),
)?]
}
_ => return Err("usage: oxa work <taskfile> | --issue N --model MODEL".into()),
};
let binary: PathBuf = std::env::current_exe().map_err(|e| e.to_string())?;
let mut code = 0;
for task in tasks {
let record = oxa_work::run_task_with_policy(cwd, &binary, &task, oxa_proto::offline())
.unwrap_or_else(|detail| oxa_work::blocked_record(&task, detail));
if matches!(
record.outcome,
oxa_work::Outcome::Red | oxa_work::Outcome::Blocked
) {
code = 1;
}
serde_json::to_writer(&mut *out, &record).map_err(|e| e.to_string())?;
writeln!(out).map_err(|e| e.to_string())?;
}
Ok(code)
})();
match result {
Ok(code) => code,
Err(e) => {
let _ = writeln!(err, "oxa work: {e}");
2
}
}
}
47 changes: 47 additions & 0 deletions oxa/oxa-cli/tests/c12_argument_parsing.rs
Original file line number Diff line number Diff line change
Expand Up @@ -389,6 +389,53 @@ fn subcommands_split() {
assert_eq!(a.messages, ["summarise", "install"]);
}

#[test]
fn agent_options_keep_command_words_as_prompts() {
for word in [
"mcp",
"install",
"remove",
"update",
"list",
"config",
"identity",
"report-issue",
"wipe",
"work",
"auth",
"login",
"logout",
] {
for flags in [&["--model", "m"][..], &["-c"][..]] {
let mut words = flags.to_vec();
words.extend([word, "example"]);
let a = parse(&words);
assert_eq!(a.subcommand, None, "{words:?}");
assert_eq!(a.messages, [word, "example"]);
}
if word != "work" {
let a = parse(&["--offline", word, "example"]);
assert_eq!(a.subcommand, None, "{word}");
assert_eq!(a.messages, [word, "example"]);
}
}
}

#[test]
fn only_the_offline_work_prefix_dispatches_after_options() {
let a = parse(&["--offline", "work", "tasks.json"]);
assert!(a.offline);
assert_eq!(a.subcommand, Some(Subcommand::Work(argv(&["tasks.json"]))));
for flags in [&["-p"][..], &["--model", "m"][..], &["--"][..]] {
let mut words = vec!["--offline"];
words.extend(flags);
words.extend(["work", "tasks.json"]);
let a = parse(&words);
assert_eq!(a.subcommand, None, "{words:?}");
assert_eq!(a.messages, ["work", "tasks.json"]);
}
}

/// Extra: help lists the flags and the extension flags.
#[test]
fn usage_text_lists_flags_and_extension_flags() {
Expand Down
79 changes: 79 additions & 0 deletions oxa/oxa-cli/tests/common/work.rs
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
use oxa_fake::{FakeOpts, FakeServer, ScriptTurn, TestEnv};
use std::{path::Path, process::Command};
pub fn git(env: &TestEnv, dir: &Path, args: &[&str]) -> String {
let out = Command::new("git")
.args(args)
.current_dir(dir)
.env_clear()
.envs(env.envs("http://127.0.0.1:1"))
.env("GIT_AUTHOR_NAME", "Test")
.env("GIT_AUTHOR_EMAIL", "test@example.invalid")
.env("GIT_COMMITTER_NAME", "Test")
.env("GIT_COMMITTER_EMAIL", "test@example.invalid")
.output()
.unwrap();
assert!(out.status.success(), "{}", String::from_utf8_lossy(&out.stderr));
String::from_utf8_lossy(&out.stdout).trim().into()
}
pub fn setup(env: &TestEnv, done: &str) {
git(env, &env.work(), &["init", "--bare", "remote.git"]);
git(env, &env.work(), &["init", "-b", "main", "project"]);
let project = env.work().join("project");
git(env, &project, &["config", "user.name", "Test"]);
git(env, &project, &["config", "user.email", "test@example.invalid"]);
env.write(
"work/project/.oxa/settings.json",
&format!(r#"{{"done":{done}}}"#),
);
git(env, &project, &["add", "."]);
git(env, &project, &["commit", "-m", "fixture"]);
git(env, &project, &["remote", "add", "origin", "../remote.git"]);
git(env, &project, &["push", "origin", "main"]);
env.write(
"work/tasks.json",
r#"[{"id":"test","branch":"agent/test","model":"fake","prompt":"Finish task"}]"#,
);
}
pub fn run(env: &TestEnv, turns: Vec<ScriptTurn>) -> serde_json::Value {
run_args(env, turns, &["work", "../tasks.json"], None)
}
pub fn run_args(
env: &TestEnv,
turns: Vec<ScriptTurn>,
args: &[&str],
path: Option<String>,
) -> serde_json::Value {
run_observed(env, turns, args, path).0
}
pub fn run_observed(
env: &TestEnv,
turns: Vec<ScriptTurn>,
args: &[&str],
path: Option<String>,
) -> (serde_json::Value, Vec<oxa_fake::Recorded>) {
let server = FakeServer::start(turns, FakeOpts::default()).unwrap();
let mut command = Command::new(env!("CARGO_BIN_EXE_oxa"));
command
.args(args)
.current_dir(env.work().join("project"))
.env_clear()
.envs(env.envs(&server.url()));
if let Some(path) = path {
command.env("PATH", path);
}
let (tx, rx) = std::sync::mpsc::channel();
std::thread::spawn(move || {
tx.send(command.output().unwrap()).unwrap();
});
let out = rx
.recv_timeout(std::time::Duration::from_secs(90))
.expect("runner finished");
let record = serde_json::from_slice(&out.stdout).unwrap_or_else(|e| {
panic!(
"{e}: {} / {}",
String::from_utf8_lossy(&out.stdout),
String::from_utf8_lossy(&out.stderr)
)
});
(record, server.requests())
}
Loading