blender: exec command (author-time bpy code) + per-frame progress on the builtin transport #692

Why

People are pairing Blender with Claude/Codex to make building animations: construction sequences, fly-throughs, sun studies, exploded views. The blender agent already renders headlessly (IFC → still/turntable), but only through five fixed recipes. FloLess users want to ask in chat for an animation of their model. The terminal AI should author the bpy code once at .flo authoring time, and AWARE should run that exact code deterministically on every run. That is the same model tekla/exec, rhino-8 exec, revit-2026 exec and sketchup-2026 exec already follow.

Long renders (minutes to hours) must also report progress. Otherwise the caller cannot tell a 40-minute animation from a hang.

Scope

1. blender/exec: author-time bpy code, run headless

• New command in 20-agents/aeco/visualization/blender/manifest.yaml: lifecycle: single, mode: write, mode-overridable: true.
• Inputs:
  • code (string, required): Python source defining run(ctx).
  • args (object, optional).
  • ifc-path | blend-path (optional, mutually exclusive): the scene to start from. An IFC is staged through the existing _stage/_ifc_import so IFC class/material/storey/GUID custom props are present.
  • preset (optional look, same enum as scene.apply-look).
  • output-dir (string): where the code may write.
  • timeout-seconds.
• A fixed scripts/exec.py wrapper puts scripts/ on sys.path, optionally stages the scene, then calls run(ctx). ctx exposes:
  • ctx.args and ctx.output_dir.
  • Helpers: ctx.frame_model(direction) (_framing), ctx.apply_look(preset), ctx.elements() (objects with IFC props), ctx.progress(phase, done, total, message).
  • ctx.render_still(path) / ctx.render_animation(path). These set up output and report frames automatically.
• The return value of run(ctx) is JSON-framed back through _result (<<<AWARE_RESULT>>>).
• Errors:
  • A Python exception becomes {ok:false, code:"exec-error", message, traceback}, a clean error rather than a missing frame.
  • A syntax error is reported as such.
• Determinism: code is inline in the app source, so it is covered by the lock source-hash (app_lock.rs). No external code file is allowed.
• dry_run_result branch, default_timeout_seconds (render-class: 1800 s), and an invoker.rs dispatch entry.

2. Progress for the builtin Blender transport (#405 parity)

• Today node-progress (feat(runtime): progressive large-geometry delivery for first render #405, runtime/progress.rs) is relayed only for the CLI transport. BuiltinInvoker never sets AWARE_PROGRESS_FILE, so Blender never reports.
• Wire relay_progress into the builtin Blender path: set AWARE_PROGRESS_FILE on the spawned blender process and relay its records into node-progress events.
• Add scripts/_progress.py, which appends {"$aware-progress":{"phase","done","total","message"}} lines.
• Register a render_post / frame_change_post handler during animation renders so every frame reports done/total with no author effort. Use it in render.turntable too, and emit stage phases (import, look, render, encode) from scene.import/render.*.
• aware agent invoke (builtin): when the caller sets AWARE_PROGRESS_FILE, honour it. FloLess's Render card calls agent invoke directly and can then tail frames too.

3. Skill + example

• skills/exec-bpy.md: the ctx contract, recipes (construction sequence by storey or erection order using keyframed visibility, camera fly-through on a path, sun study via sun-position animation, exploded view, highlight changed GUIDs), and gotchas (EEVEE for animations, the 5.x media_type gate, layered actions).
• 30-apps/_examples/model-to-construction-sequence.app with a safety: block (cf. model-to-renders.app ships four write-mode blender nodes with no safety: block — invalid the moment blender is installed #613).
• Tests: Python suite (tests/) for the wrapper (exception framing, progress records, frame handler), plus Rust tests for dispatch, dry-run and progress relay on the builtin path. Bump the agent to 0.2.0 and reindex.

Out of scope

Live/interactive Blender control (an MCP server). It is non-deterministic and needs a person at the desktop.

Acceptance

• aware app run on the example app, against a real IFC, produces an MP4. The run log JSONL contains node-progress records with done increasing to total (= frame count) during the render, not only at the end.
• A bpy exception in code gives a clean exec-error with the traceback.
• cargo fmt/clippy -D warnings/test and the Python agent suites are green.

Cross-ref: #405 (progress), #613 (write-node safety), #314. FloLess side: pawellisowski/floless.app (epic linked below).