Skip to content

workflow_builder_interactive.md

Latest commit

 

History

History
259 lines (184 loc) · 8.45 KB

workflow_builder_interactive.md

File metadata and controls

259 lines (184 loc) · 8.45 KB
Raw

Interactive Workflow Builder

This doc explains how the interactive workflow builder works now.

This is the chat-driven builder experience used from the workflow canvas. Internally it is the workflow_phase path with phase_id = workflow-builder.

What It Is

The interactive builder is not the same thing as normal workflow execution.

  • normal execution uses agent_mode = workflow
  • builder chat uses agent_mode = workflow_phase
  • the builder gets a phase-specific system prompt, a restricted tool set, and builder-specific run-folder behavior

The main code paths are:

Request Shape

From the frontend, builder chat is sent as:

  • agent_mode = workflow_phase
  • phase_id = workflow-builder
  • preset_query_id = <workflow preset>

The server then:

  • resolves the workflow manifest
  • loads phase LLM settings from the manifest when available
  • converts the request onto the standard chat agent path
  • overrides the system prompt for the builder phase
  • registers builder/workshop tools
  • applies a per-turn tool allow list based on workshop mode

This is handled in server.go.

Core Mental Model

The interactive builder is a persistent chat session that can:

  • inspect the current workflow plan
  • modify plan structure
  • modify step configuration
  • manage groups, workflow config, schedules, and related artifacts
  • run single steps in the background
  • run the full workflow in the background in the appropriate modes
  • inspect run results and logs

It is a design-and-operations surface, not just a prompt editor.

Workshop Modes

The builder has multiple workshop modes.

Current backend modes:

  • builder
  • optimizer
  • run
  • debugger
  • eval
  • output

The most important ones for normal workflow building are:

builder

Use this for designing and testing the workflow.

Allowed behavior:

  • add, update, and delete plan steps
  • update workflow config, variables, groups, schedules
  • run individual steps
  • inspect executions
  • patch scripts and files

optimizer

Use this after the basic workflow exists and needs hardening against run/eval/metric evidence.

Adds:

  • Pulse Bug Review/Fixer
  • debug_step
  • run_full_workflow
  • evaluation helpers
  • learning and step-hardening workflows

run

Use this when the workflow is already built and the user mainly wants operational execution, Slack/WhatsApp answers, or result inspection.

Allowed behavior is runtime-focused:

  • answer directly from workflow state, KB, learnings, db, and latest run artifacts
  • run normal steps
  • run orphan utility steps
  • run the full workflow
  • inspect executions

It is intentionally more operational and less structural.

Mode Detection

If the frontend does not explicitly force a workshop mode, the backend defaults to Builder.

Current rule:

  • default -> builder
  • optimizer, run, and reporting mode are explicit frontend/user choices or bot-route settings

This logic lives in interactive_workshop_manager.go.

Frontend override still wins when provided.

Tool Gating

The builder does not expose all tools all the time.

Current behavior:

  • the server registers a broad set of workshop-capable tools
  • then applies a workshop-mode allow list
  • the allow list is recomputed based on the current workshop mode

This is how the product enforces boundaries like:

  • builder can modify the plan
  • run mode can execute user-facing work, normal steps, orphan utility steps, and full workflows
  • run mode can read KB/learnings/db/run artifacts, but cannot freely redesign the workflow
  • debugger is read-heavy

The tool allow-list logic is in interactive_workshop_manager.go.

Main Builder Tools

The interactive builder commonly uses:

  • execute_step
  • query_step
  • send_step_message
  • stop_step
  • stop_all_executions
  • list_executions
  • run_in_background
  • update_step_config
  • plan modification tools such as add_*, update_*, delete_*
  • update_workflow_config
  • update_variable, add_group, update_group, delete_group
  • schedule tools

Depending on mode, it may also expose:

  • run_saved_main_py
  • debug_step
  • run_full_workflow
  • run_full_evaluation
  • run_full_report
  • Pulse Bug Review/Fixer

Step Execution From Builder

The builder can execute steps directly from chat.

Key behavior:

  • execute_step(...) runs in background and returns an execution ID
  • query_step(...) is used to inspect progress and live tool calls
  • send_step_message(execution_id, message) steers the exact active child-agent turn without starting a second run. Coding CLIs receive live input; other agents queue it for the next safe turn boundary. It cannot resume completed work and may return no_active_agent during validation or script-only phases.
  • run_in_background(...) can spawn a side task with the same workspace access

In builder mode:

  • iteration is effectively pinned to iteration-0
  • any incoming builder run-folder selection is normalized to iteration-0 or iteration-0/<group>
  • every execution re-reads the latest plan and config state

This means builder testing always operates against the current mutable run, not an archived iteration.

Full Workflow Runs From Builder

In optimizer and run modes, the workshop agent can execute the entire workflow via run_full_workflow(...).

That is still a background workflow execution, not a special toy mode.

Important behavior:

  • it runs the real workflow controller path
  • it can require human_inputs if the workflow has human_input steps
  • it uses the current workflow plan and config from the workspace

Run Folder Behavior

Interactive builder mode is tightly coupled to iteration-0.

Current rule:

  • builder mode normalizes run-folder selection to iteration-0
  • if a group path is selected, it becomes iteration-0/<group>

This is why the builder always feels attached to the latest mutable run.

For the broader run-folder model, see iteration_run_folder_architecture.md.

Session Behavior

The builder uses a persistent per-session workshop chat session.

Current behavior:

  • the server reuses the workshop session for the same chat session when possible
  • refreshed manifest settings can be pushed back into the session
  • background step executions are tracked so the frontend can keep polling and showing status
  • stop-state checks are wired to avoid orphaned background processes

This is one reason builder chat behaves more like an operator console than a plain LLM chat.

Files And Persistence

The interactive builder writes and reads several kinds of state:

Plan and config state

  • planning/plan.json
  • planning/step_config.json
  • workflow.json
  • variables/group data

Builder chat artifacts

  • builder/conversation/YYYY-MM-DD/session-{sessionId}-conversation.json

Builder phase costs

  • costs/phase/token_usage.json
  • costs/phase/daily/YYYY-MM-DD.json

Execution artifacts from tested steps

  • runs/iteration-0/...

So the builder has both:

  • phase-level chat state and costs
  • execution-level run artifacts when it tests or runs workflow steps

Relationship To Other Modes

The same underlying workshop infrastructure also supports adjacent specialized phases:

  • eval
  • output
  • debugger

But the primary workflow-builder experience is still workflow-builder plus the builder/optimizer/run workshop modes.

Practical Summary

Use this mental model:

  • interactive builder = workflow_phase chat for workflow design and operation
  • it is sessionful, tool-driven, and workspace-backed
  • it auto-detects or accepts a workshop mode
  • tool access changes by mode
  • single-step testing happens through workshop execution tools
  • full runs are available in the more operational modes
  • builder run-folder context is centered on iteration-0

Related Docs