diff --git a/oxa/docs/pages/cli.md b/oxa/docs/pages/cli.md index 88582f0d..d3f0dfce 100644 --- a/oxa/docs/pages/cli.md +++ b/oxa/docs/pages/cli.md @@ -120,6 +120,8 @@ $ oxa share key list `oxa share serve` starts a foreground listener after the owner enables the native local engine and selects one or more local aliases with `--model`. It binds to the Tailscale interface by default and prints its `/v1` base URL. Set `--port` to use a fixed port, or `--bind 127.0.0.1` to put the listener behind Tailscale Serve. `--same-owner` requires the connecting peer to pass the Tailscale owner check. Clients send a guest bearer and can list models or stream text chat. Ctrl+C stops admission and joins active cleanup. +Start an interactive owner session with `oxa --share-model ALIAS` to share that session's native engine. A queued owner request goes before a waiting guest, and an active guest keeps its lease through cleanup. The startup notice gives the guest API address. Exiting the owner session drains the listener. + `oxa update --self`, `--all` and `--models` report that they are not supported: oxa does not update itself and does not refresh model catalogues. Update oxa by installing a new build. `oxa report-issue draft` takes `--title ` (required), and the notes either inline with `--notes ` or from a file with `--notes-file ` (relative paths are taken from the current directory). It writes the draft under `issue-drafts/` in the agent directory and prints its path; it posts nothing. `oxa report-issue submit ` posts it after you type `yes`. @@ -236,6 +238,8 @@ See [tools.md](tools.md) for the tool names. | `--yolo` | permission mode yolo, full access: no prompts, bash runs without the sandbox, no deny-list or protected paths for file tools ([security.md](security.md#standard-auto-and-yolo)) | | `--approve`, `-a` | trust the project's configuration and resources for this run | | `--no-approve`, `-na` | ignore the project's configuration and resources for this run | +| `--share-model ` | share one native local model during the interactive owner session in a build with the `share` feature, repeat to select more aliases | +| `--share-bind
` | set an explicit bind address for `--share-model`. Sharing uses the Tailscale interface by default | | `--offline` | offline mode: oxa's own non-local connections are refused, bash has no network, `web_search` is off, and `!cmd` and stdio MCP servers run without network. What it does not cover is in [security.md](security.md#offline-mode) | See [security.md](security.md). diff --git a/oxa/oxa-cli/src/args.rs b/oxa/oxa-cli/src/args.rs index 6bc5e9e6..ab4aac30 100644 --- a/oxa/oxa-cli/src/args.rs +++ b/oxa/oxa-cli/src/args.rs @@ -216,6 +216,12 @@ pub struct Args { pub version: bool, /// The hard offline switch (see the help text). pub offline: bool, + /// Explicitly expose only these native local aliases for the current owner session. + #[cfg(feature = "share")] + pub share_models: Vec, + /// Override the Tailscale bind for this owner session. + #[cfg(feature = "share")] + pub share_bind: Option, /// Flags registered by extensions (`registerFlag`): name -> value. pub extension_flags: Vec<(String, Value)>, /// Unknown `--long` flags seen before the extension flags are known (resolved by the @@ -454,6 +460,10 @@ const OPTIONS: &[(&str, &str)] = &[ "Permission mode: standard, auto, yolo, plan (or workspace, ask); default: permissions.defaultMode, else auto", ), ("--verbose", "Show verbose startup information"), + #[cfg(feature = "share")] + ("--share-model ", "Share one native local model during the interactive owner session (repeatable)"), + #[cfg(feature = "share")] + ("--share-bind
", "Explicitly bind interactive guest sharing to this address"), ( "--offline", "Hard offline switch: non-local connections refused, bash has no network, web_search off", @@ -920,6 +930,25 @@ fn parse_flag( no_value(inline, flag)?; a.approve = Some(false); } + #[cfg(feature = "share")] + "--share-model" => { + let alias = value(argv, i, inline, flag, "a native local alias")?; + if alias.is_empty() || a.share_models.len() >= 64 || a.share_models.contains(&alias) { + return Err(usage( + "specify between one and 64 distinct native local sharing aliases", + )); + } + a.share_models.push(alias); + } + #[cfg(feature = "share")] + "--share-bind" => { + let address = value(argv, i, inline, flag, "an IP address")?; + a.share_bind = Some( + address + .parse() + .map_err(|_| usage("invalid --share-bind address"))?, + ); + } "--offline" => { no_value(inline, flag)?; a.offline = true; diff --git a/oxa/oxa-cli/src/dispatch.rs b/oxa/oxa-cli/src/dispatch.rs index bd7dab58..41d5909c 100644 --- a/oxa/oxa-cli/src/dispatch.rs +++ b/oxa/oxa-cli/src/dispatch.rs @@ -156,6 +156,31 @@ pub fn run(argv: &[String], env: &Env, io: Stdio) -> i32 { crate::netguard::install(a.offline, env, a.session_dir.as_deref(), &cwd); + #[cfg(feature = "share")] + if !a.share_models.is_empty() || a.share_bind.is_some() { + let refusal = if crate::share_cmd::is_agent(env) { + Some(OxaError::new( + codes::INVALID, + "Guest serving requires the owner outside an agent tool", + )) + } else if a.share_models.is_empty() { + Some(OxaError::new( + codes::USAGE, + "--share-bind requires --share-model ALIAS", + )) + } else if !loads_extensions || choose_mode(&a, stdin_is_tty, stdout_is_tty) != RunMode::Interactive { + Some(OxaError::new( + codes::USAGE, + "--share-model requires an interactive owner session", + )) + } else { + oxa_proto::check_online("starting the LAN sharing listener").err() + }; + if let Some(error) = refusal { + return report(&mut *stderr, &error); + } + } + if let Some(sub) = a.subcommand.clone() { let dirs = match dirs_from_env(env, None) { Ok(d) => d, @@ -185,14 +210,7 @@ pub fn run(argv: &[String], env: &Env, io: Stdio) -> i32 { #[cfg(feature = "share")] Subcommand::Share(words) => { let serve = words.first().is_some_and(|word| word == "serve"); - // Env::get treats empty values as unset; owner-command policy - // refuses marker presence, including an empty value. - if env.pairs().iter().any(|(name, _)| { - matches!( - name.as_str(), - "OXA_CODING_AGENT" | "AI_AGENT" | "OXA_SUBAGENT_DEPTH" - ) - }) { + if crate::share_cmd::is_agent(env) { return report( &mut *stderr, &OxaError::new( @@ -439,6 +457,8 @@ pub fn run(argv: &[String], env: &Env, io: Stdio) -> i32 { /// Everything decided before a session is opened. struct Prep { built: Built, + #[cfg(feature = "share")] + sharing: Option, open: Open, session_id: Option, notices: Vec<(Level, String)>, @@ -746,12 +766,29 @@ fn prepare( settings.string("defaultModel") } }); + #[cfg(feature = "share")] + let sharing = (!a.share_models.is_empty()) + .then(|| { + crate::share_cmd::prepare_session( + &user_settings, + &settings, + dirs, + a.share_models.clone(), + a.share_bind, + ) + }) + .transpose()?; + #[cfg(feature = "share")] + let shared_local = sharing.as_ref().map(|prepared| prepared.local.clone()); + #[cfg(not(feature = "share"))] + let shared_local = None; let engine = child.wrap(crate::in_process::select_observed( &user_settings, &settings, dirs, requested_model.as_deref(), (!child.nested() && mode != RunMode::Rpc).then(|| cloud_diagnostics.clone()), + shared_local, || engine_with_settings(&endpoint, &settings), )?); @@ -975,6 +1012,8 @@ fn prepare( }; Ok(Prep { built, + #[cfg(feature = "share")] + sharing, open, session_id, notices, @@ -1495,6 +1534,8 @@ fn run_tui(a: &Args, env: &Env, dirs: &Dirs, cwd: &Path, prep: Prep, stderr: &mu let Prep { built, + #[cfg(feature = "share")] + sharing, open, session_id, mut notices, @@ -1506,6 +1547,18 @@ fn run_tui(a: &Args, env: &Env, dirs: &Dirs, cwd: &Path, prep: Prep, stderr: &mu Ok(s) => s, Err(e) => return report(stderr, &e), }; + #[cfg(feature = "share")] + let _guest_listener = match sharing.map(crate::share_cmd::Prepared::start).transpose() { + Ok(Some((running, address))) => { + notices.push(( + Level::Info, + format!("Guest OpenAI API listening at http://{address}/v1"), + )); + Some(running) + } + Ok(None) => None, + Err(error) => return report(stderr, &error), + }; notices.extend(startup_notices(&built, &session)); let yolo = built.yolo.clone(); // Its diagnostics are among the startup notices (`prepare`). diff --git a/oxa/oxa-cli/src/in_process.rs b/oxa/oxa-cli/src/in_process.rs index 84445c58..e8ae0746 100644 --- a/oxa/oxa-cli/src/in_process.rs +++ b/oxa/oxa-cli/src/in_process.rs @@ -93,7 +93,29 @@ pub(crate) fn select( requested: Option<&str>, http: impl FnOnce() -> Result, OxaError>, ) -> Result, OxaError> { - select_observed(user, effective, dirs, requested, None, http) + select_observed(user, effective, dirs, requested, None, None, http) +} + +/// Native launch configuration is user-only. Stream policy follows the effective session. +pub(crate) fn local_engine_settings<'a>( + user: &'a Settings, + effective: &Settings, +) -> (Option<&'a Value>, oxa_engine::StreamOpts) { + let stream = oxa_engine::StreamOpts { + silence_limit_ms: crate::dispatch::stream_silence_timeout(effective) + .unwrap_or(365 * 24 * 3600 * 1000), + ..oxa_engine::StreamOpts::default() + }; + (user.get("oxa.local"), stream) +} + +#[test] +fn shared_local_engine_uses_effective_stream_timeout() { + let user_values = serde_json::json!({"httpIdleTimeoutMs": 1700}); + let user = Settings::from_values(user_values.clone(), serde_json::json!({})); + let effective = Settings::from_values(user_values, serde_json::json!({"httpIdleTimeoutMs": 2400})); + let (_, stream) = local_engine_settings(&user, &effective); + assert_eq!(stream.silence_limit_ms, 2400); } pub(crate) fn select_observed( @@ -102,8 +124,16 @@ pub(crate) fn select_observed( dirs: &Dirs, requested: Option<&str>, diagnostics: Option, + shared_local: Option>, http: impl FnOnce() -> Result, OxaError>, ) -> Result, OxaError> { + let local_engine = || match shared_local { + Some(engine) => Ok(engine as Arc), + None => { + let (launch, stream) = local_engine_settings(user, effective); + oxc_local::configured_engine(launch, dirs.agent_dir.join("local-engine"), stream) + } + }; if user.bool(oxc_local::LOCAL_SETTING, false) && user.bool(SETTING, false) { let aliases = |path| { user.get(path) @@ -112,15 +142,7 @@ pub(crate) fn select_observed( .unwrap_or_default() }; return routing::Routed { - local: oxc_local::configured_engine( - user.get("oxa.local"), - dirs.agent_dir.join("local-engine"), - oxa_engine::StreamOpts { - silence_limit_ms: crate::dispatch::stream_silence_timeout(effective) - .unwrap_or(365 * 24 * 3600 * 1000), - ..oxa_engine::StreamOpts::default() - }, - ), + local: local_engine(), cloud: if oxa_proto::offline() { Err(oxa_proto::offline_error("the in-process cloud gateway")) } else { @@ -134,15 +156,7 @@ pub(crate) fn select_observed( .into_engine(requested); } if user.bool(oxc_local::LOCAL_SETTING, false) { - return oxc_local::configured_engine( - user.get("oxa.local"), - dirs.agent_dir.join("local-engine"), - oxa_engine::StreamOpts { - silence_limit_ms: crate::dispatch::stream_silence_timeout(effective) - .unwrap_or(365 * 24 * 3600 * 1000), - ..oxa_engine::StreamOpts::default() - }, - ); + return local_engine(); } if !user.bool(SETTING, false) { return http(); diff --git a/oxa/oxa-cli/src/share_cmd.rs b/oxa/oxa-cli/src/share_cmd.rs index a2cc4142..4a31147e 100644 --- a/oxa/oxa-cli/src/share_cmd.rs +++ b/oxa/oxa-cli/src/share_cmd.rs @@ -1,5 +1,5 @@ //! Foreground opt-in native LAN listener. Only user settings can select its engine. -use oxa_config::{Dirs, Settings}; +use oxa_config::{Dirs, Env, Settings}; use oxa_proto::{codes, CancelToken, ChatRequest, Engine, OxaError, StreamEvent}; use oxc_gateway::share::{ keys::Store, @@ -9,15 +9,44 @@ use oxc_gateway::share::{ }; use std::{ io::Write, + net::{IpAddr, SocketAddr}, path::{Path, PathBuf}, sync::Arc, time::Duration, }; -pub(crate) fn run(args: &[String], dirs: &Dirs, cwd: &Path, out: &mut dyn Write) -> Result<(), OxaError> { +const TAILSCALE_SOCKET: &str = "/var/run/tailscale/tailscaled.sock"; + +pub(crate) fn is_agent(env: &Env) -> bool { + // Marker presence, including an empty value, is enough to refuse. + env.pairs().iter().any(|(name, _)| { + matches!( + name.as_str(), + "OXA_CODING_AGENT" | "AI_AGENT" | "OXA_SUBAGENT_DEPTH" + ) + }) +} + +pub(crate) struct Prepared { + pub local: Arc, + keys: Arc, + models: Vec, + tailnet: Arc, + config: Config, +} + +fn prepare( + settings: &Settings, + effective: &Settings, + dirs: &Dirs, + config: Config, + aliases: Vec, + socket: PathBuf, +) -> Result { oxa_proto::check_online("starting the LAN sharing listener")?; - let (config, aliases, socket) = options(args)?; - let settings = Settings::load(dirs, cwd, false); + if aliases.is_empty() || aliases.len() > 64 { + return Err(usage()); + } if !settings.bool(oxc_local::LOCAL_SETTING, false) { return Err(OxaError::new( codes::INVALID, @@ -28,15 +57,8 @@ pub(crate) fn run(args: &[String], dirs: &Dirs, cwd: &Path, out: &mut dyn Write) Store::open(&dirs.home.join(".oxa/share")) .map_err(|error| OxaError::new(codes::INVALID, error.to_string()))?, ); - let local = oxc_local::configured_local_engine( - settings.get("oxa.local"), - dirs.agent_dir.join("local-engine"), - oxa_engine::StreamOpts { - silence_limit_ms: crate::dispatch::stream_silence_timeout(&settings) - .unwrap_or(365 * 24 * 3600 * 1000), - ..oxa_engine::StreamOpts::default() - }, - )?; + let (launch, stream) = crate::in_process::local_engine_settings(settings, effective); + let local = oxc_local::configured_local_engine(launch, dirs.agent_dir.join("local-engine"), stream)?; let catalog = local.info(None)?; let models = aliases .into_iter() @@ -62,16 +84,108 @@ pub(crate) fn run(args: &[String], dirs: &Dirs, cwd: &Path, out: &mut dyn Write) }) }) .collect::, OxaError>>()?; - let answer = native::Native::new( + let tailnet = Arc::new( + LocalApi::new(socket, Duration::from_secs(5)) + .map_err(|error| OxaError::new(codes::INVALID, error.to_string()))?, + ); + Ok(Prepared { + local, + keys, models, - move |request: &ChatRequest<'_>, cancel: &CancelToken, on: &mut dyn FnMut(StreamEvent)| { - local.chat_guest(request, cancel, on) - }, + tailnet, + config, + }) +} + +pub(crate) fn prepare_session( + settings: &Settings, + effective: &Settings, + dirs: &Dirs, + aliases: Vec, + bind: Option, +) -> Result { + let config = Config { + binding: bind.map_or(Binding::Tailnet, Binding::Explicit), + ..Config::default() + }; + prepare( + settings, + effective, + dirs, + config, + aliases, + PathBuf::from(TAILSCALE_SOCKET), ) - .map_err(service_error)?; - let tailnet = LocalApi::new(socket, Duration::from_secs(5)) - .map_err(|error| OxaError::new(codes::INVALID, error.to_string()))?; +} + +impl Prepared { + fn serve( + self, + stop: CancelToken, + ready: impl FnOnce(SocketAddr) -> Result<(), Failure>, + ) -> Result<(), OxaError> { + let Self { + local, + keys, + models, + tailnet, + config, + } = self; + let answer = native::Native::new( + models, + move |request: &ChatRequest<'_>, cancel: &CancelToken, on: &mut dyn FnMut(StreamEvent)| { + local.chat_guest(request, cancel, on) + }, + ) + .map_err(service_error)?; + native::serve(keys, Arc::new(answer), tailnet, config, stop, ready).map_err(service_error) + } + pub(super) fn start(self) -> Result<(Serving, SocketAddr), OxaError> { + let stop = CancelToken::new(); + let thread_stop = stop.clone(); + let (send, receive) = std::sync::mpsc::channel(); + let thread = std::thread::Builder::new() + .spawn(move || { + self.serve(thread_stop, |address| { + send.send(address).map_err(|_| Failure::Failed) + }) + }) + .map_err(|error| OxaError::io("cannot start the guest listener", &error))?; + match receive.recv() { + Ok(address) => Ok(( + Serving { + stop, + thread: Some(thread), + }, + address, + )), + Err(_) => match thread.join() { + Ok(Err(error)) => Err(error), + _ => Err(service_error(Failure::Failed)), + }, + } + } +} + +pub(super) struct Serving { + stop: CancelToken, + thread: Option>>, +} + +impl Drop for Serving { + fn drop(&mut self) { + self.stop.cancel(); + if let Some(thread) = self.thread.take() { + let _ = thread.join(); + } + } +} + +pub(crate) fn run(args: &[String], dirs: &Dirs, cwd: &Path, out: &mut dyn Write) -> Result<(), OxaError> { + let (config, aliases, socket) = options(args)?; + let settings = Settings::load(dirs, cwd, false); + let prepared = prepare(&settings, &settings, dirs, config, aliases, socket)?; let stop = CancelToken::new(); let mut signals = signal_hook::iterator::Signals::new([signal_hook::consts::SIGINT, signal_hook::consts::SIGTERM]) @@ -86,27 +200,20 @@ pub(crate) fn run(args: &[String], dirs: &Dirs, cwd: &Path, out: &mut dyn Write) }) .map_err(|error| OxaError::io("cannot start listener shutdown handler", &error))?; - let result = native::serve( - keys, - Arc::new(answer), - Arc::new(tailnet), - config, - stop, - |address| { - writeln!(out, "Guest OpenAI API listening at http://{address}/v1") - .and_then(|()| out.flush()) - .map_err(|_| Failure::Failed) - }, - ); + let result = prepared.serve(stop, |address| { + writeln!(out, "Guest OpenAI API listening at http://{address}/v1") + .and_then(|()| out.flush()) + .map_err(|_| Failure::Failed) + }); signal_handle.close(); let _ = signal_thread.join(); - result.map_err(service_error) + result } fn options(args: &[String]) -> Result<(Config, Vec, PathBuf), OxaError> { let mut config = Config::default(); let mut aliases = Vec::new(); - let mut socket = PathBuf::from("/var/run/tailscale/tailscaled.sock"); + let mut socket = PathBuf::from(TAILSCALE_SOCKET); let mut args = args.iter(); while let Some(arg) = args.next() { if arg == "--same-owner" { @@ -144,3 +251,53 @@ fn service_error(error: Failure) -> OxaError { }; OxaError::new(codes::INVALID, message) } + +#[cfg(test)] +mod tests { + use super::*; + use oxc_local::native::LocalEngine; + + #[test] + fn owner_router_and_listener_use_the_same_local_engine() { + let home = oxa_fake::TestEnv::new(); + let dirs = Dirs::under(home.root()); + let settings = Settings::from_values( + serde_json::json!({"oxa":{ + "engine":{"inProcessLocal":true}, + "local":{"binary":"/synthetic/oxe-server", + "models":{"synthetic":{"model":"/synthetic/model.gguf", + "arguments":["--engine","stub"]}}, + "limits":{"synthetic":{"context_window":4096,"max_output":64, + "allocation_budget":{"kv_bytes_per_position":1,"scratch_bytes":0, + "mtp_state_bytes":0,"margin_bytes":1044480}}}} + }}), + serde_json::json!({}), + ); + Store::initialize(&dirs.home.join(".oxa/share")).unwrap(); + let prepared = prepare_session( + &settings, + &settings, + &dirs, + vec!["synthetic".into()], + Some(std::net::Ipv4Addr::LOCALHOST.into()), + ) + .unwrap(); + let local: Arc = prepared.local.clone(); + let owner = crate::in_process::select_observed( + &settings, + &settings, + &dirs, + Some("synthetic"), + None, + Some(local.clone()), + || panic!("owner should use the shared native engine"), + ) + .unwrap(); + let local_api: Arc = local; + assert!(Arc::ptr_eq(&owner, &local_api)); + let (running, address) = prepared.start().unwrap(); + assert!(std::net::TcpStream::connect_timeout(&address, Duration::from_secs(2)).is_ok()); + drop(running); + assert!(std::net::TcpStream::connect_timeout(&address, Duration::from_secs(2)).is_err()); + } +} diff --git a/oxa/oxa-cli/tests/share_keys.rs b/oxa/oxa-cli/tests/share_keys.rs index 923b74c6..b310cca8 100644 --- a/oxa/oxa-cli/tests/share_keys.rs +++ b/oxa/oxa-cli/tests/share_keys.rs @@ -468,3 +468,24 @@ fn foreground_serve_lists_only_the_owner_selected_local_models_on_loopback() { assert!(!reply.contains("synthetic-hidden")); assert!(!reply.contains(bearer)); } + +#[cfg(feature = "share")] +#[test] +fn owner_session_sharing_flags_refuse_noninteractive_and_agent_invocations() { + let home = Home::new(); + let args = [ + "--share-model", + "synthetic-visible", + "--share-bind", + "127.0.0.1", + "-p", + "probe", + ]; + let headless = home.run(&args); + assert!(!headless.status.success()); + assert!(String::from_utf8_lossy(&headless.stderr).contains("requires an interactive owner session")); + let agent = home.marked(&args, "OXA_CODING_AGENT", ""); + assert!(!agent.status.success()); + assert!(String::from_utf8_lossy(&agent.stderr).contains("requires the owner outside an agent tool")); + assert!(!home.0.join(".oxa/share").exists()); +}