A host-owned R worker for iterative calculations and plots. Construct an
Agent with fixed conversation identity in run_context, then register
$tools(). Each owner has independent R variables and loaded packages.
Calls queue in order and return promises without blocking other conversations.
The worker executes with the local account's access. It provides process
isolation, not an OS security sandbox. Agent permissions gate the registered
tool; $run() is an explicit trusted host operation, not a governed Agent run.
Each call starts in the Agent's immutable working directory. A setwd() in
evaluated code applies only until the next call.
$cancel() and timeouts terminate the worker and discard its variables and
queued calls. Later calls start fresh and report that fact. External effects
are not rolled back. $close() is terminal; the host must call it when the
conversation is disposed. Garbage collection also closes the worker.
Results contain native ellmer text/images, embedded display HTML, and a plain
extra$deputy_r execution record. Store conversation turns to keep code,
output and plots reviewable after reopening. Agent snapshots retain current
model turns; hosts must store full display history separately across compaction.
Worker variables are live state,
are not included in Agent session files, and must be recreated after restart.
Static base, ggplot2, grid and patchwork figures are supported. Visible
htmlwidgets and rich HTML tables report unsupported_output; they are not
persisted as interactive artifacts. Print underlying data for a text table.
Owners and executable tools cannot be cloned or transferred between Agents.
Methods
RSession$new()
Create a lazy R worker owner. No code is executed here.
Usage
RSession$new(
agent,
timeout = 30,
startup_timeout = 60,
queue_limit = 16L,
max_output_bytes = 8 * 1024 * 1024,
plot_width = 1000L,
plot_height = 650L
)Arguments
agentAgent owning the session and its conversation identity.
timeoutMaximum seconds for each dispatched execution.
startup_timeoutMaximum seconds for worker startup.
queue_limitMaximum waiting calls, excluding the active call.
max_output_bytesMaximum retained output bytes per execution. This bounds captured evidence, not arbitrary R allocations or effects.
plot_width, plot_heightPNG plot dimensions in pixels.
RSession$run()
Enqueue a trusted host execution. Invalid inputs fail before admission.
Returns
A promise resolving to an ellmer::ContentToolResult. R errors,
worker failures and cancelled queued calls are retained as result evidence.