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
28 changes: 25 additions & 3 deletions oxa/docs/lead.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,9 +4,31 @@ The lead is an ordinary oxa session with an embedded, lead-only `lead` skill.
Its instructions are exported as `oxa_resources::LEAD_SKILL` for the preset;
ordinary sessions neither discover nor install this skill. It does not enable
runner access by itself.
`oxa lead`, its restricted session preset, the `work` tool and the commands below
are pending integration with the runner. Do not use this document as a list of
commands supported by the current binary.
Shadow is disabled by default. Enable `"oxa.lead.shadow": true` in the user's
`settings.json`; project settings cannot enable it. Then `oxa lead --shadow`
opens an ordinary TUI or print session restricted to
`read`, `grep`, `find` and `ls`. It embeds the lead instructions in every prefix
epoch and enforces the proposal schema. For example:

```console
$ oxa lead --shadow -p "Read the bounded exports in ./state and propose the next action."
```

It emits proposals only. `oxa lead` without `--shadow` refuses explicitly until
live runner coordination is available. The `work` tool, live `/status`, `/asks`,
`/hold`, `/decide` and event wake-up remain pending. Shadow mode neither executes
proposals nor establishes that a supplied export is current.

The preset removes mutating tools from the registry, bypasses external hook,
extension, MCP, subagent and codemode construction, and refuses typed shell
escapes. It accepts model/session/TUI flags, but owns its schema and resource
selection; explicit extension/skill/template/schema overrides and mutating tool
requests are rejected. The same restrictions apply on continuation and reopen.
Reload retains the preset's resources, and resuming an ordinary session rebuilds
its prefix with the lead instructions and restricted declarations. Goal mode is
not supported: `--goal` and saved sessions containing a goal refuse explicitly.
Project executable resources are not trusted by this preset. Read tools still
use ordinary path permissions; no sandbox or secret policy is relaxed.

The preset must work with both the TUI and print driver, using the same session
store, engine selection, turn loop and result contract as ordinary oxa. It adds
Expand Down
1 change: 1 addition & 0 deletions oxa/docs/pages/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -175,6 +175,7 @@ $ oxa mcp logout <name>
| `--list-models [search]` | list the models the engine serves, optionally filtered by a fuzzy search, and exit |
| `--thinking <level>` | `off`, `minimal`, `low`, `medium`, `high`, `xhigh` or `max` |
| `--mode <mode>` | output mode: `text` (default), `json` or `rpc` ([rpc.md](rpc.md)) |
| `--shadow` | required with `oxa lead`; read-only proposal preset, enabled only by user setting `oxa.lead.shadow` (default false) |
| `--output-schema <file>` | check the final answer against a JSON schema file (a supported subset), retrying once on mismatch |
| `--print`, `-p` | non-interactive: process the prompts and exit |
| `--goal <file>` | pursue a stored UTF-8 objective in print/JSON mode; continue the saved pursuing goal after restart |
Expand Down
3 changes: 2 additions & 1 deletion oxa/docs/pages/settings.md
Original file line number Diff line number Diff line change
Expand Up @@ -27,7 +27,7 @@ Settings that older files may contain but oxa does not implement are not listed

Where the user file alone counts, the table says so:

