Peter combines a model with your current R workspace. A language
model requests tools and returns a session; a decision model returns a
typed vector. peter() handles both. An inline agent can
compute on a multi-GB object already loaded in R, keep intermediate
variables, and reuse them across turns. This guide explains where that
computation happens, what the model receives, and where memory or file
transfers still occur.
peter() captures the prompt and context expressions and
selects the model and permission mode.For an ordinary interactive call, start with a prompt and the data:
library(gptr)
session = peter("Fit fuel economy against weight.", mtcars)
session |> peter("Plot the fitted relationship.")The executed example below uses a scripted fake
provider. It runs offline and requests the same R code each time; its
setup is hidden. An explicit environment keeps the fitted object.
work = new.env()
work$d = mtcars
session = peter("Fit fuel economy against weight.", d = work$d, model = fake,
envir = work, mode = auto)
session$text
#> [1] "The regression is ready."
session$status
#> [1] "idle"
coef(session$value)
#> (Intercept) wt
#> 37.285126 -5.344472gptr_return(fit) designates fit as the
result. The final model text is session$text; it does not
automatically become the fitted object. The result also remains
available as work$fit.
The default envir is the calling frame. At the console
that is usually the global workspace; inside a function it is that
function’s frame. Supply an environment when you want the work to
persist in a particular place. Named context such as
d = work$d labels an attachment; it does not create a
binding called d in a different evaluation environment.
gptr_describe(work$d, budget = 60)
#> [1] "<data.frame> 32 x 11, 6.9 KB"
#> [2] " mpg:dbl cyl:dbl disp:dbl hp:dbl drat:dbl wt:dbl qsec:dbl vs:dbl am:dbl gear:dbl carb:dbl"
ls(work)
#> [1] "d" "fit"
identical(session$value, work$fit)
#> [1] TRUEThe inline r tool evaluates against those actual
bindings. It does not need to write a dataset to a file or reload it
before the next tool call. Attach a large object as a plain name visible
in that environment; gptr captures that name without retaining another
copy of the object in the conversation. An expression such as
subset(d, ...) still performs ordinary R work when
evaluated, and may allocate a new object.
Workspace context lists names, classes, shapes and sizes within a budget. Attached objects get compact descriptions that can include schema, sample values and summaries. The full local object remains available to R code. Printed tool output is bounded, with an output handle for long results, and captured plots can be sent as images. Those previews and results may contain data values; the permission and egress controls still apply. System 1 decisions instead send encoded input states under their own size rules; see Typed decisions.
context = "names" reduces workspace context to names and
attachments to headers; context = "none" omits both
built-in workspace and attached-object descriptions. These settings
leave R objects available to the tools and do not suppress prompt text,
tool results or every other context block. Project instructions and
environment details remain even with context = "none", so
remote routes still require provider acknowledgment. In unattended runs,
save that consent before calling the model; offline providers and local
loopback routes are exempt (Ollama only while local-only inference is
on). See Configuration and Token efficiency.
Ordinary R copy-on-modify rules still apply. Modifying an object, keeping aliases, fitting a model or calling a package can allocate substantial memory. Workers, bridges and artifact snapshots have their own transfer or copy costs. An overlay lets reads find the parent object’s binding while keeping ordinary assignments local; it does not isolate changes to reference objects or external resources.
Undo writes nothing before a call and keeps old values by reference;
only a data.table the code changes by reference is copied. Before a call
that runs R code it keeps every object up to
undo.capture_max (100 MB) and each object the code is
predicted to change up to undo.memory (1 GB). A kept value
shares memory with the object until the object changes: a new assignment
keeps the old value alive, and an in-place edit copies what it touches,
a whole vector or matrix or one column of a data frame. After every call
the kept images stay within undo.memory in memory and
undo.disk (2 GB) on disk. Over undo.memory,
the largest image moves to disk when it fits and a .gptr/
workspace exists or a person is present; otherwise the oldest is
dropped. Images older than undo.turns (20) turns are
dropped too. An object over these limits is not kept, so a turn that
changes an object of several GB cannot be undone unless
undo.memory is raised; the approval question and the undo
report name the limit. An object you change after a turn is a conflict,
kept unless force = TRUE (?gptr_rewind lists
the edits it cannot see). Configuration
shows how to change these limits.
A continued session reuses its kept home environment unless you
explicitly supply a new envir. When the default environment
is a function call frame, gptr uses it during the active run and does
not retain it as the session’s home afterward. An explicit working
environment can retain named results. An explicit
gptr_fork(session) branches the conversation and uses a
workspace overlay. Restoring a session from disk restores its
conversation; it does not restore all of your R objects.
Each model request has provider and transport latency. R evaluation takes the time and memory its code needs; memory pressure can slow work or make an allocation fail. A file-backed matrix, Arrow dataset or database connection may read from disk through its package even when its R handle is already loaded. Use those packages’ normal subset and compute operations rather than assuming every object is a fully resident data frame.
session$id
#> [1] "sd50f1e5e3b"
session$model
#> [1] "fake/fake-1"
session$turns
#> [1] 1
gptr_usage(session)
#> group requests input output cache_read cache_write cost
#> 1 sd50f1e5e3b 2 3435 20 0 0 0
#>
#> # 1 row
#> 2 requests, 3.4k tokens in, $0.0000| Interface | Use |
|---|---|
session$text, session$value,
session$status |
Inspect the answer, R result and state |
session$messages, session$history,
session$usage |
Inspect conversation, history and usage |
session |> peter("next question") |
Add a turn to the same conversation |
gptr_step(), gptr_wait(),
gptr_steer(), gptr_cancel() |
Drive or control a session |
gptr_sessions(), gptr_resume(),
gptr_last() |
Find stored or live sessions |
gptr_on() |
Attach a session event handler |
gptr_fork(), gptr_checkpoints(),
gptr_rewind() |
Branch or recover supported state |
Printing session$history or
summary(session) shows eight recent messages and session
details without a model request. The underlying table keeps every
message; unknown token counts stay unknown.
session$history
#> turn role preview tools tokens
#> 1 1 user Fit fuel economy agai... 8
#> 2 1 operator <gptr_runtime> Curren... 94
#> 3 1 assistant r 1729
#> 4 1 tool_result + fit <lm length 12> r 5
#> 5 1 assistant The regression is ready. 1726
#> # 5 recorded messages
#> idle . fake/fake-1 . 1 turn . 3.5k tokens . $0.0000 . sd50f1e5e3b
as.data.frame(session$history)[, c("turn", "role", "tools", "tokens")]
#> turn role tools tokens
#> 1 1 user 8
#> 2 1 operator 94
#> 3 1 assistant r 1729
#> 4 1 tool_result r 5
#> 5 1 assistant 1726Without an initialized project workspace, session files use a
temporary directory. gptr_init() creates
.gptr/ for project storage. Recording an R document is a
separate choice; see Record, replay and
export.
A history document records executed code, decisions and bounded output. It does not automatically archive the full input dataset. Replay runs the recorded R procedure again; provide its input objects, packages and required files in a fresh session. Answer caches, checkpoints and artifact data snapshots are separate storage mechanisms. File checkpoints back up the files Peter’s tools name before they run, plus what a bounded scan of the working directory finds; other changed files have no automatic backup. See Teams and background work for the limits and for rewinding.
manual is the default: actions classified as read-only
can run, while changes require approval. plan is for
inspection and proposals; edits allows approved classes of
project file edits; auto allows ordinary tool work without
prompting. The plan a plan run proposes goes once, as a
<plan> block, to the next top-level
peter() call from the same environment, within an hour and
in another mode, whatever that call asks: a script runs the plan with
peter("Go ahead.", mode = auto). Another
peter() call first discards it, and
options(gptr.plan_handoff = FALSE) turns the hand-off off.
Critical, secret and control guards remain separate. yolo,
which only you can select, also runs gptr’s own configuration functions
and secret reads; deleting protected files, files outside the project or
the project itself, moving the working directory out of the project,
rm(list = ls()), options(gptr.*) and sending a
secret over the network still ask. In auto and
yolo, a system() or system2()
call whose command the code computes is refused: the model is told to
run the command with peter$sh(), whose command the
permission rules check when it runs. A permission gate is not an
isolation boundary. External CLIs also have their own sandbox and tool
controls; live R requests still pass through gptr’s MCP gate. Use Configuration and
?gptr_security to choose a mode and understand its
limits.
HTTP requests, CLI processes, MCP connections and workers share one event loop. Multiple requests can wait for I/O together. Inline R code runs serially in the owning R process and pauses event-loop callbacks until evaluation returns. A worker is a separate R process and receives serializable context; it does not share the parent workspace. See Teams and background work.
Model code in a top-level run, and in a plain peter()
sub-agent it starts, draws from your random-number stream, as your own
code would. Members of a team, a fan-out or gptr_parallel()
draw from their own stream, so your .Random.seed is
preserved around them, except after a deliberate RNGkind()
change or a callback R runs while idle.