Many agent demos tell the story this way: the user says one sentence, and the software immediately moves.

That is good demo storytelling, but it is not good architecture. For a local agent harness that needs to be maintained, the more reliable path is to generate a bridge trace before calling SketchUp.

A bridge trace is the explicit operation plan before live execution. It lets the system answer “what am I going to do?” before it answers “what did I do?”

Trace separates planning from execution

In SAH, plan_project_execution derives a project-level bridge trace from the current design_model.json. This does not require live SketchUp.

The trace can include wall operations derived from space bounds, wall-with-opening operations from explicit walls and hosted openings, placement operations from component instances, component placement or fallback from lighting entries, and a final scene info query.

This is not just a dry run. It is a compilation step from project truth into an intermediate representation the host application can execute.

With that intermediate representation, the system can check before live execution:

  • whether any object cannot become an operation;
  • whether each operation has a stable id;
  • whether payloads are complete;
  • whether rollback behavior is explicit;
  • whether clean replay is required;
  • whether partial execution should be refused.

Headless planning helps developers

If every validation step requires opening SketchUp, development becomes slow and CI becomes difficult.

Bridge trace planning lets many problems be checked headlessly: whether initialization creates valid truth, whether truth can generate a complete execution trace, whether schema changes break trace generation, whether component metadata is sufficient for placement, and whether imported walls or openings can replay.

Live SketchUp integration remains necessary, but it should not carry all verification. A better strategy is: most logic headless, key host-application paths live.

Partial execution must not be silent

Suppose a project has 20 objects and 3 of them cannot be converted into bridge operations. The system could execute the other 17.

That may sound tolerant, but it is dangerous in a design tool.

The resulting scene may look successful while missing walls, lights, openings, or components. Screenshots, saves, and visual reviews would then be based on a false result.

SAH therefore treats silent partial execution as the wrong default. Unless the agent makes omitted objects explicit to the designer and intentionally continues, missing truth should not be packaged as success.

That is a product-quality boundary, not a minor error-handling detail.

Clean replay prevents stale geometry

Repeated execution creates another common failure mode.

If every run adds new generated objects to SketchUp without removing old generated geometry, the scene becomes contaminated. Visually, you see an accumulation, not the current truth.

Bridge trace plus clean replay helps: clean harness-managed layers or objects first, replay from the current design_model.json, widen the clean scope for import replay when required, and check for scene contamination after execution.

That is how visual review can inspect current truth rather than historical leftovers.

Operation id is the debugging coordinate

Each operation needs a stable id.

Without operation ids, failure becomes “SketchUp execution failed.” With operation ids, the system can say which placement failed, which wall was not generated, which opening had no valid host wall, which component fallback was used, and which rollback step failed.

For the agent, that information can become a next repair action. For developers, it becomes testable and debuggable evidence.

Feedback is not just logging

After trace execution, bridge results should not remain only in an execution report.

On success, entity ids and operation metadata need to be written back to design_model.json. On failure, error data should identify the operation and rollback state clearly enough to guide repair.

That lets the next agent call continue from current truth instead of guessing from the SketchUp scene.

A good agent harness lets execution feedback update state. It does not treat feedback as disposable console output.

Why this is not a tutorial yet

Bridge trace is an architecture concept, not merely a command. Concrete commands and examples should become tutorials only after they are verified against the current product repository.

This article fixes the developer mental model first: live host execution should not be the first inspectable object. The trace should be.

Without a trace or equivalent intermediate representation, local agent products become black boxes quickly. It becomes hard to separate what the LLM said, what the tool planned, and what the host application actually did.

Source trace