Live: session step
live_session_stepRun one perceive-decide-act-observe cycle for live SVG editing. Perceive the current scene, optionally apply styles or insert content, and return the updated frame and diff.
Instructions
Run ONE perceive→decide→act→observe iteration of the live-view loop.
When to use: the flagship loop step — call it repeatedly to drive a live edit loop (use
live_wait_for_change between steps to react to the user's edits). It COMPOSES the existing
live tools (ADR-006); for a single standalone edit call live_apply_to_selection /
live_insert_svg / live_set_selected_text directly. Each call is one bounded iteration — no
server-side autonomous run.
Key params: action is the AGENT's decision (this tool embeds no LLM), one of the FIXED set
apply | insert_svg | set_text (no raw-Action/code path — ADR-002/003; an out-of-enum
action is rejected). OMIT action for a PERCEIVE-ONLY step (mutates nothing, no Operation
Record). When acting: apply takes fill/stroke/stroke_width/opacity and/or
dx/dy/scale/rotate; insert_svg takes a safe-parsed svg_fragment; set_text takes a
control-char-checked text. The act runs through run_live_mutation (the SAME path as the
standalone tools); mutating a running session is HIGH risk and REQUIRES an explicit
approval_token. Requires a session.
Return shape: LiveSessionStepResult — always the PERCEIVE scene + frame; after an act also the
operation_id, a focused live_diff_view artifact, and the after scene/frame.
Example: live_session_step(action="apply", approval_token="ok", fill="#3366cc")
Risk class: high when it acts (routes through run_live_mutation — HIGH + approval); low when
perceive-only (read-only; no mutation, no Operation Record).
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| dx | No | ||
| dy | No | ||
| fill | No | ||
| text | No | ||
| scale | No | ||
| action | No | ||
| rotate | No | ||
| stroke | No | ||
| opacity | No | ||
| stroke_width | No | ||
| svg_fragment | No | ||
| approval_token | No |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| diff | No | Focused before/after diff linked to the record (act steps only). | |
| edit | No | The mutation outcome (null when perceive-only). | |
| acted | Yes | Whether a semantic act was performed this step. | |
| action | No | The semantic act performed, or null on a perceive-only step. | |
| after_frame | No | Canvas frame captured after the act (null when perceive-only). | |
| after_scene | No | Structured scene captured AFTER the act (null when perceive-only). | |
| before_frame | Yes | Canvas frame captured before acting. | |
| before_scene | Yes | Structured scene captured BEFORE deciding/acting. | |
| operation_id | No | Live Operation Record id of the act (null when perceive-only). |