Python: HITL respond-URL addressing from inside workflows

[ahmedmuhsin]

Motivation & Context

The durable function HITL flow pauses a workflow with request_info and waits for a human to POST a response to the /respond endpoint. The gap was that nothing inside the workflow could build that respond URL. An executor only receives its message payload, not the orchestration instanceId, and the requestId does not exist until request_info runs. So to email someone an approval link you had to pull both ids from the HTTP run response or poll the status endpoint from outside the app.

This came out of a real POC where someone wanted Agent B to email a reviewer when it finished, then resume to Agent C once approved, but had no way to address the running workflow from within it. This change lets a workflow build its own respond URL and notify a human from inside the graph with no caller plumbing of instanceId or requestId, and it works for nested sub workflows too.

Description & Review Guide

• What are the major changes?

  • The orchestrator now surfaces orchestration metadata (the addressable root instanceId, the workflow name, and for nested workflows the request path prefix) onto each executor through the durable runner context. There is no new core API.
  • A new WorkflowHitlContext helper in agent-framework-azurefunctions builds the canonical respond and status URLs from that metadata. It returns None in process so the same executor degrades gracefully when it is not on the durable host.
  • WorkflowHitlContext.pending_request_id(ctx) reads the id request_info just generated back off the context, so the user never mints an id by hand. It works on any host through the existing core runner context protocol.
  • For nested sub workflows the address context propagates down call_sub_orchestrator via a new SUBWORKFLOW_ADDRESS_KEY marker, so an executor at any depth builds a URL that targets the top level instance with a qualified request id. That marker is stripped from untrusted input alongside the existing input marker, so a top level caller cannot forge it.
  • Samples 12 and 13 show the two step pattern. The review executor reads the request id back and sends it to a downstream notify executor that builds the URL, so a retried activity never emails a dead link because only the committed attempt reaches the notifier.

• What is the impact of these changes?

  • Additive. No core change, nothing public removed, and top level behavior is unchanged when the helper is not used.
  • New unit tests cover the metadata round trip, the id read back, the nested ordinal and prefix agreement with the read side, marker stripping, and URL building. Integration tests assert that the URL the helper builds equals the server respondUrl and that posting to it resumes the run, for both the flat (12) and nested (13) samples.

• What do you want reviewers to focus on?

  • The per executor ordinal used to build the nested prefix at dispatch has to match the enumerate index the status and respond endpoints use when they resolve a nested request. That agreement is the one spot where a mistake would send an emailed URL to the wrong child or a 404.

Related Issue

No separate issue. This is stacked on feature/python-durabletask-subworkflows-multiworkflow and targets it directly so the diff stays scoped to the HITL notify work.

Contribution Checklist

• The code builds clean without any errors or warnings
• All unit tests pass, and I have added new tests where possible
• The PR follows the Contribution Guidelines
• This PR is linked to an issue and there is no other open PR for this issue (see Related Issue above).
• This is not a breaking change. If it is a breaking change, add the breaking change label (or add "[BREAKING]" to the title prefix, before or after any language prefix) — a workflow keeps the label and title prefix in sync automatically.

[ahmedmuhsin]

Superseded by microsoft#7001, which targets main directly now that the sub-workflow / multi-workflow base work has merged (microsoft#6696). Rebased onto main with the same three HITL commits.