Skip to content

The fastest, cheapest, most efficient open-source agent harness. Run more than 500 agents on a $10 VPS.

feat(shell): a long command comes back at its yield point; shell_process follows it

sanil-23be4ebffbd672
diff --git a/app/src/features/conversations/tools/__fixtures__/coreToolNames.json b/app/src/features/conversations/tools/__fixtures__/coreToolNames.json
index cd2df480ce..b06872a3b9 100644
--- a/app/src/features/conversations/tools/__fixtures__/coreToolNames.json
+++ b/app/src/features/conversations/tools/__fixtures__/coreToolNames.json
@@ -139,6 +139,7 @@
"service_uninstall",
"session_state",
"shell",
+ "shell_process",
"show_ui",
"skill_registry_browse",
"skill_registry_install",
diff --git a/app/src/features/conversations/tools/toolSpecs.ts b/app/src/features/conversations/tools/toolSpecs.ts
index aa755dbd5c..10eb5cfda8 100644
--- a/app/src/features/conversations/tools/toolSpecs.ts
+++ b/app/src/features/conversations/tools/toolSpecs.ts
@@ -173,6 +173,8 @@ export const EXACT_TOOL_SPECS: Record<string, ToolSpec> = {
// ── Shell and system ────────────────────────────────────────────────────
shell: spec('runCommand', SquareTerminalIcon, 'shell', { chip: chip.command(), body: 'shell' }),
+ // Follows a `shell` command left running past its yield point.
+ shell_process: spec('wait', SquareTerminalIcon, 'shell', { chip: chip.text('process') }),
detect_tools: spec('checkInstalledTools', ScanSearchIcon, 'system'),
install_tool: spec('installTool', PackagePlusIcon, 'system', {
chip: chip.text('package', 'tool_name'),
diff --git a/crates/openhuman-core/src/agent/tinyagents/middleware/failure_policy.rs b/crates/openhuman-core/src/agent/tinyagents/middleware/failure_policy.rs
index f4348ea34f..59bf23596d 100644
--- a/crates/openhuman-core/src/agent/tinyagents/middleware/failure_policy.rs
+++ b/crates/openhuman-core/src/agent/tinyagents/middleware/failure_policy.rs
@@ -235,7 +235,9 @@ pub(super) fn classified_recovery_policy(
// attempt, steered by a reconcile-first nudge, and halts on a second.
// Remote actions (`gmail_send`, payments, …) stay at zero: a retry
// there can repeat an effect the agent cannot observe.
- Class::Timeout if tool == "shell" => ("uncertain_side_effect", 1),
+ Class::Timeout if tool == "shell" || tool == "shell_process" => {
+ ("uncertain_side_effect", 1)
+ }
Class::Timeout => ("uncertain_side_effect", 0),
// The harness's own schema-validation answer, classified from its
// prefix before any keyword in the echoed schema could read as a
diff --git a/crates/openhuman-core/src/agent_registry/agents/orchestrator/agent.toml b/crates/openhuman-core/src/agent_registry/agents/orchestrator/agent.toml
index 0d5b471aed..454617cc97 100644
--- a/crates/openhuman-core/src/agent_registry/agents/orchestrator/agent.toml
+++ b/crates/openhuman-core/src/agent_registry/agents/orchestrator/agent.toml
@@ -209,6 +209,7 @@ named = [
"apply_patch",
"file_write",
"shell",
+ "shell_process",
"git_operations",
# Versioned artifact surface (vendor/tiny-artifacts): every document the
# agent creates must land in the artifact pipeline — versioned JSON record
diff --git a/crates/openhuman-core/src/tools/impl/system/mod.rs b/crates/openhuman-core/src/tools/impl/system/mod.rs
index 83ea101862..55bfda8ecd 100644
--- a/crates/openhuman-core/src/tools/impl/system/mod.rs
+++ b/crates/openhuman-core/src/tools/impl/system/mod.rs
@@ -11,6 +11,7 @@ mod retrieve_tool_output;
mod schedule;
mod shell;
mod shell_description;
+mod shell_process;
mod shell_saas;
mod shell_support;
mod update_apply;
@@ -26,6 +27,7 @@ pub use proxy_config::ProxyConfigTool;
pub use retrieve_tool_output::{retrieve_tool_output_tool, RetrieveToolOutputTool};
pub use schedule::ScheduleTool;
pub use shell::ShellTool;
+pub use shell_process::ShellProcessTool;
pub use update_apply::UpdateApplyTool;
pub use update_check::UpdateCheckTool;
diff --git a/crates/openhuman-core/src/tools/impl/system/shell.rs b/crates/openhuman-core/src/tools/impl/system/shell.rs
index 1b55fd9c7f..b79cab80c6 100644
--- a/crates/openhuman-core/src/tools/impl/system/shell.rs
+++ b/crates/openhuman-core/src/tools/impl/system/shell.rs
@@ -194,6 +194,12 @@ impl Tool for ShellTool {
"minimum": 0,
"maximum": 3600,
"description": "Optional wall-clock timeout (seconds, up to 3600) for this command before it is killed. Use a larger value for long-running work (builds, test suites, solvers). Omitted or 0 runs without a deadline."
+ },
+ "yield_after_secs": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 3600,
+ "description": "Seconds after which a command that is still running comes back with its output so far and keeps running as a process you follow with `shell_process`. Default 120; 0 waits for the command to end."
}
},
"required": ["command"]
@@ -299,12 +305,20 @@ impl ShellTool {
// `tool_timeout::explicit_call_timeout_*`. Shell has no default deadline
// (issue #4023) — long scripts must run to completion.
let requested_timeout = args.get("timeout_secs").and_then(|v| v.as_u64());
+ let requested_yield = args.get("yield_after_secs").and_then(|v| v.as_u64());
let start = Instant::now();
let (allowed, result) = crate::sandbox::shell_progress::with_shell_progress(
context,
crate::sandbox::shell_progress::HEARTBEAT_INTERVAL,
|meter| {
- self.run_with_security_in_context(ctx, command, requested_timeout, context, meter)
+ self.run_with_security_in_context(
+ ctx,
+ command,
+ requested_timeout,
+ requested_yield,
+ context,
+ meter,
+ )
},
)
.await;
@@ -338,7 +352,7 @@ impl ShellTool {
command: &str,
requested_timeout: Option<u64>,
) -> (bool, ToolResult) {
- self.run_with_security_in_context(ctx, command, requested_timeout, None, None)
+ self.run_with_security_in_context(ctx, command, requested_timeout, None, None, None)
.await
}
@@ -347,6 +361,7 @@ impl ShellTool {
ctx: &DispatchCtx,
command: &str,
requested_timeout: Option<u64>,
+ requested_yield: Option<u64>,
context: Option<&dyn ToolRunContext>,
meter: Option<crate::sandbox::shell_progress::ShellOutputMeter>,
) -> (bool, ToolResult) {
@@ -589,25 +604,7 @@ impl ShellTool {
env.insert(key, value);
}
- // Point the child's temp dir at the agent's granted scratch dir
- // (`/tmp/openhuman`, a ReadWrite trusted root — see SecurityPolicy
- // `from_config`) so `python3 tempfile` / `mktemp` / `$TMPDIR` writes land
- // in a sandboxed, readable location instead of the world-shared /tmp.
- let scratch_dir = crate::security::openhuman_scratch_dir();
- if let (true, Some(scratch)) = (scratch_dir.is_dir(), scratch_dir.to_str()) {
- tracing::debug!(
- scratch_dir = %scratch_dir.display(),
- "[shell] overriding TMPDIR/TMP/TEMP to the openhuman scratch dir"
- );
- for name in ["TMPDIR", "TMP", "TEMP"] {
- env.insert(name.to_owned(), scratch.to_owned());
- }
- } else {
- tracing::debug!(
- scratch_dir = %scratch_dir.display(),
- "[shell] scratch dir missing — leaving TMPDIR/TMP/TEMP to the module"
- );
- }
+ super::shell_support::use_scratch_tmp(&mut env);
// No default deadline — only a caller-supplied `timeout_secs` bounds the
// run (issue #4023). TinyBox needs a finite budget, so an unbounded call
@@ -644,8 +641,9 @@ impl ShellTool {
run.python_utf8 = true;
run.hide_window = self.runtime.hide_window();
run.meter = meter;
- let result = crate::sandbox::shell_exec::run(ctx, &config, run).await;
- (true, exec_result(result, effective))
+ let result =
+ super::shell_support::run_native(ctx, &config, run, requested_yield, context).await;
+ (true, result)
}
/// Execute a command through the sandbox backend. Called when the
diff --git a/crates/openhuman-core/src/tools/impl/system/shell_description.rs b/crates/openhuman-core/src/tools/impl/system/shell_description.rs
index b9ca9a54b0..b5299345cf 100644
--- a/crates/openhuman-core/src/tools/impl/system/shell_description.rs
+++ b/crates/openhuman-core/src/tools/impl/system/shell_description.rs
@@ -21,10 +21,10 @@ pub(super) fn shell_description(flavor: ShellFlavor) -> &'static str {
commands chain with `&&` (`;` is not a separator). For PowerShell run \
`powershell -NoProfile -Command \"...\"`. Only stdout/stderr comes back, so a script \
that computes silently or only writes a file returns nothing — print what you need, \
- or read the file afterwards."
+ or read the file afterwards. A command still running after `yield_after_secs` (default 120) comes back with its output so far and keeps running as a process: follow it with `shell_process` (wait for more, or kill it) instead of starting it again. Don't pipe a long command through `tail`/`head` to shorten it: long output is kept and capped for you, and a pipe holds everything back until the command ends."
}
ShellFlavor::Posix => {
- "Execute a shell command: run code, manipulate workspace files, or launch applications (`open -a Music`, `xdg-open music://`). Only stdout/stderr comes back, so a script that computes silently or only writes a file returns nothing — print what you need, or read the file afterwards."
+ "Execute a shell command: run code, manipulate workspace files, or launch applications (`open -a Music`, `xdg-open music://`). Only stdout/stderr comes back, so a script that computes silently or only writes a file returns nothing — print what you need, or read the file afterwards. A command still running after `yield_after_secs` (default 120) comes back with its output so far and keeps running as a process: follow it with `shell_process` (wait for more, or kill it) instead of starting it again. Don't pipe a long command through `tail`/`head` to shorten it: long output is kept and capped for you, and a pipe holds everything back until the command ends."
}
}
}
diff --git a/crates/openhuman-core/src/tools/impl/system/shell_process.rs b/crates/openhuman-core/src/tools/impl/system/shell_process.rs
new file mode 100644
index 0000000000..b8760d8fef
--- /dev/null
+++ b/crates/openhuman-core/src/tools/impl/system/shell_process.rs
@@ -0,0 +1,214 @@
+//! `shell_process`: follow a shell command the turn left running.
+//!
+//! A `shell` call whose command is still running at its yield point returns
+//! a process id instead of waiting; this tool waits on that process for more
+//! output or its end, stops it, or reports its status
+//! (`sandbox::shell_processes`). A wait blocks on the host, so following a long
+//! command takes a few calls, not a polling loop.
+
+use std::time::Duration;
+
+use async_trait::async_trait;
+use serde_json::json;
+use tinytools::{PermissionLevel, Tool, ToolCallOptions, ToolResult, ToolRunContext, ToolTimeout};
+
+use super::shell_support::{command_failure, human_duration, printed, tool_timeout_message};
+use crate::sandbox::shell_processes::{Ended, Report, ReportState, QUIET_WAITS_NOTE};
+
+/// How long a wait blocks when the call does not say.
+const DEFAULT_WAIT_SECS: u64 = 120;
+/// The longest one wait may block.
+const MAX_WAIT_SECS: u64 = 600;
+
+/// Follows a shell command left running past its yield point.
+#[derive(Default)]
+pub struct ShellProcessTool;
+
+impl ShellProcessTool {
+ pub fn new() -> Self {
+ Self
+ }
+}
+
+#[async_trait]
+impl Tool for ShellProcessTool {
+ fn name(&self) -> &str {
+ "shell_process"
+ }
+
+ fn description(&self) -> &str {
+ "Follow a shell command that is still running: `shell` returns a process id (`p1`) \
+ instead of waiting when a command outlives its yield point. `wait` (the default) blocks \
+ until the process writes and ends or `wait_secs` pass, and returns only the output \
+ written since the last call, then its exit code or that it is still running. `kill` \
+ stops it and returns the rest of its output. `status` says whether it is still running. \
+ Processes stop at their own timeout and when the turn ends."
+ }
+
+ fn parameters_schema(&self) -> serde_json::Value {
+ json!({
+ "type": "object",
+ "properties": {
+ "process": {
+ "type": "string",
+ "description": "The id `shell` returned, such as `p1`."
+ },
+ "action": {
+ "type": "string",
+ "enum": ["wait", "kill", "status"],
+ "description": "`wait` (default) for more output or the end, `kill` to stop it, `status` to check it."
+ },
+ "wait_secs": {
+ "type": "integer",
+ "minimum": 1,
+ "maximum": MAX_WAIT_SECS,
+ "description": "For `wait`: the longest to block, default 120."
+ }
+ },
+ "required": ["process"]
+ })
+ }
+
+ fn max_result_size_chars(&self) -> Option<usize> {
+ Some(30_000)
+ }
+
+ /// A wait blocks for its own `wait_secs`; the harness's per-call timeout
+ /// must not cut it short.
+ fn timeout_policy(&self, _args: &serde_json::Value) -> ToolTimeout {
+ ToolTimeout::Unbounded
+ }
+
+ /// Reading or stopping a command the turn already started (and that was
+ /// already approved) has no effect of its own.
+ fn permission_level(&self) -> PermissionLevel {
+ PermissionLevel::ReadOnly
+ }
+
+ async fn execute(&self, args: serde_json::Value) -> anyhow::Result<ToolResult> {
+ self.execute_with_context(args, ToolCallOptions::default(), None)
+ .await
+ }
+
+ async fn execute_with_context(
+ &self,
+ args: serde_json::Value,
+ _options: ToolCallOptions,
+ context: Option<&dyn ToolRunContext>,
+ ) -> anyhow::Result<ToolResult> {
+ let Some(id) = args.get("process").and_then(|v| v.as_str()) else {
+ return Ok(ToolResult::error(
+ "Missing 'process': the id `shell` returned, such as `p1`.",
+ ));
+ };
+ let Some(processes) =
+ crate::agent::tinyagents::host::run_context::shell_processes_for_tool(context)
+ else {
+ return Ok(ToolResult::error(
+ "No running processes here: only a turn can leave a shell command running.",
+ ));
+ };
+ let action = args
+ .get("action")
+ .and_then(|v| v.as_str())
+ .unwrap_or("wait");
+ let report = match action {
+ "wait" => {
+ let secs = args
+ .get("wait_secs")
+ .and_then(|v| v.as_u64())
+ .unwrap_or(DEFAULT_WAIT_SECS)
+ .clamp(1, MAX_WAIT_SECS);
+ tracing::debug!(process = %id, wait_secs = secs, "[shell_process] wait");
+ processes.wait(id, Duration::from_secs(secs)).await
+ }
+ "kill" => processes.kill(id).await,
+ "status" => processes.status(id).await,
+ other => {
+ return Ok(ToolResult::error(format!(
+ "Unknown action `{other}`: use `wait`, `kill` or `status`."
+ )))
+ }
+ };
+ Ok(match report {
+ Ok(report) => render(&report, action),
+ Err(message) => ToolResult::error(message),
+ })
+ }
+}
+
+/// The tool result for one report. A process that ended on its own reads like
+/// a finished `shell` call: an exit report for a non-zero code, the timeout
+/// line when its deadline stopped it.
+pub(super) fn render(report: &Report, action: &str) -> ToolResult {
+ let id = &report.id;
+ let elapsed = human_duration(report.elapsed);
+ match &report.state {
+ ReportState::Running if action == "status" => ToolResult::success(format!(
+ "Process {id} is still running ({elapsed}; it stops at its {} timeout).",
+ human_duration(report.timeout)
+ )),
+ ReportState::Running => {
+ let mut out = format!("Process {id} is still running ({elapsed}).");
+ out.push_str(&printed(
+ &report.stdout,
+ &report.stderr,
+ "New output:",
+ "No new output.",
+ ));
+ if report.quiet_waits >= QUIET_WAITS_NOTE {
+ out.push_str(&format!(
+ "\nNothing new in the last {} waits: if it is stuck or no longer needed, \
+ stop it with {{\"process\": \"{id}\", \"action\": \"kill\"}}.",
+ report.quiet_waits
+ ));
+ }
+ ToolResult::success(out)
+ }
+ ReportState::Ended(Ended::Exited(0)) => {
+ let mut out = format!("Process {id} exited with code 0 after {elapsed}.");
+ out.push_str(&printed(
+ &report.stdout,
+ &report.stderr,
+ "Final output:",
+ "No further output.",
+ ));
+ ToolResult::success(out)
+ }
+ ReportState::Ended(Ended::Exited(code)) => {
+ command_failure(Some(*code), &report.stdout, &report.stderr)
+ }
+ ReportState::Ended(Ended::TimedOut) => {
+ let mut out = tool_timeout_message(report.timeout.as_secs());
+ out.push_str(&printed(
+ &report.stdout,
+ &report.stderr,
+ "Output before the kill:",
+ "No further output before the kill.",
+ ));
+ ToolResult::error(out)
+ }
+ ReportState::Ended(Ended::Stopped) => {
+ let mut out = format!("Process {id} stopped after {elapsed}.");
+ out.push_str(&printed(
+ &report.stdout,
+ &report.stderr,
+ "Its last output:",
+ "No further output.",
+ ));
+ ToolResult::success(out)
+ }
+ ReportState::AlreadyEnded(ended) => ToolResult::success(format!(
+ "Process {id} already {}; its output was returned earlier.",
+ match ended {
+ Ended::Exited(code) => format!("exited with code {code}"),
+ Ended::TimedOut => "stopped at its timeout".to_owned(),
+ Ended::Stopped => "stopped".to_owned(),
+ }
+ )),
+ }
+}
+
+#[cfg(test)]
+#[path = "shell_process_tests.rs"]
+mod tests;
diff --git a/crates/openhuman-core/src/tools/impl/system/shell_process_tests.rs b/crates/openhuman-core/src/tools/impl/system/shell_process_tests.rs
new file mode 100644
index 0000000000..dd4e4a0626
--- /dev/null
+++ b/crates/openhuman-core/src/tools/impl/system/shell_process_tests.rs
@@ -0,0 +1,90 @@
+//! How a `shell_process` report reads to the model.
+
+use super::*;
+
+fn report(state: ReportState, stdout: &str, quiet_waits: u32) -> Report {
+ Report {
+ id: "p2".to_owned(),
+ command: "pytest".to_owned(),
+ elapsed: Duration::from_secs(185),
+ timeout: Duration::from_secs(1800),
+ stdout: stdout.to_owned(),
+ stderr: String::new(),
+ state,
+ quiet_waits,
+ }
+}
+
+#[test]
+fn a_running_process_shows_its_new_output() {
+ let out = render(&report(ReportState::Running, "FAIL: case 3\n", 0), "wait").output();
+ assert_eq!(
+ out,
+ "Process p2 is still running (3m 5s). New output:\n[stdout]\nFAIL: case 3"
+ );
+}
+
+#[test]
+fn quiet_waits_suggest_stopping_it() {
+ let out = render(&report(ReportState::Running, "", QUIET_WAITS_NOTE), "wait").output();
+ assert!(out.contains("No new output."), "{out}");
+ assert!(out.contains("Nothing new in the last 3 waits"), "{out}");
+}
+
+#[test]
+fn an_ending_reads_like_the_matching_shell_result() {
+ let ok = render(
+ &report(ReportState::Ended(Ended::Exited(0)), "all passed", 0),
+ "wait",
+ );
+ assert!(!ok.is_error);
+ assert!(ok
+ .output()
+ .starts_with("Process p2 exited with code 0 after 3m 5s."));
+
+ let failed = render(
+ &report(ReportState::Ended(Ended::Exited(1)), "1 failed", 0),
+ "wait",
+ );
+ assert!(failed.is_error);
+ assert!(
+ failed.output().contains("exit code 1"),
+ "{}",
+ failed.output()
+ );
+
+ let timed_out = render(
+ &report(ReportState::Ended(Ended::TimedOut), "slow", 0),
+ "wait",
+ );
+ assert!(timed_out.is_error);
+ assert!(
+ timed_out
+ .output()
+ .starts_with("Command timed out after 1800s"),
+ "the timeout line stays first, as for shell: {}",
+ timed_out.output()
+ );
+}
+
+#[test]
+fn a_process_asked_about_again_says_how_it_ended() {
+ let out = render(
+ &report(ReportState::AlreadyEnded(Ended::Stopped), "", 0),
+ "wait",
+ )
+ .output();
+ assert_eq!(
+ out,
+ "Process p2 already stopped; its output was returned earlier."
+ );
+}
+
+#[test]
+fn status_reports_without_output() {
+ let out = render(&report(ReportState::Running, "", 0), "status").output();
+ assert_eq!(
+ out,
+ "Process p2 is still running (3m 5s; it stops at its 30m 0s timeout)."
+ );
+}
diff --git a/crates/openhuman-core/src/tools/impl/system/shell_support.rs b/crates/openhuman-core/src/tools/impl/system/shell_support.rs
index be9b189559..1f826c154d 100644
--- a/crates/openhuman-core/src/tools/impl/system/shell_support.rs
+++ b/crates/openhuman-core/src/tools/impl/system/shell_support.rs
@@ -139,6 +139,28 @@ pub(super) fn with_unbuffered_python(
env
}
+/// Point a native child's temp dir at the agent's granted scratch dir
+/// (`/tmp/openhuman`, a ReadWrite trusted root — see SecurityPolicy
+/// `from_config`) so `python3 tempfile` / `mktemp` / `$TMPDIR` writes land in a
+/// sandboxed, readable location instead of the world-shared /tmp.
+pub(super) fn use_scratch_tmp(env: &mut std::collections::BTreeMap<String, String>) {
+ let scratch_dir = crate::security::openhuman_scratch_dir();
+ if let (true, Some(scratch)) = (scratch_dir.is_dir(), scratch_dir.to_str()) {
+ tracing::debug!(
+ scratch_dir = %scratch_dir.display(),
+ "[shell] overriding TMPDIR/TMP/TEMP to the openhuman scratch dir"
+ );
+ for name in ["TMPDIR", "TMP", "TEMP"] {
+ env.insert(name.to_owned(), scratch.to_owned());
+ }
+ } else {
+ tracing::debug!(
+ scratch_dir = %scratch_dir.display(),
+ "[shell] scratch dir missing — leaving TMPDIR/TMP/TEMP to the module"
+ );
+ }
+}
+
/// The [`PYTHON_ENV_DEFAULTS`] a child gets, each one the parent's own value
/// when `lookup` has one.
pub(super) fn python_env_defaults(
@@ -208,3 +230,107 @@ pub(super) fn extend_explicit_environment(
}));
}
}
+
+/// When a command still running is handed back as a process, unless the call
+/// says otherwise (`yield_after_secs`).
+pub(super) const DEFAULT_YIELD_AFTER_SECS: u64 = 120;
+
+/// The yield point a call asked for: the default when absent, none for `0`.
+pub(super) fn yield_after(requested: Option<u64>) -> Option<Duration> {
+ match requested.unwrap_or(DEFAULT_YIELD_AFTER_SECS) {
+ 0 => None,
+ secs => Some(Duration::from_secs(secs.min(3600))),
+ }
+}
+
+/// The result of a call that came back with its command still running.
+pub(super) fn yielded_output(
+ id: &str,
+ elapsed: Duration,
+ timeout: Duration,
+ stdout: &str,
+ stderr: &str,
+) -> String {
+ let mut out = format!(
+ "Still running as process {id} after {}; it keeps running (it stops at its {} timeout).",
+ human_duration(elapsed),
+ human_duration(timeout),
+ );
+ out.push_str(&printed(stdout, stderr, "Output so far:", "No output yet."));
+ out.push_str(&format!(
+ "\nFollow it with shell_process {{\"process\": \"{id}\"}} to wait for more output or the \
+ end, or {{\"process\": \"{id}\", \"action\": \"kill\"}} to stop it. Do not start the \
+ command again while it runs."
+ ));
+ out
+}
+
+/// Run a native shell command for a `shell` call. In a turn with room for
+/// another process, a command still running at its yield point is handed to
+/// the turn's registry and comes back as a process id; direct dispatch (no run
+/// context) and a turn already following its limit of processes wait for the
+/// end as before.
+pub(super) async fn run_native(
+ ctx: &crate::core::runtime::DispatchCtx,
+ config: &crate::config::Config,
+ mut run: crate::sandbox::shell_exec::NativeShellRun,
+ requested_yield: Option<u64>,
+ context: Option<&dyn tinytools::ToolRunContext>,
+) -> ToolResult {
+ use crate::sandbox::shell_exec::{run_yielding, ShellRunOutcome};
+ let processes = crate::agent::tinyagents::host::run_context::shell_processes_for_tool(context)
+ .filter(|processes| processes.has_room());
+ if processes.is_some() {
+ run.yield_after = yield_after(requested_yield);
+ }
+ let (command, timeout) = (run.command.clone(), run.timeout);
+ let started = std::time::Instant::now();
+ match run_yielding(ctx, config, run).await {
+ Ok(ShellRunOutcome::Running(live)) => {
+ let Some(processes) = processes else {
+ // Unreachable: no yield point without a registry. The dropped
+ // handle stops the process.
+ return ToolResult::error("Command was left running unexpectedly.");
+ };
+ let (stdout, stderr) = (live.stdout.clone(), live.stderr.clone());
+ let id = processes.adopt(live, &command, started, timeout);
+ ToolResult::success(yielded_output(
+ &id,
+ started.elapsed(),
+ timeout,
+ &stdout,
+ &stderr,
+ ))
+ }
+ Ok(ShellRunOutcome::Finished(result)) => exec_result(Ok(result), timeout),
+ Err(error) => exec_result(Err(error), timeout),
+ }
+}
+
+/// `label` and the non-empty streams, or `empty` when both are empty.
+pub(super) fn printed(stdout: &str, stderr: &str, label: &str, empty: &str) -> String {
+ let (stdout, stderr) = (stdout.trim_end(), stderr.trim_end());
+ if stdout.is_empty() && stderr.is_empty() {
+ return format!(" {empty}");
+ }
+ let mut out = format!(" {label}");
+ if !stdout.is_empty() {
+ out.push_str("\n[stdout]\n");
+ out.push_str(stdout);
+ }
+ if !stderr.is_empty() {
+ out.push_str("\n[stderr]\n");
+ out.push_str(stderr);
+ }
+ out
+}
+
+/// `45s`, `2m 0s`, `1h 5m`.
+pub(super) fn human_duration(duration: Duration) -> String {
+ let secs = duration.as_secs();
+ match secs {
+ 0..=59 => format!("{secs}s"),
+ 60..=3599 => format!("{}m {}s", secs / 60, secs % 60),
+ _ => format!("{}h {}m", secs / 3600, (secs % 3600) / 60),
+ }
+}
diff --git a/crates/openhuman-core/src/tools/impl/system/shell_tests.rs b/crates/openhuman-core/src/tools/impl/system/shell_tests.rs
index 48f4df7a16..3da71054f3 100644
--- a/crates/openhuman-core/src/tools/impl/system/shell_tests.rs
+++ b/crates/openhuman-core/src/tools/impl/system/shell_tests.rs
@@ -60,6 +60,8 @@ fn test_security_with_env_cmd() -> Arc<SecurityPolicy> {
})
}
+#[path = "shell_tests_keep_running_tests.rs"]
+mod keep_running_tests;
#[path = "shell_tests_platform_tests.rs"]
mod platform_tests;
#[path = "shell_tests_runtime_and_sandbox_tests.rs"]
diff --git a/crates/openhuman-core/src/tools/impl/system/shell_tests_keep_running_tests.rs b/crates/openhuman-core/src/tools/impl/system/shell_tests_keep_running_tests.rs
new file mode 100644
index 0000000000..698fd4f027
--- /dev/null
+++ b/crates/openhuman-core/src/tools/impl/system/shell_tests_keep_running_tests.rs
@@ -0,0 +1,124 @@
+//! A shell command past its yield point keeps running, and `shell_process`
+//! follows it, within one turn.
+
+use super::*;
+use crate::agent::tinyagents::host::run_context::test_turn_run;
+use crate::tools::implementations::system::ShellProcessTool;
+use tinyagents_harness::ids::CallId;
+use tinyagents_harness::tool::ToolExecutionContext;
+
+fn shell() -> ShellTool {
+ ShellTool::new(
+ test_security(AutonomyLevel::Full),
+ test_runtime(),
+ test_audit(),
+ )
+}
+
+#[cfg(not(windows))]
+#[tokio::test]
+async fn a_long_command_yields_and_shell_process_follows_it_to_its_end() {
+ let run = test_turn_run();
+ let first = ToolExecutionContext::from_run_context(&run, CallId::new("c1"));
+ let result = shell()
+ .execute_with_context(
+ json!({"command": "echo first; sleep 2; echo second", "yield_after_secs": 1}),
+ ToolCallOptions::default(),
+ Some(&first),
+ )
+ .await
+ .unwrap();
+ assert!(!result.is_error, "{}", result.output());
+ let out = result.output();
+ assert!(out.starts_with("Still running as process p1"), "{out}");
+ assert!(out.contains("[stdout]\nfirst"), "{out}");
+
+ let follow = ToolExecutionContext::from_run_context(&run, CallId::new("c2"));
+ let done = ShellProcessTool::new()
+ .execute_with_context(
+ json!({"process": "p1", "wait_secs": 10}),
+ ToolCallOptions::default(),
+ Some(&follow),
+ )
+ .await
+ .unwrap();
+ assert!(!done.is_error, "{}", done.output());
+ let out = done.output();
+ assert!(out.contains("exited with code 0"), "{out}");
+ assert!(out.contains("second") && !out.contains("first"), "{out}");
+}
+
+#[cfg(not(windows))]
+#[tokio::test]
+async fn without_a_turn_a_command_runs_to_its_end() {
+ let result = shell()
+ .execute(json!({"command": "sleep 2; echo done", "yield_after_secs": 1}))
+ .await
+ .unwrap();
+ assert_eq!(result.output().trim(), "done");
+}
+
+#[cfg(not(windows))]
+#[tokio::test]
+async fn yield_after_zero_waits_for_the_end() {
+ let run = test_turn_run();
+ let call = ToolExecutionContext::from_run_context(&run, CallId::new("c1"));
+ let result = shell()
+ .execute_with_context(
+ json!({"command": "sleep 2; echo done", "yield_after_secs": 0}),
+ ToolCallOptions::default(),
+ Some(&call),
+ )
+ .await
+ .unwrap();
+ assert_eq!(result.output().trim(), "done");
+}
+
+#[cfg(not(windows))]
+#[tokio::test]
+async fn a_failing_end_reads_like_a_failed_shell_call() {
+ let run = test_turn_run();
+ let call = ToolExecutionContext::from_run_context(&run, CallId::new("c1"));
+ let yielded = shell()
+ .execute_with_context(
+ json!({"command": "sleep 2; echo broke >&2; exit 3", "yield_after_secs": 1}),
+ ToolCallOptions::default(),
+ Some(&call),
+ )
+ .await
+ .unwrap();
+ assert!(
+ yielded.output().contains("No output yet."),
+ "{}",
+ yielded.output()
+ );
+ let follow = ToolExecutionContext::from_run_context(&run, CallId::new("c2"));
+ let ended = ShellProcessTool::new()
+ .execute_with_context(
+ json!({"process": "p1"}),
+ ToolCallOptions::default(),
+ Some(&follow),
+ )
+ .await
+ .unwrap();
+ assert!(ended.is_error);
+ let out = ended.output();
+ assert!(
+ out.contains("exit code 3") && out.contains("broke"),
+ "{out}"
+ );
+}
+
+#[tokio::test]
+async fn shell_process_without_a_turn_says_so() {
+ let result = ShellProcessTool::new()
+ .execute(json!({"process": "p1"}))
+ .await
+ .unwrap();
+ assert!(result.is_error);
+ assert!(
+ result.output().contains("only a turn can leave"),
+ "{}",
+ result.output()
+ );
+}
diff --git a/crates/openhuman-core/src/tools/ops.rs b/crates/openhuman-core/src/tools/ops.rs
index 4040428411..33e0e65c67 100644
--- a/crates/openhuman-core/src/tools/ops.rs
+++ b/crates/openhuman-core/src/tools/ops.rs
@@ -139,6 +139,8 @@ pub fn all_tools_with_runtime_and_pack_handle(
let mut tools: Vec<Box<dyn Tool>> = vec![
shell,
+ // Follows a `shell` command left running past its yield point.
+ Box::new(ShellProcessTool::new()),
Box::new(FileReadTool::new(security.clone())),
file_write,
// Coding-harness baseline tools (issue #1205): file navigation
diff --git a/crates/openhuman-core/src/tools/user_filter.rs b/crates/openhuman-core/src/tools/user_filter.rs
index 71a482b77b..d1f945cde3 100644
--- a/crates/openhuman-core/src/tools/user_filter.rs
+++ b/crates/openhuman-core/src/tools/user_filter.rs
@@ -25,7 +25,7 @@ struct ToolFamily {
const TOOL_FAMILIES: &[ToolFamily] = &[
ToolFamily {
id: "shell",
- rust_names: &["shell"],
+ rust_names: &["shell", "shell_process"],
default_enabled: true,
},
// detect_tools / install_tool are filterable but not surfaced in the