Shell Runner

The Shell Runner enables shell command execution as a first-class citizen in AgentSessionManager. It provides two complementary modules:

Workspace.Exec -- Low-Level Command Execution

AgentSessionManager.Workspace.Exec provides direct command execution with timeout, output capture, and streaming. Use it when you need lightweight command execution without session management overhead.

Basic Usage

{:ok, result} = AgentSessionManager.Workspace.Exec.run("mix", ["test"])
IO.puts("Exit code: #{result.exit_code}")
IO.puts("Output: #{result.stdout}")

With Options

{:ok, result} = AgentSessionManager.Workspace.Exec.run(
  "npm", ["run", "build"],
  cwd: "/home/user/project",
  timeout_ms: 120_000,
  env: [{"NODE_ENV", "production"}]
)

Streaming

AgentSessionManager.Workspace.Exec.run_streaming("mix", ["test", "--trace"])
|> Enum.each(fn
  {:stdout, data} -> IO.write(data)
  {:exit, code} -> IO.puts("\nExit: #{code}")
  {:error, reason} -> IO.puts(:stderr, "Error: #{inspect(reason)}")
end)

Options

Option	Type	Default	Description
`:cwd`	`String.t()`	`File.cwd!()`	Working directory
`:timeout_ms`	`pos_integer()`	`30_000`	Command timeout
`:max_output_bytes`	`pos_integer()`	`1_048_576`	Output size limit
`:env`	`[{String.t(), String.t()}]`	`[]`	Environment variables
`:on_output`	`(chunk -> any())`	`nil`	Callback for streaming output

ShellAdapter -- Managed Execution via SessionManager

AgentSessionManager.Adapters.ShellAdapter implements the ProviderAdapter behaviour, enabling shell commands to participate in the full SessionManager lifecycle: event emission, policy enforcement, workspace snapshots, concurrency control, and persistence.

Basic Usage

alias AgentSessionManager.Adapters.{ShellAdapter, InMemorySessionStore}
alias AgentSessionManager.SessionManager

{:ok, store} = InMemorySessionStore.start_link([])
{:ok, adapter} = ShellAdapter.start_link(cwd: File.cwd!())

{:ok, result} = SessionManager.run_once(store, adapter, "mix test",
  event_callback: fn event ->
    case event.type do
      :message_streamed -> IO.write(event.data.delta)
      :run_completed -> IO.puts("\nDone")
      _ -> :ok
    end
  end
)

Input Formats

ShellAdapter accepts three input formats:

# String -- executed via /bin/sh -c
"mix test --cover"

# Structured map -- explicit command and args
%{command: "mix", args: ["test", "--cover"], cwd: "/path", timeout_ms: 60_000}

# Messages (compatibility) -- extracts user content as command
%{messages: [%{role: "user", content: "mix test"}]}

Configuration

Option	Type	Default	Description
`:cwd`	`String.t()`	required	Working directory
`:timeout_ms`	`pos_integer()`	`30_000`	Default command timeout
`:max_output_bytes`	`pos_integer()`	`1_048_576`	Max output capture size
`:env`	`[{String.t(), String.t()}]`	`[]`	Environment variables
`:shell`	`String.t()`	`"/bin/sh"`	Shell for string commands
`:allowed_commands`	`[String.t()]`	`nil`	Allowlist (nil = all)
`:denied_commands`	`[String.t()]`	`nil`	Denylist of blocked commands
`:success_exit_codes`	`[integer()]`	`[0]`	Exit codes treated as success

Event Mapping

Shell Event	Normalized Event	Notes
Command started	`:run_started`	Execution begins
Command started	`:tool_call_started`	tool_name: "bash"
Command completed (exit 0)	`:tool_call_completed`
Command failed (exit != 0)	`:tool_call_failed`
Full output	`:message_received`	Complete stdout
Success	`:run_completed`	stop_reason: "exit_code_0"
Failure	`:run_failed`	error_code: :command_failed
Timeout	`:run_failed`	error_code: :command_timeout
Cancelled	`:run_cancelled`

Security

Use allowed_commands and denied_commands to restrict which commands can be executed:

{:ok, adapter} = ShellAdapter.start_link(
  cwd: File.cwd!(),
  allowed_commands: ["mix", "npm", "git"],
  denied_commands: ["rm", "sudo", "chmod"]
)

The denylist takes precedence over the allowlist. Both match against the base name of the executable.

Mixed AI + Shell Workflows

ShellAdapter enables mixed workflows where AI and shell runs participate in the same session lifecycle:

{:ok, claude} = ClaudeAdapter.start_link([])
{:ok, shell} = ShellAdapter.start_link(cwd: File.cwd!())

# Step 1: Ask AI to generate code
{:ok, _} = SessionManager.run_once(store, claude, "Write a test")

# Step 2: Run the tests
{:ok, test_result} = SessionManager.run_once(store, shell, "mix test")

# Step 3: If tests fail, ask AI to fix
if test_result.output.exit_code != 0 do
  SessionManager.run_once(store, claude,
    "Tests failed: #{test_result.output.content}\nPlease fix.")
end

← Previous Page Provider Adapters

Next Page → Concurrency