- user settings only: `defaultProjectTrust`, `httpProxy`, `oxa.allowHomeCwd`, `oxa.offline`, `oxa.engine.allowRemote`, `oxa.engine.inProcessCloud`, `oxa.cloud`, `oxa.engine.inProcessLocal`, `oxa.local`, `oxa.lead.serve`, and every `oxa.sandbox.*` key. A project file cannot set them, because a project file cannot widen what the model can reach.
- user settings only: `defaultProjectTrust`, `httpProxy`, `oxa.allowHomeCwd`, `oxa.offline`, `oxa.engine.allowRemote`, `oxa.engine.inProcessCloud`, `oxa.cloud`, `oxa.engine.inProcessLocal`, `oxa.local`, `oxa.lead.shadow`, `oxa.lead.serve`, and every `oxa.sandbox.*` key. A project file cannot set them, because a project file cannot widen what the model can reach.
- project settings are trust-gated. In an untrusted project they are not read. Project files that run or load code (`hooks`, `shellPath`, `shellCommandPrefix`, `packages`, `extensions`, `skills`, `prompts`) also need the content approval described in [security.md](security.md#project-trust).

Interactive selectors (`/settings`, `/thinking` and `/model` with Ctrl+S) write the user file.
Expand Down Expand Up @@ -170,6 +170,7 @@ The compaction rules are in [compaction.md](compaction.md).
| `oxa.engine.allowRemote` | bool | `false` | allow an engine on another host; user settings only |
| `oxa.engine.inProcessLocal` | bool | `false` | select the in-process owned local engine, including offline; user settings only |
| `oxa.local` | object | `{}` | literal native binary/model/arguments/environment and model limits; user settings only; see [native local configuration](../../oxc-local/CONFIGURATION.md) |
| `oxa.lead.shadow` | bool | `false` | enable the read-only `oxa lead --shadow` proposal preset; user settings only; no live runner actions |
| `oxa.engine.inProcessCloud` | bool | `false` | select the in-process Rust cloud gateway for sessions and model discovery; user settings only |
| `oxa.cloud` | object | `{}` | native cloud models, prices, USD budget and subscription caps; user settings only; see below |
| `oxa.lead.serve` | object | `{}` | the lead web access scaffold: `enabled`, `identity` (`local` or `tailscale`), `bind` (a loopback address), `port`, `allowed_identities`. Off by default and no listener is installed yet; user settings only. See [lead-web.md](lead-web.md) |
Expand Down
15 changes: 14 additions & 1 deletion oxa/oxa-cli/src/args.rs
Original file line number Diff line number Diff line change
Expand Up @@ -61,6 +61,9 @@ impl std::fmt::Debug for ApiKey {
/// Every flag of cli.md that oxa keeps. Field comments give the spellings.
#[derive(Debug, Clone, PartialEq, Default)]
pub struct Args {
/// Explicit lead shadow preset; ordinary sessions retain their existing tools.
pub lead: bool,
pub shadow: bool,
pub subcommand: Option<Subcommand>,
/// Positional prompt words (each is one prompt in print/json mode, as pi).
pub messages: Vec<String>,
Expand Down Expand Up @@ -322,6 +325,7 @@ const OPTIONS: &[(&str, &str)] = &[
"Disable built-in tools by default, keep extension and custom tools",
),
("--no-tools, -nt", "Disable all tools by default"),
("--shadow", "Lead preset only: return proposals without executing actions"),
(
"--no-mcp",
"Disable MCP support: no servers connect and no MCP tools",
Expand Down Expand Up @@ -541,6 +545,10 @@ pub fn parse_args(argv: &[String], ext_flags: &[FlagSpec]) -> Result<Args, OxaEr
while i < argv.len() {
let arg = argv[i].as_str();
i += 1;
if !stop && i == 1 && arg == "lead" {
a.lead = true;
continue;
}
// Inbox delivery, like work, accepts leading offline switches. Once a prompt,
// another option or `--` appears, later words retain their positional meaning.
if !stop
Expand Down Expand Up @@ -570,6 +578,7 @@ pub fn parse_args(argv: &[String], ext_flags: &[FlagSpec]) -> Result<Args, OxaEr
parse_flag(&mut a, argv, &mut i, flag, inline, ext_flags)?;
}
if !a.help && !a.version {
crate::lead_preset::apply(&mut a)?;
check_conflicts(&a)?;
}
Ok(a)
Expand All @@ -584,6 +593,10 @@ fn parse_flag(
ext: &[FlagSpec],
) -> Result<(), OxaError> {
match flag {
"--shadow" => {
no_value(inline, flag)?;
a.shadow = true;
}
"-h" | "--help" => {
no_value(inline, flag)?;
a.help = true;
Expand Down Expand Up @@ -926,7 +939,7 @@ fn present_flags<'a>(flags: &[(bool, &'a str)]) -> Vec<&'a str> {
pub fn usage_text(ext_flags: &[FlagSpec]) -> String {
let mut out = String::new();
out.push_str("oxa - coding agent with read, bash, edit and write tools\n\n");
out.push_str("Usage:\n oxa [options] [--] [@files...] [messages...]\n\n");
out.push_str("Usage:\n oxa [options] [--] [@files...] [messages...]\n oxa lead --shadow [options] [messages...]\n\n");
out.push_str("Commands:\n");
for (left, desc) in COMMANDS {
out.push_str(&format!(" {left:<36}{desc}\n"));
Expand Down
46 changes: 34 additions & 12 deletions oxa/oxa-cli/src/dispatch.rs
Original file line number Diff line number Diff line change
Expand Up @@ -465,6 +465,7 @@ fn open_named(
/// `reopen` closure, which builds sessions for `/new`, `/resume`, fork and import.
#[derive(Clone)]
struct Built {
lead: bool,
status: Option<Arc<crate::status::StatusWriter>>,
result_facts: Arc<crate::result_facts::ResultFacts>,
output_schema: Option<oxa_core::output_schema::OutputSchema>,
Expand Down Expand Up @@ -530,6 +531,9 @@ impl Built {
.with_owner_present(self.ask_owner_present),
));
}
if self.lead {
tools.retain(|tool| crate::lead_preset::READ_TOOLS.contains(&tool.spec().name.as_str()));
}
Deps {
engine: self.engine.clone(),
store: self.store.clone(),
Expand Down Expand Up @@ -590,20 +594,33 @@ fn prepare(
));
}
let goal = crate::goal_cmd::load(a, cwd)?;
let output_schema = a
.output_schema
.as_ref()
.map(|file| {
let path = cwd.join(file);
let text = std::fs::read_to_string(&path)
.map_err(|e| OxaError::io(&format!("read output schema {}", path.display()), &e))?;
let value = serde_json::from_str(&text)
.map_err(|e| OxaError::new(codes::USAGE, format!("Invalid output schema JSON: {e}")))?;
oxa_core::output_schema::OutputSchema::new(value)
})
.transpose()?;
let output_schema = if a.lead {
Some(crate::lead_preset::schema()?)
} else {
a.output_schema
.as_ref()
.map(|file| {
let path = cwd.join(file);
let text = std::fs::read_to_string(&path)
.map_err(|e| OxaError::io(&format!("read output schema {}", path.display()), &e))?;
let value = serde_json::from_str(&text)
.map_err(|e| OxaError::new(codes::USAGE, format!("Invalid output schema JSON: {e}")))?;
oxa_core::output_schema::OutputSchema::new(value)
})
.transpose()?
};
let mut notices: Vec<(Level, String)> = Vec::new();
let user_settings = Settings::load(dirs, cwd, false);
// Only user settings may enable this default-off proposal session.
if a.lead && !user_settings.bool(crate::lead_preset::SETTING, false) {
return Err(OxaError::new(
codes::USAGE,
format!(
"lead --shadow is disabled; set \"{}\": true in the user settings.json to enable it",
crate::lead_preset::SETTING
),
));
}
let (models, diags) = ModelsConfig::load(dirs, env);
notices.extend(
diags
Expand Down Expand Up @@ -903,6 +920,7 @@ fn prepare(
crate::result_facts::ResultFacts::new(status.clone()).with_billing(cloud_diagnostics.clone()),
);
let built = Built {
lead: a.lead,
status,
result_facts,
output_schema,
Expand Down Expand Up @@ -1089,6 +1107,9 @@ fn discover_opts(a: &Args, dirs: &Dirs, cwd: &Path, trusted: bool) -> Result<Dis
/// that would need the dialog stays untrusted. Problems are reported on `err` and give no
/// flags; the help is printed anyway.
fn help_extension_flags(a: &Args, env: &Env, cwd: &Path, err: &mut dyn Write) -> Vec<oxa_proto::FlagSpec> {
if a.lead {
return Vec::new();
}
let Ok(dirs) = dirs_from_env(env, a.session_dir.as_deref()) else {
return Vec::new();
};
Expand Down Expand Up @@ -2324,6 +2345,7 @@ mod session_scratch_tests {
let base: Arc<dyn Sandbox> = Arc::new(NetSandbox::new(Arc::new(bwrap), true, false));
let yolo = oxa_proto::YoloSwitch::new(oxa_proto::Autonomy::Standard);
let built = Built {
lead: false,
status: None,
result_facts: Arc::new(crate::result_facts::ResultFacts::default()),
output_schema: None,
Expand Down
6 changes: 6 additions & 0 deletions oxa/oxa-cli/src/hooks.rs
Original file line number Diff line number Diff line change
Expand Up @@ -80,6 +80,12 @@ pub struct HookInputs<'a> {
/// Build the hook sets. Problems that do not stop the start (a failed extension, a bad hook
/// entry, an `mcp.json` diagnostic) are pushed to `notices`.
pub fn build_hooks(i: &HookInputs<'_>, notices: &mut Vec<(Level, String)>) -> Result<HookSets, OxaError> {
if i.args.lead {
return Ok(HookSets {
hooks: vec![Arc::new(crate::lead_preset::LeadHooks)],
..HookSets::default()
});
}
let mut sets = HookSets::default();

// ---- extensions ----
Expand Down
20 changes: 18 additions & 2 deletions oxa/oxa-cli/src/lead_peer.rs
Original file line number Diff line number Diff line change
Expand Up @@ -122,6 +122,22 @@ pub fn owner_uid(stream: &TcpStream) -> Result<u32> {
mod tests {
use super::*;

#[cfg(target_os = "linux")]
fn sample_live_owner(stream: &TcpStream) -> Result<u32> {
// The kernel table is live. An ambiguous observation remains a refusal;
// real-socket liveness controls may obtain another sample for at most one second.
// Wrong/missing ownership and every other error still fail immediately.
let start = std::time::Instant::now();
loop {
match owner_uid(stream) {
Err("ambiguous peer ownership") if start.elapsed() < std::time::Duration::from_secs(1) => {
std::thread::sleep(std::time::Duration::from_millis(5));
}
result => return result,
}
}
}

fn pair(local: &str, peer: &str) -> (SocketAddr, SocketAddr) {
(local.parse().unwrap(), peer.parse().unwrap())
}
Expand Down Expand Up @@ -192,7 +208,7 @@ mod tests {
let listener = std::net::TcpListener::bind(bind).unwrap();
let client = TcpStream::connect(listener.local_addr().unwrap()).unwrap();
let (server, _) = listener.accept().unwrap();
assert_eq!(owner_uid(&server), Ok(uid));
assert_eq!(sample_live_owner(&server), Ok(uid));
drop(client);
}
}
Expand All @@ -211,7 +227,7 @@ mod tests {
let client = TcpStream::connect(("127.0.0.1", port)).unwrap();
let (server, peer) = listener.accept().unwrap();
assert!(peer.ip().is_ipv6(), "the kernel reports the mapped IPv4 client");
assert_eq!(owner_uid(&server), Ok(uid));
assert_eq!(sample_live_owner(&server), Ok(uid));
drop(client);
}
}
Loading
Loading