Extract plan-authored Durable retry execution

[Tsuyoshi Ushio (TsuyoshiUshio)]

Summary

Extract the plan-authored Durable native retry execution foundation from #185 as an independently usable slice.

• Adds bounded execution.retry authoring for tool and Sub Agent tasks.
• Freezes the effective policy into orchestration input for replay-safe dispatch.
• Maps persisted policies to Durable RetryPolicy for static, dynamic, and fan-out scheduling.
• Adds policy-aware Activity envelopes, runtime-owned failure classification, stable idempotency context, and sanitized exhaustion errors.
• Preserves policy-free legacy histories and their existing Activity/result envelopes.
• Preserves latest-main DTS display tags on orchestration start and policy-free/retry-aware tool and Sub Agent Activity calls.
• Adds a plan-authored retry sample plus a real Functions-host E2E.
• Updates finalized FRD 0004 to record the approved delivery split and replay-safety decisions.

This is the execution-foundation extraction from #185. PR #185 remains open and its remote branch is unchanged. After this PR merges, #185 will be rebased and reduced to retain only the @workflow_tool(retry=...) authoring/discovery/catalog integration.

Scope boundary

This PR intentionally does not add a retry argument or retry metadata to @workflow_tool, propagate retry through discovery/registry/catalog paths, or implement decorator-over-plan precedence.

Upstream dependency

durabletask 1.10.0 drops Activity tags when reconstructing a schedule after a native retry timer. The initial attempt keeps durabletask.displayName, but retry attempts currently fall back to the registered Activity function name in DTS.

• Azure-side tracking: Track upstream fix for Activity tags lost on retry #204
• Upstream fix: microsoft/durabletask-python#263

The runtime supplies tags correctly on the initial retry-aware Activity schedule. Consuming a future durabletask release containing the upstream fix is tracked separately and is not worked around in this PR.

Validation

• python -m ruff check src tests
• python -m mypy src — 44 source files clean
• python -m pytest --cache-clear --cov=./src/azure_functions_agents --cov-report=xml --cov-branch tests — 1166 passed, 55 deselected
• python -m pytest -q -m e2e tests/endtoend/test_workflow_native_retry_e2e.py — 2 passed in 25.31s against a real Functions host and Azurite, using task hub prstatusreports

For the Windows host run, the sample was installed into its ignored .python_packages/lib/site-packages directory to match CI's packaged-dependency layout and avoid duplicate native gRPC loading. No machine-specific settings or package artifacts are committed.

NOTE

I found the tag label issue when we had a retry. I created the upstream fix on durabletask-python.

[Copilot]

🟡 Changes recommended

The E2E exhaustion assertion can pass from earlier cumulative logs, and several finalized retry-contract descriptions do not match the implementation.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

Pull request overview

Adds plan-authored Durable retry execution while preserving replay compatibility for policy-free workflows.

Changes:

• Adds bounded retry policies, failure classification, and idempotency context.
• Integrates native retry across static, dynamic, fan-out, tool, and Sub Agent execution.
• Adds tests, a runnable sample, and architecture/user documentation.

File summaries

File	Description
src/azure_functions_agents/workflows/schema.py	Defines retry policies and persisted execution contracts.
src/azure_functions_agents/workflows/activity.py	Implements policy-aware Activity execution and outcomes.
src/azure_functions_agents/workflows/native_retry.py	Maps policies and handles retry failures.
src/azure_functions_agents/workflows/engine.py	Dispatches Activities with persisted retry policies.
src/azure_functions_agents/workflows/context.py	Adds task context and idempotency keys.
src/azure_functions_agents/workflows/tools.py	Exposes retry authoring and freezes policies.
src/azure_functions_agents/__init__.py	Exports the new public API.
tests/test_workflow_native_retry.py	Covers retry contracts and scheduling.
tests/test_workflow_engine.py	Covers policy-aware Sub Agent execution.
tests/test_workflow_registry.py	Adapts registry tests for async Activities.
tests/test_workflow_retry_policy_sample.py	Validates the sample contract.
tests/test_package_imports.py	Verifies public exports.
tests/endtoend/test_workflow_native_retry_e2e.py	Exercises retry with a real Functions host.
samples/workflow-retry-policy/src/tools/order_tools.py	Implements the transient-failure sample tools.
samples/workflow-retry-policy/src/main.agent.md	Instructs plan-authored retry.
samples/workflow-retry-policy/src/function_app.py	Creates the sample app.
samples/workflow-retry-policy/src/requirements.txt	Installs the local runtime package.
samples/workflow-retry-policy/src/host.json	Configures the Functions host.
samples/workflow-retry-policy/src/local.settings.template.json	Provides local settings.
samples/workflow-retry-policy/src/.funcignore	Configures sample packaging exclusions.
samples/workflow-retry-policy/README.md	Documents the sample.
samples/README.md	Lists the new sample.
README.md	Documents retry authoring and the sample.
docs/workflows.md	Documents the retry contract.
docs/frds/0004-dynamic-workflows.md	Records design and delivery decisions.
docs/architecture.md	Updates the workflow module map.

Review details

Suppressed comments (2)

docs/frds/0004-dynamic-workflows.md:177

• These are not the authored field names implemented by this PR. The limits apply to the nested backoff.initial, backoff.multiplier, and backoff.max fields.

`first_interval`, `backoff_coefficient`, and `max_interval` have fixed limits,

docs/frds/0004-dynamic-workflows.md:1272

• The idempotency key is not persisted at submission; invoke_policy_handler derives it when the Activity starts from the persisted workflow ID and node-instance ID. This test-plan item should describe the actual invariant.

  - persist the effective policy and stable idempotency key at submission;

• Files reviewed: 26/26 changed files
• Comments generated: 5
• Review effort level: Balanced

---

💡 Configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Laveesh Rohra (larohra)]

Approved with non-blocking suggestions for alignment with the Python source conventions on feature/aca-sandboxes. These are NITs/low-priority follow-ups rather than merge requirements.

[Tsuyoshi Ushio (TsuyoshiUshio)]

Laveesh Rohra (@larohra) Thank you for the detailed standards-alignment review.

I addressed the three correctness/security items in commit 1edce829:

• plan-schema validation errors no longer reflect caller-authored input values;
• retry marker JSON rejects duplicate keys at every object level;
• the E2E assertion inspects each nested failure message directly and requires the decoded terminal failure to have no innerFailure.

The remaining non-blocking refactoring and documentation suggestions are tracked in #205 so they can be handled as a focused follow-up without expanding this already large PR. That issue covers Pydantic outcome boundary models, a StrEnum for failure kinds, source/test basename alignment, concise source docstrings, and applying the newer minimal-decisions guidance prospectively while preserving the existing append-only FRD history.

The full gate passes (1174 passed, 55 deselected), and the real Functions Host sample E2E passes both scenarios with no skips.