Summary

• regression fix: uipath debug with llamaindex workflows fails with ContextStateError
• uipath run is unaffected (breakpoint injection is skipped)

the error

WorkflowFailedEvent
├── exception_type: workflows.errors.ContextStateError
├── exception_message: wait_for_event is only available from within step functions.

root cause

the breakpoint wrapper calls ctx.wait_for_event() to pause a step before execution. this requires a Context in InternalContext state (the per-step context the framework creates).

the old code read self.context from the workflow instance, which was the ExternalContext set by the runtime at _run_workflow() time:

# old (broken)
ctx: Context | None = getattr(self, "context", None)
await ctx.wait_for_event(...)  # ExternalContext -> ContextStateError

the fix

create an InternalContext via Context._create_internal(workflow=self) inside the wrapper. this works because the wrapper executes inside the step worker where StepWorkerStateContextVar is already set:

# new
ctx = Context._create_internal(workflow=self)
await ctx.wait_for_event(...)  # InternalContext -> works

note: _create_internal is a private API on the workflows library. there is currently no public way to obtain an InternalContext from within a step wrapper that doesn't declare ctx: Context in its signature. this is a workaround until [llama-index/llama_index_workflows#TBD] provides a public API. see the issue linked below.

other changes

• removed DebuggableWorkflow protocol and the runtime code that set debug_workflow.context (no longer needed)
• bumped uipath-llamaindex to 0.5.9
• added pexpect-based integration test (testcases/debug-breakpoints) covering single/multiple breakpoints, step mode, and quit

Why

breakpoints are a core part of the uipath debug experience. this regression made debug mode unusable for all llamaindex workflow agents.

Llamaindex opened issue: run-llama/llama-agents#505