Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
17 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
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
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
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
460e509
Merge remote-tracking branch 'origin/main' into agent/333-work-task-r…
n0rpan Nov 15, 2026
a397ac9
Merge remote-tracking branch 'origin/main' into agent/333-work-task-r…
n0rpan Nov 16, 2026
ccf2550
Sandbox runner acceptance and consume the worker result contract (#333)
n0rpan Nov 16, 2026
12341d2
Use trusted host tools for runner issue lookup and child startup (#333)
n0rpan Nov 16, 2026
098a257
Exclude outer project tools across nested Git boundaries (#333)
n0rpan Nov 16, 2026
224b4fe
Keep final Git inspection inside the runner sandbox (#333)
n0rpan Nov 16, 2026
dd80623
Bootstrap task branches without host Git callbacks (#333)
n0rpan Nov 16, 2026
7d81cd5
Freeze task batches and deny worker project resources (#333)
n0rpan Nov 16, 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",
"oxc-gateway",
]
Expand Down Expand Up @@ -47,6 +47,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" }
# Shared oxa dependencies; the optional cloud transport is owned by the gateway.
serde = { version = "1", features = ["derive"] }
Expand Down
79 changes: 79 additions & 0 deletions oxa/docs/work.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,79 @@
# 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; branches must be new. 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.
Issue lookup also requires source-project trust. Git and GitHub CLI host calls use
validated executables outside the repository. Worker and check-supervisor PATHs
exclude project directories, relative entries and unsafe aliases; project tools
can still run by explicit path inside the sandbox.
Branches must be literal names; checkout-history aliases such as `@{-1}` are refused.
Every base and acceptance command list is resolved before any task in the batch
starts. All bases must therefore exist at batch startup. Host metadata commands
ignore replacement objects and inherited `GIT_*` overrides, disable filesystem
monitors, and never lazily fetch missing objects. Fetch the needed objects before
starting the batch. Checkout and checks also ignore replacement objects.

Each task runs a child `oxa --mode=json` with its model and a saved session. 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
passes `-na` on every child start, including repair, and removes `OXA_TRUST_PROJECT`.
Worker project settings, MCP servers and extensions are therefore ignored even
when a parent directory or the user's default would trust the new worktree.
User-level resources keep their normal behavior; external acceptance uses the
approved source project and the batch's frozen command list. The runner
creates detached Git metadata with callbacks suppressed on the host, then creates
the task branch and populates the fresh worktree inside the normal sandbox.
Reference hooks, checkout hooks and smudge filters stay inside it; a reference hook
that rejects the task branch still blocks the task.
missing bwrap blocks before checkout or a worker starts. Configured hook directories
keep their normal read-only protection: a checkout that needs to populate a tracked
protected hook directory blocks with the worktree retained.
Acceptance commands are frozen from the captured base commit before checkout
callbacks can change settings. The runner executes those `done` commands outside the
agent after it exits, even without edits. The source project must pass the existing
trust and executable-content approval before a task starts. Invoking `work` does
not approve an untrusted project. Acceptance runs in the normal bwrap sandbox;
missing or unusable bwrap blocks the task. Checkout and each check have the same ten-minute limit
as agent-internal done checks. `in subdirectory: command` selects a folder inside
that sandbox; escaping the worktree is rejected.
The final Git inspection is also sandboxed, with a read-only workspace, no network
and fsmonitor disabled. Clean filters stay inside that sandbox; an inspection
error blocks the task rather than producing a clean verdict.
Agent-internal done checks may also run when the project is trusted.

The runner reads the child's exit code, terminal `oxa_result` and session header,
without retaining its event stream. A blocked, failed or interrupted worker remains
blocked and does not consume a repair attempt. Failed acceptance after a successful
worker continues that same saved session once, then acceptance runs once more.
JSON lines include the worker result, session ID and captured `base_sha` and 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). Private result receipts and
locks live under `~/.oxa/agent/work/<repository-hash>/` (or the configured agent
directory), outside the worker's writable Git bind. Receipts are published atomically
without overwriting an existing receipt. Worktrees stay outside that git
directory so the normal sandbox can bind git objects and refs for commits. No automatic
cleanup, commit, push, PR creation or continuation is implemented yet. Inspect
retained work before removing it with `git worktree remove`. Review task prompts
and bases before running them.

`done` here describes accepted local work, which may be uncommitted. This slice
does not publish it. The saving/publication slices must bind acceptance to a clean
committed tree and verify its recorded commit before pushing.
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 @@ -182,6 +184,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 @@ -352,6 +358,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 @@ -463,19 +470,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
Loading
Loading