Module agentforge4j.runtime
Package com.agentforge4j.runtime.command

Interface ShellCommandRunner

Functional Interface:
This is a functional interface and can therefore be used as the assignment target for a lambda expression or method reference.
@FunctionalInterface public interface ShellCommandRunner
Abstraction over the RunCommandCommand side effect.

Shell execution is opt-in by design. An embedding application that does not want its agents running shell commands simply does not register a ShellCommandRunner — the runtime then falls back to NO_OP_SHELL_COMMAND_RUNNER, which runs no process and returns an empty result for any RUN_COMMAND command.

Sandboxing is entirely the embedder's responsibility. Implementations receive unvalidated, LLM-produced command strings. The runtime does not sanitize, parse, or restrict the command before calling run(String, String).

Implementations are responsible for:

  • command allow-listing or denylisting
  • argument escaping
  • working-directory restriction
  • filesystem and network sandboxing
  • resource limits (CPU, memory, wall-clock)
  • output size capping
  • never executing under elevated privileges

A default no-op or "reject all" implementation is acceptable for embedders that do not intend to support shell execution (see NO_OP_SHELL_COMMAND_RUNNER).

Implementations must not log the full command at INFO or above without considering that it may contain secrets injected via workflow context.

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final ShellCommandRunner
    NO_OP_SHELL_COMMAND_RUNNER
    Runs no process and returns an empty string.

  • Method Summary

    Modifier and Type
    Method
    Description
    String
    run(String runId, String command)
    Execute the given shell command on behalf of the given run.

  • Field Details

    • NO_OP_SHELL_COMMAND_RUNNER

      static final ShellCommandRunner NO_OP_SHELL_COMMAND_RUNNER
      Runs no process and returns an empty string.

  • Method Details

    • run

      String run(String runId, String command)
      Execute the given shell command on behalf of the given run.

      The command string is passed through from agent output without runtime validation. See the interface Javadoc for embedder sandbox obligations.

      Parameters:
      runId - id of the owning run — useful for scoping the working directory
      command - the command to execute
      Returns:
      the captured stdout of the command