Mutation tools
4-mutation-tools.RmdGoal
Phase 4 turns the Phase 3 staging primitive into a usable surface for
the LLM: nine mutation tools (add_block,
remove_block, modify_block,
add_link, remove_link,
modify_link, add_stack,
remove_stack, modify_stack) that the assistant
can call to build and edit a board. Every tool is a thin façade over the
Phase 3 stage API — its body constructs the relevant object (or forwards
a delta), calls a stage_* function, and returns a short
result string. No new dispatch path, no parallel reactive structure
visible to the model: every mutation accumulates into the
pending_update reactiveVal and flushes via the existing
flush_pending hook on last_turn.
The phase deliberately pushes routing complexity down into
blockr.core. A modify_block call ships a
single partial-args delta as part of an update(...)
payload; core decides whether to service it as an external-control write
or as an atomic re-setup of the block server (see blockr.core#175).
The consumer sees one shape and does not branch.
Scope
In:
- Nine mutation tools, registered alongside the Phase 2 read tools via
a new
register_mutation_tools()helper. - A refactor of Phase 3’s
stage_block_mod(),stage_stack_mod()andstage_link_mod()to accept a partial-args delta rather than a full constructed object — matching the unified dispatch shape agreed in blockr.core#175. -
inst/examples/empty-board/for manual smoke-testing against a live LLM. - Tests covering each tool’s happy path, the new delta-mod conflict
rows, ID-generation behaviour, and a turn-boundary end-to-end test via
shiny::testServer().
Out (deferred to later phases or out of roadmap):
- Same-turn read-after-write. The Phase 2 read tools continue to read the committed board only. Staged operations are visible to the model only through its own tool-call history. Revisited if Phase 5 telemetry shows the model is confused.
- A “pending changes” UI affordance (badge, diff preview, apply-now button). The reactiveVals are observable; an extension is cheap to bolt on later.
- Snapshot / undo. Atomicity at the turn boundary is what we ship;
multi-turn rollback waits on
blockr.sessionhooks that do not yet exist. - Per-block-type custom tools. Block packages contributing tools
(
set_filter_expression, etc.) is a separate roadmap item. - Multi-board / multi-session orchestration. Extension state is scoped to the board it is mounted on.
Phase 4 is gated on the blockr.core change tracked at blockr.core#175:
unified delta-shape mod slots for all three entity types
(blocks, stacks, links), with blocks additionally routed internally to
external-control writes vs. atomic re-setup. Until that lands, Phase 4
pins blockr.core via Remotes: to the branch
carrying the fix. The design proceeds as if the unified dispatch is
already available.
Architectural decisions
Trust core to dispatch; do not split routing in the consumer
The natural shape for modify_block(id, args) is one tool
that ships one update(...) payload — and trusts the
framework to do the right thing. Today (pre-#175) the framework forces
consumers to choose: write external-control reactiveVals directly
(bypassing update() entirely, fast but per-call cascade),
or stage a blocks$mod entry that won’t actually re-run the
server. Splitting that choice in every consumer of the mutation
API leaks an implementation detail of blockr.core into
every LLM-driven (or script-driven) board mutator.
Phase 4 takes the opposite stance. modify_block stages
exactly one thing — a partial-args delta in
pending_update$blocks$mod[[id]] — and
flush_pending ships it via update(...). The
core routing table (ctrl write if all changed args are ctrl-able on the
live block; atomic re-setup otherwise) is core’s problem.
Two consequences shape the rest of this document:
-
No
pending_ctrlreactiveVal. Phase 3 left the door open for a parallel staging structure for ctrl writes (“if this turns out painful”). Phase 4 walks through that door and back out: the only staging structure for the whole tool surface is theupdate(...)-shapedpending_updatefrom Phase 3. No sibling reactiveVals. -
The model sees uniform semantics. Every mutation
tool returns
"Staged <tool>(<id>) — will apply at turn end.". No tool fires side-effects mid-turn. The whole assistant turn is one atomic board update.
Mods are deltas; adds are full constructions
Mutation tools split into two shapes:
-
add_block,add_link,add_stackcarry the full set of constructor arguments and produce a typed object (blockr.core::create_block(type, ...),new_link(...),new_stack(...)). The constructor call is the natural place to surface “missing required arg” / “wrong type” errors to the model, routed throughwith_tool_errorsinto a<tool> failed: <reason>string. Construction-as-validation: we have to construct the object to stage it anyway, so the validation is free. -
modify_block,modify_stack,modify_linkcarry a partial-args delta (a named list of just the keys being changed). No construction in the consumer. The delta lands inpending_update$<entity>$mod[[id]]and flushes as part of theupdate(...)payload. Core merges the delta against the live entry, validates, and dispatches.
Why the asymmetry? An add knows everything (it’s bringing a new
object into existence); a mod knows only the diff. For blocks and
stacks, the current args live inside an opaque object —
blockr.core does not export a block_args()
readback, and stack subclasses
(e.g. blockr.dock::dock_stack with its color
attribute) make generic readback brittle. Forcing the consumer to
reconstruct a full object for a one-arg change would require either a
generic arg-readback API or a stateful mirror of every entity’s args
inside the extension. Neither is worth the cost when core can do the
merge in one place. Links are not subclassable today and could
support full-replace from the consumer side, but Phase 4 puts them on
the delta path too for API symmetry — every modify_* tool
has the same body shape, every mod slot has the same
payload shape.
This means stage-time validation for mods is shallow — at the
consumer we can only check that the delta is a named list. The
substantive validation (does n_rows exist on a
head_block? is the proposed value the right type?) runs at
flush against the live entry, in core. The cost: a typo’d arg name in
modify_block goes undetected until turn end. The benefit:
we don’t ship a parallel schema layer in the consumer that’s guaranteed
to drift from blockr.core’s actual constructor
signatures.
Block ids are immutable for committed blocks
The assistant cannot change the id of a block that already exists on
the board. There is no change_id tool, no embedded
id-change arg on modify_block, no path of any kind. Same
for links and stacks.
The reasoning:
-
Ids are system identifiers, not user-facing labels.
Blocks carry an
id(the registry key) and a per-type displaynameregistered viaregister_block(ctor, name, ...). The display name is type-level metadata, not per-instance editable surface; a “rename this block” user request maps onto changing the rendered label in the board UI (out of scope for Phase 4) or picking a different block type, not on changing the registry key. The conflation of “name” and “id” in casual speech is what makes this worth spelling out. -
Stable ids = stable model context. The model is
rebuilding its mental model of the board across turns from
list_blocks/describe_blockoutput. If ids could drift mid-conversation, the model’s tool-call history and current board state would desynchronise. -
External references stay valid. Saved app state,
bookmarks, upstream observers that key off block id, and any future
blockr.sessionintegration all assume committed ids are stable. The assistant’s mutation surface should not be the thing that breaks that.
For a staged (not yet committed) block, the id is freely
changeable — but not via a dedicated tool. The model just stages a
remove_block(old_id) followed by
add_block(<type>, <args>, id = new_id).
Behaviorally identical to re-keying the pending entry, costs two tool
calls instead of one, and avoids a tool that has to detect “is this id
pending vs. committed?” and dispatch differently.
If a user asks the assistant to change a committed block’s id, the
expected handling is conversational: the assistant explains it can offer
remove_block(old_id) + add_block(<type>, <args>, id = new_id),
but that tears down the block server (lost eval state, re-evaluation of
downstream blocks), and asks the user whether that’s acceptable. Phase
5’s prompt-context layer will likely codify this kind of guidance into
the system prompt.
Same rule applies to link and stack ids. The conflict table has no id-change rows for any entity type.
Hybrid ID generation via blockr.core::rand_names()
add_block, add_link, add_stack
all accept an optional id argument:
- If the model supplies an id, it is used as-is. Uniqueness against
the merged board-plus-pending state is checked by core’s validator at
stage time (Phase 3’s
validate_pendingalready runs the full validator chain). Format constraints are whatever core enforces — we do not layer our own. - If the model omits the id, the package generates one via
blockr.core::rand_names(old_names = existing_ids(board, pending)). Core’s defaultrand_namesproducesadjective-animalids (quick-elephant,tidy-otter) via the optionalidspackage, falling back to random letter strings. The tool result string echoes the final id in either path.
Result string template:
"Staged add_block(quick-elephant) — will apply at turn end."
The id is always present and unambiguous, so the model can quote it in subsequent calls without needing a separate listing tool.
Read tools stay committed-only (reaffirmed)
Phase 3’s deferred decision is settled in favour of option (1): read
tools read board$board, not a merged
board-plus-pending view. The reasons accumulated since Phase 3 still
hold:
- The stage-time validator already accounts for pending state when
checking cross-references (e.g. an
add_link(foo→bar)staged after anadd_block(foo)validates against the merged payload thanks tovalidate_pendingcalling through tocombine_update_blocksin core). -
get_block_resultcannot return a value for a pending block (no server has been built yet), so a partial merge view would create the illusion of a usable block. - The model’s own tool-call history records what it staged this turn — a separate “list pending” surface adds nothing the conversation log does not already carry.
If Phase 5’s user-test telemetry surfaces friction here, the
lightweight fix is a new list_pending_changes() tool that
explicitly reports the staged operations (not a retrofit of the existing
read tools).
Validity checks delegated to core
Phase 3’s validate_pending(payload, board) runs the full
validate_board_update chain on every stage. Cycles,
dangling block references in links, missing target inputs, duplicate ids
and the rest are caught there against the merged state. Phase 4 adds
nothing new. The stagers stay thin: collapse against the conflict table,
call commit_pending, return. There is no consumer-side
re-implementation of any cross-reference rule.
Reject add → mod; recover via
remove + add
Phase 3’s conflict table lenient-collapses add(x)
followed by mod(x): the pending add’s value is replaced by
the mod’s new value. In Phase 3 the mod carried a full block
object, so the collapse was a trivial swap. In Phase 4 the mod
carries a delta, and producing the collapsed value would
require rebuilding the staged block with the merged args via
create_block(type, merged_args). The original
(type, args) recipe is known at stage time of the
add_block call, but discarded once the block is stored —
there is no public arg readback on a constructed block.
We could maintain a sidecar recipe cache (a second reactiveVal keyed
by id holding list(type = ..., args = ...) for every staged
add). It would close the gap and keep the row a collapse. The cost is a
second reactiveVal that has to stay in lockstep with
pending_update across every add and rm, plus a more complex
stage_block_mod that branches on “is this a live-board
target or a pending-add target?”.
Phase 4 takes the simpler trade. The add → mod
row rejects. The model recovers by issuing
remove_block(x) + add_block(type, corrected_args, id = "x")
instead. The corrected args are visible to the model in its own
tool-call history (the prior add_block call sits in the
conversation log with the original type and
args), so reconstructing them is not a knowledge
problem.
The rejection error string points the model at the recovery path explicitly:
"modify_block(foo) failed: foo is staged for creation this turn.
Use remove_block(foo) followed by add_block(<type>, <args>, id = \"foo\")
with the corrected arguments."
Cost: extra tokens when the model self-corrects a pending-add mid-turn, especially for blocks with many args. The frequency is bounded (only triggers on same-turn second-thoughts about an add). Benefit: no second reactiveVal, no recipe bookkeeping, no divergence risk between the staged block and its recipe.
Same rule for stacks:
add_stack(x) → modify_stack(x, ...) rejects. Base stacks
expose stack_blocks() / stack_name() readers,
but subclasses such as blockr.dock::dock_stack add extra
attributes (e.g. color) without a generic readback API, so
a recipe-free collapse is not portable across subclasses. Keeping the
rule uniform across block and stack mods is also easier for the model to
internalise than two different behaviours for two
superficially-identical operations.
The one collapse that doesn’t need reconstruction is still
in the table: add(x) → rm(x) drops the pending add. A
trivial named-list manipulation, no recipe required.
Conflict table for delta-mods
Phase 3’s nine-row table for blocks extends with one row flip:
add → mod becomes a reject (see previous section) rather
than a collapse. The remaining collapses keep their Phase 3 mechanics
except for mod → mod, where the collapse now merges deltas
key-wise rather than replacing the full block.
For blocks ({add, mod, rm} × {add, mod, rm}):
| Prior pending entry | Stage call | Outcome |
|---|---|---|
add(x) |
add(x, ...) |
reject — duplicate id |
add(x) |
mod(x, ...) |
reject — x is staged for creation; use
remove_block + add_block with corrected args |
add(x) |
rm(x) |
collapse — drop pending add |
mod(x, d1) |
add(x, ...) |
reject — x exists on board, cannot re-add |
mod(x, d1) |
mod(x, d2) |
collapse — pending mod becomes
merge_args(d1, d2) (key-wise last-write-wins) |
mod(x, d1) |
rm(x) |
collapse — discard pending mod, stage
rm
|
rm(x) |
any (x, ...)
|
reject — x is being removed |
The merge_args(prev, new) helper is named-overwrite:
keys in new replace prev; keys in prev not
present in new survive. Matches “delta means partial
override”.
Stacks and links follow the same table, substituting the appropriate
modify_* tool name. All three entity types have an
identical conflict shape now that links also surface a
modify_* tool with delta semantics.
Principle inherited from Phase 3: collapse where the combined intent
is unambiguous and cheap, reject otherwise (including the one Phase 4
reject — add → mod — that buys us no recipe cache).
Tool result formatting
All nine tools follow the same template:
"Staged <tool>(<id>) — will apply at turn end."
Same shape as Phase 3’s format_stage_error for failures
("<tool>(<id>) failed: <reason>") so the
model parses one consistent pattern across the whole API.
No structured tool result (no JSON object). The model consumes the chat content of the tool result; a single sentence is enough for it to confirm the call landed and to recall the id later. Phase 5 may revisit this if richer telemetry helps the model self-correct.
Atomicity, errors, and flush rejection
Inherited from Phase 3 unchanged:
- A turn’s mutations are atomic. Any stage error throws from the tool
body, gets re-shaped by
with_tool_errors, and goes back to the model as a<tool> failed: <reason>string. The pending payload is not mutated by a failing stage — the model can retry. - Flush rejection (validator throws at
update(...)dispatch time) discards the whole staged payload and logs a warning. The user sees the standard Shiny notification fromblockr.core’s validator; the model sees nothing on the next turn unless the user (or Phase 5’s prompt-context layer) tells it. - No partial apply on flush. Phase 4 changes nothing here.
Tool surface
Each tool factory has the Phase 2 shape:
tool_<name>(board, update, pending, session) returns
an ellmer::tool(...). Bodies below elide the
with_tool_errors("<name>", { ... }) wrapper for
brevity; assume each tool body is wrapped exactly like the Phase 2 read
tools at R/tools-read.R.
add_block(type, args, id = NULL)
tool_add_block <- function(board, update, pending, session) {
ellmer::tool(
function(type, args, id = NULL) {
id <- id %||% rand_names(existing_ids(board, pending, "blocks"))
parsed <- jsonlite::fromJSON(args, simplifyVector = TRUE)
block <- do.call(create_block, c(list(type), parsed))
stage_block_add(pending, board, id, block)
sprintf(
"Staged add_block(%s) — will apply at turn end.", id
)
},
name = "add_block",
description = paste(
"Add a new block to the board. `type` is a block id as",
"reported by list_available_blocks. `args` is a JSON object",
"(passed as a string) of constructor arguments — field names",
"must match the arg names reported by list_available_blocks",
"for the chosen type. `id` is optional — if omitted,",
"a unique id is generated."
),
arguments = list(
type = ellmer::type_string(
"Block type id, from list_available_blocks."
),
args = ellmer::type_string(
paste(
"JSON object of constructor arguments, e.g.",
"'{\"n\": 10}'. Field names match list_available_blocks."
)
),
id = ellmer::type_string(
"Optional id for the new block. Generated if omitted.",
required = FALSE
)
)
)
}args ships as a JSON-formatted string rather than a
native object because ellmer’s type_object requires a
closed key list and the only escape hatch
(.additional_properties = TRUE) is deprecated and only
supported by Claude. A JSON-string parameter is provider-agnostic; the
body parses with jsonlite::fromJSON and surfaces parse
failures, construction failures (missing required arg, wrong type,
unknown type id) through the
<tool> failed: <reason> envelope.
stage_block_add enforces uniqueness against board + pending
via core’s validator and the conflict-table reject rows.
remove_block(id)
tool_remove_block <- function(board, update, pending, session) {
ellmer::tool(
function(id) {
stage_block_rm(pending, board, id)
sprintf(
"Staged remove_block(%s) — will apply at turn end.", id
)
},
name = "remove_block",
description = paste(
"Remove a block from the board. Any links to or from the",
"block are cleaned up at apply time by core; the model does",
"not need to remove them explicitly."
),
arguments = list(
id = ellmer::type_string("Block id to remove.")
)
)
}The cascade-cleanup of orphaned links and stack memberships is core’s
job at preprocess_board_update time. The tool does not
stage those; the model does not need to know they happen.
modify_block(id, args)
tool_modify_block <- function(board, update, pending, session) {
ellmer::tool(
function(id, args) {
delta <- jsonlite::fromJSON(args, simplifyVector = TRUE)
stage_block_mod(pending, board, id, delta)
sprintf(
"Staged modify_block(%s) — will apply at turn end.", id
)
},
name = "modify_block",
description = paste(
"Change one or more constructor arguments of an existing",
"block. `args` is a JSON object (passed as a string) of",
"just the keys being changed; unmentioned keys keep their",
"current values."
),
arguments = list(
id = ellmer::type_string("Id of the block to modify."),
args = ellmer::type_string(
paste(
"JSON object of arguments to change, e.g.",
"'{\"n\": 5}'. Only supplied keys are modified."
)
)
)
)
}Same JSON-string treatment as add_block for the same
reason — ellmer cannot model an open-keyed object portably.
stage_block_mod writes the parsed delta into
pending$blocks$mod[[id]], collapses with a prior pending
mod by key-wise merge, or rejects against a pending
add / rm per the conflict table. No
construction in the consumer.
add_link(from, to, input, id = NULL)
tool_add_link <- function(board, update, pending, session) {
ellmer::tool(
function(from, to, input, id = NULL) {
id <- id %||% rand_names(existing_ids(board, pending, "links"))
link <- new_link(from, to, input)
stage_link_add(pending, board, id, link)
sprintf(
"Staged add_link(%s: %s → %s$%s) — will apply at turn end.",
id, from, to, input
)
},
name = "add_link",
description = paste(
"Add a link that wires the output of block `from` into",
"argument `input` of block `to`. Both blocks must exist on",
"the board or be staged for creation in this turn."
),
arguments = list(
from = ellmer::type_string("Source block id."),
to = ellmer::type_string("Destination block id."),
input = ellmer::type_string(
"Input slot on the destination block."
),
id = ellmer::type_string(
"Optional id for the new link. Generated if omitted.",
required = FALSE
)
)
)
}Cross-reference validity (both blocks exist, input is a
valid slot on to, no cycle introduced) is checked by core’s
validator at stage time against the merged board-plus-pending state.
remove_link(id)
tool_remove_link <- function(board, update, pending, session) {
ellmer::tool(
function(id) {
stage_link_rm(pending, board, id)
sprintf(
"Staged remove_link(%s) — will apply at turn end.", id
)
},
name = "remove_link",
description = "Remove a link by its id.",
arguments = list(
id = ellmer::type_string("Link id to remove.")
)
)
}
modify_link(id, from = NULL, to = NULL, input = NULL)
tool_modify_link <- function(board, update, pending, session) {
ellmer::tool(
function(id, from = NULL, to = NULL, input = NULL) {
delta <- compact(list(from = from, to = to, input = input))
stage_link_mod(pending, board, id, delta)
sprintf(
"Staged modify_link(%s) — will apply at turn end.", id
)
},
name = "modify_link",
description = paste(
"Retarget an existing link. Any combination of `from`, `to`,",
"and `input` may be supplied; only supplied fields are",
"changed. Omitted fields keep their current values."
),
arguments = list(
id = ellmer::type_string("Id of the link to modify."),
from = ellmer::type_string(
"New source block id.",
required = FALSE
),
to = ellmer::type_string(
"New destination block id.",
required = FALSE
),
input = ellmer::type_string(
"New input slot on the destination block.",
required = FALSE
)
)
)
}
add_stack(blocks, name = NULL, id = NULL)
tool_add_stack <- function(board, update, pending, session) {
ellmer::tool(
function(blocks, name = NULL, id = NULL) {
id <- id %||% rand_names(existing_ids(board, pending, "stacks"))
stack <- new_stack(blocks = blocks, name = name)
stage_stack_add(pending, board, id, stack)
sprintf(
"Staged add_stack(%s) — will apply at turn end.", id
)
},
name = "add_stack",
description = paste(
"Group a set of blocks into a stack. `blocks` is a",
"character vector of block ids; `name` is an optional",
"human-readable label."
),
arguments = list(
blocks = ellmer::type_array(
"Block ids to include in the stack.",
items = ellmer::type_string()
),
name = ellmer::type_string(
"Optional display name for the stack.",
required = FALSE
),
id = ellmer::type_string(
"Optional id for the new stack. Generated if omitted.",
required = FALSE
)
)
)
}
remove_stack(id)
tool_remove_stack <- function(board, update, pending, session) {
ellmer::tool(
function(id) {
stage_stack_rm(pending, board, id)
sprintf(
"Staged remove_stack(%s) — will apply at turn end.", id
)
},
name = "remove_stack",
description = paste(
"Remove a stack. Member blocks are not removed; only the",
"grouping disappears."
),
arguments = list(
id = ellmer::type_string("Stack id to remove.")
)
)
}
modify_stack(id, blocks = NULL, name = NULL)
tool_modify_stack <- function(board, update, pending, session) {
ellmer::tool(
function(id, blocks = NULL, name = NULL) {
delta <- compact(list(blocks = blocks, name = name))
stage_stack_mod(pending, board, id, delta)
sprintf(
"Staged modify_stack(%s) — will apply at turn end.", id
)
},
name = "modify_stack",
description = paste(
"Change a stack's member blocks and/or name. Either or both",
"arguments may be omitted; only supplied fields are",
"changed."
),
arguments = list(
id = ellmer::type_string("Stack id to modify."),
blocks = ellmer::type_array(
"New set of member block ids.",
items = ellmer::type_string(),
required = FALSE
),
name = ellmer::type_string(
"New display name.",
required = FALSE
)
)
)
}compact() is a small utility that strips
NULL entries from a list — so a modify_stack
call that supplies only name produces a delta
list(name = ...) with no blocks key.
Stage API changes from Phase 3
The Phase 3 stagers take full constructed objects for mods. With the
unified delta shape, the three mod stagers all change
signature. No new stagers.
| Function | Phase 3 signature | Phase 4 signature |
|---|---|---|
stage_block_add |
(pending, board, id, block) |
unchanged |
stage_block_mod |
(pending, board, id, block) |
(pending, board, id, delta) |
stage_block_rm |
(pending, board, id) |
unchanged |
stage_stack_add |
(pending, board, id, stack) |
unchanged |
stage_stack_mod |
(pending, board, id, stack) |
(pending, board, id, delta) |
stage_stack_rm |
(pending, board, id) |
unchanged |
stage_link_add |
(pending, board, id, link) |
unchanged |
stage_link_mod |
(pending, board, id, link) |
(pending, board, id, delta) |
stage_link_rm |
(pending, board, id) |
unchanged |
The internal conflict-handling in stage_block_mod
becomes:
stage_block_mod <- function(pending, board, id, delta) {
cur <- isolate(pending())
if (id %in% names(cur$blocks$add)) {
stage_abort(
"modify_block", id,
paste0(
id, " is staged for creation this turn. Use remove_block(",
id, ") followed by add_block(<type>, <args>, id = \"", id,
"\") with the corrected arguments."
)
)
}
if (id %in% cur$blocks$rm) {
stage_abort(
"modify_block", id,
"id is staged for removal; mod has no effect"
)
}
new <- cur
if (id %in% names(cur$blocks$mod)) {
new$blocks$mod[[id]] <- merge_args(cur$blocks$mod[[id]], delta)
} else {
new$blocks$mod <- c(
new$blocks$mod,
set_names(list(delta), id)
)
}
commit_pending(pending, isolate(board$board), new, "modify_block", id)
}Two structural notes:
- The type of
pending$blocks$moddiverges from Phase 3’s typedblocks(...)object. Phase 4 stores it as a named list of deltas (each a named list of args), matching the post-#175 payload shape. The validator incommit_pendingruns against this new shape — which requires the matching change in core (#175) to land before the test suite can pass end-to-end. - The
merge_argshelper is named-overwrite:merge_args(d1, d2)returns a list whose keys are the union, with values fromd2winning on conflict.
stage_stack_mod and stage_link_mod follow
the same template with their entity-specific slot names and
conflict-table guards. All three mod stagers have identical body shape;
only the entity key differs (blocks, stacks,
links).
Extension server diff
asst_ext_srv <- function(system_prompt, messages) {
function(id, board, update, ...) {
moduleServer(
id,
function(input, output, session) {
chat_ctor <- isolate(
get_board_option_value("llm_model", session)
)
sys_prompt <- coal(system_prompt, default_system_prompt())
client <- chat_ctor(system_prompt = sys_prompt)
pending_update <- reactiveVal(empty_pending())
register_read_tools(client, board, update, session)
register_mutation_tools( # new
client, board, pending_update, session
)
if (length(messages)) {
client$set_turns(
lapply(messages, ellmer::contents_replay)
)
}
mod <- shinychat::chat_mod_server("chat", client)
observeEvent(
mod$last_input(),
{
reset_pending(pending_update)
record_new_turns()
},
ignoreNULL = TRUE
)
observeEvent(
mod$last_turn(),
{
flush_pending(pending_update, update)
record_new_turns()
},
ignoreNULL = TRUE
)
list(
state = list(
system_prompt = sys_prompt,
messages = messages
)
)
}
)
}
}No second reactiveVal beyond Phase 3’s pending_update.
The extension carries exactly one piece of turn-local state for staging,
mirroring Phase 3 unchanged.
Files added / changed
-
R/tools-mutation.R(new) — ninetool_*factories, theregister_mutation_tools()helper,existing_ids(),merge_args(),compact(). -
R/staging.R— refactorstage_block_mod,stage_stack_modandstage_link_modto take a delta (instead of a full block / stack / link). Updateempty_pending()so the threemodslots are plainlist()(named lists of deltas) instead of Phase 3’s typedblocks()/links()/stacks()— the typed slots no longer fit the delta shape. -
R/extension.R— callregister_mutation_tools()fromasst_ext_srv. No new reactiveVal. -
tests/testthat/test-tools-mutation.R(new) — per-tool happy path; per-tool error path (construction failure on adds, conflict-table rejects); ID generation (model-supplied, omitted, collision). -
tests/testthat/test-staging.R— extend with the new delta shape forstage_block_mod/stage_stack_mod/stage_link_mod; remove the Phase 3 tests that validate the full-object mod shape. -
tests/testthat/test-extension.R— end-to-end turn-boundary test asserting oneupdate(...)per turn carrying the expected shape for a multi-tool turn (add, link, mod). -
inst/examples/empty-board/(new) — minimal demo app exercising the full surface. -
DESCRIPTION— bumpRemotes:to pinblockr.coreto the branch carrying the #175 fix; unpinning at release time. AddjsonlitetoImports:(used byadd_blockandmodify_blocktool bodies to parse the JSON-shapedargsparameter; the other tools take typed top-level args and do not need it).jsonliteis already loaded transitively viaellmer, but the explicit declaration documents the direct use.
No new exports. The mutation tools are internal to the extension’s
server scope, accessed only via
register_mutation_tools.
Acceptance criteria
Automated (CI / devtools::check())
The end-to-end staging / flush assertions below are gated on the
blockr.core change in issue
175. Until that lands, the tests pin blockr.core via
Remotes: to the branch carrying the delta-shape
mod dispatch; CI tracks that branch.
- Per-tool happy path: each of the nine tools, called against a
synthetic board fixture, stages the expected entry into
pending_updateand returns the expected result string. - Per-tool error path: at least one error case per tool, asserting the
returned string starts with
"<tool> failed: ". Coverage includes construction failure (missing required arg onadd_*), conflict-table rejects (duplicateadd,add → mod, anything on a staged-rm id), and unknown id forrm/mod. - ID generation: explicit valid id → used as-is; explicit colliding id
→ rejected via core’s validator; omitted id →
rand_namesgenerates a non-colliding id and the tool result echoes it. - Conflict-table coverage: one test per collapse row asserting the
post-stage
pending_updatestate; one test per reject row asserting the error string and that no state changed. -
flush_pendingtest cases from Phase 3 continue to pass against the new payload shape (delta-mods). -
shiny::testServer()end-to-end (scripted sequences invoke tool functions directly viaclient$get_tools(), simulating whatellmer’s dispatch loop would do on the model’s behalf):- A turn with
add_block,add_link,add_stackflushes exactly oneupdate(...)carrying all three. - A turn with
add_block(foo, ...)thenmodify_block(foo, ...)returns a failure string for the modify, and the flushedupdate(...)carries only the original add (no mod entry forfoo). - The recovery sequence flushes correctly: a turn scripted as
add_block(foo, type, args1)→modify_block(foo, args2)(fails) →remove_block(foo)(collapses with pending add to a no-op) →add_block(foo, type, args3)flushes exactly oneupdate(...)carrying a single add forfoowithargs3and no rm. - Two
last_turnfirings without intervening stages produce zeroupdate(...)calls.
- A turn with
- Phase 1, 2, 3 acceptance criteria continue to pass.
-
devtools::check()passes 0/0/0.
Manual (demo app, live LLM)
A new example app at inst/examples/empty-board/: empty
board, a single text input for the user prompt, no pre-loaded state.
Used to smoke-test the full surface end-to-end against a real
provider.
Scenarios to verify by hand:
-
Build a pipeline. “Load the
irisdataset, drop the species column, then plot sepal length vs. width.” Expected: at turn end the board carries 3 blocks (e.g.dataset_block,subset_block,scatter_block), 2 links connecting them, and a 1-message chat transcript reporting each staged operation. No console errors. -
Modify in place. Starting from the pipeline above: “change
the dataset to
mtcars.” Expected:modify_blockroutes through core’s ctrl path if the dataset arg is ctrl-able, or an atomic re-setup otherwise. Downstream blocks re-evaluate with the new data; the chat reports the staged modify only. -
Id-change request from the user. “Rename
datasettodata_source.” Expected: the assistant declines an id change on the committed block, explains it can offerremove_block + add_block(with the trade-off that the block’s eval state and outputs are torn down and re-evaluated), and asks the user whether to proceed. -
Recover from a wrong arg. “Add a head block with 5 rows.”
(model picks the wrong arg name). “Sorry, use
nnotrows.” Expected: the model’s firstmodify_blockreturns theis staged for creation this turnerror; the model recovers by callingremove_blockfollowed byadd_blockwith the corrected args, and the flushed payload at turn end carries exactly one add with the corrected arg.
Manual checks are documentation, not gating — they verify the design holds in a real assistant loop and are recorded in the PR description.
Known limitations carried into later phases
-
Reads remain committed-only. No same-turn
read-after-write. The model relies on its tool-call history for what it
staged. Phase 5’s prompt-context layer or a future
list_pending_changes()tool can add explicit visibility if empirical usage shows the need. -
Stage-time mod validation is shape-only.
Substantive validation of a delta (valid arg names, type compatibility)
happens at flush via core’s validator chain, not at stage time. A typo’d
arg name in
modify_blockflushes and rejects at turn end. The user sees the standard Shiny notification; the model hears about it only via the next turn’s user prompt (or via Phase 5’s prompt-context layer once it lands). -
add → modis a reject, not a collapse. Phase 3’s lenient in-turn self-correction does not extend to changing a staged add’s args. The model has to issueremove_block + add_blockwith corrected args. Cost is bounded (extra tokens in same-turn self-correction); benefit is no recipe cache or second reactiveVal in the extension. If empirical use shows the model has trouble with the recovery pattern, a future phase can reintroduce the collapse behind a sidecar recipe cache. -
add_block/modify_blockargsare JSON-formatted strings, not native typed objects. ellmer’stype_objectrequires a closed key list, and the only escape hatch (.additional_properties = TRUE) is deprecated and supported only by Claude. JSON-string is the portable workaround. Trade-off: the model must format args as a JSON string rather than emitting a native object, and the tool body parses withjsonlite::fromJSON. The clean upgrade path — per-block-type tool generation backed by registry type info — is tracked in #12. -
Stack subclass ctor args are unreachable from the
assistant.
add_stack(blocks, name, id)andmodify_stack(id, blocks, name)expose only the baseblockr.core::new_stackargs, so e.g. thecolorattribute onblockr.dock::dock_stackcannot be set or modified through the assistant — it falls back to the auto-promoter’s default at apply time. Same architectural cause as #12 but applied to stacks; tracked separately in #13. Links face the same gap if subclasses are ever introduced (none today, so no urgency). -
Pinned upstream
Remotes:. Until the matching changes inblockr.coreandblockr.dockare released,DESCRIPTIONpins both viaRemotes:to the PR branches:blockr.core#176(delta-shapemodpayload +update_link/update_stackgenerics) andblockr.dock#133(stacked on#132, which fixes the two dock-side observer issues#131and#130surfaced during Phase 4 validation). Live end-to-end testing against Claude confirmed the pinned versions behave correctly:add_block/add_link/add_stackbuild pipelines, andmodify_blockagainst ctrl-able args updates the board in place without dock observer errors. Unpin at release time. -
Stage-time link validator and apply-time preprocess disagree
on dangling links (blockr.core). When the model removes a block
whose existing links are still referenced elsewhere on the board, then
tries to add a new link, the stage-time
validate_board_update_xrefsrejects with"Expecting all links to refer to known block IDs."— even thoughpreprocess_board_updatewould auto-clean the orphans at apply time. The model has to explicitlyremove_linkthe dangling links before adding new ones. Tracked atblockr.core#177. Workaround on the assistant side could be to mirror preprocess’s orphan-cleanup instage_block_rm; for now we prefer the upstream fix so behaviour stays single-source. -
External-control writes still go through
update(). This is the design’s bet on blockr.core#175. If core resolves the issue with a less-unified approach (e.g. ctrl writes still bypassupdate()and consumers must route), Phase 4 will need a carve-out inmodify_blockto route the ctrl-eligible subset directly. Tracked. - Atomic flush has no partial-success fallback. Inherited from Phase 3 unchanged: a racing user edit that invalidates the payload at dispatch time discards the whole turn’s mutations.
- No snapshot / undo. Inherited from Phase 3 / roadmap.