feat(functions): expose sub-orchestration tags

[wangbill (YunchuWang)]

Summary

What changed?

• Added a public SubOrchestrationOptions type with instanceId, version, and tags.
• Added options-object overloads for callSubOrchestrator() and
  callSubOrchestratorWithRetry() while retaining the existing positional overloads.
• Snapshotted tags at the facade boundary and verified that core retry reconstruction preserves
  the original tag values.
• Added a real Functions Host E2E that starts a tagged child orchestration and reads its persisted
  tags through the Durable client after completion.

Why is this change needed?

• The core SDK already supports tagged sub-orchestration actions, but the
  azure-functions-durable facade had no public path for supplying those tags.
• This brings the facade in line with the .NET SDK without changing protobufs, backend behavior, or
  existing positional calls.

Issues / work items

• Resolves: N/A
• Related: N/A

---

Project checklist

• Release notes are not required for the next release
  • Otherwise: Notes added to CHANGELOG.md
• Backport is not required
  • Otherwise: Backport tracked by issue/PR #issue_or_pr
• All required tests have been added/updated (unit tests, E2E tests)
• Breaking change?
  • If yes:
    • Impact:
    • Migration guidance:

---

AI-assisted code disclosure (required)

Was an AI tool used? (select one)

• No
• Yes, AI helped write parts of this PR (e.g., GitHub Copilot)
• Yes, an AI agent generated most of this PR

If AI was used:

• Tool(s): GitHub Copilot
• AI-assisted areas/files: Facade overloads and exported type, changelog entry, and protobuf replay
  unit tests, plus the Functions Host E2E app route and Jest coverage.
• What you changed after AI output: Assertions were aligned with the generated protobuf map shape,
  unrelated formatting churn was removed, and the real provider path was validated locally.

AI verification (required if AI was used):

• I understand the code and can explain it
• I verified referenced APIs/types exist and are correct
• I reviewed edge cases/failure paths (timeouts, retries, cancellation, exceptions)
• I reviewed concurrency/async behavior
• I checked for unintended breaking or behavior changes

---

Testing

Automated tests

• Result: Passed locally and in hosted CI.
• RED (expected): npm test -w durable-functions -- --runTestsByPath test/unit/worker.spec.ts
  failed on the missing public SubOrchestrationOptions export and object overloads before the
  production change.
• GREEN: npm test -w durable-functions -- --runTestsByPath test/unit/orchestration-context.spec.ts test/unit/worker.spec.ts (40 passed).
• Core tag/retry coverage: npm test -w @microsoft/durabletask-js -- --runTestsByPath test/orchestration_executor.spec.ts --testNamePattern "include tags on scheduled sub-orchestration actions|handle sub-orchestration retry with handler" (2 passed, 90 skipped).
• Build/declarations: npm run build -w durable-functions.
• Declaration consumer smoke: emitted declarations compiled old positional calls and new
  options-object calls with npx tsc --noEmit --strict --target ES2022 --module commonjs --moduleResolution node --esModuleInterop --skipLibCheck.
• Lint: npx eslint packages\azure-functions-durable\src\orchestration-context.ts packages\azure-functions-durable\src\index.ts packages\azure-functions-durable\test\unit\worker.spec.ts.
• Formatting/patch hygiene: production files passed scoped Prettier; git diff --check passed.
  The worker test and changelog retain their existing full-file Prettier debt in both origin/main
  and this branch rather than introducing unrelated reformatting.
• Functions Host RED against detached origin/main (expected): npm run test:e2e:functions:internal -- --runTestsByPath test/e2e-functions/sub-orchestration-tags.spec.ts launched the real host and failed, non-skipped,
  after the parent remained Running for 60 seconds because the old positional facade interpreted
  the options object as the child instance ID.
• Functions Host GREEN on this branch: the same focused command passed 1 test with 0 skipped. The
  test used the in-repo packages, real func start, Preview extension bundle, and Azurite-backed
  AzureStorage provider, then asserted the child metadata contained exactly
  { environment: "functions-e2e", empty: "" }.
• E2E builds: npm run build -w durable-functions and npm run build --prefix test\e2e-functions\test-app passed.
• E2E lint/format: scoped ESLint passed for the new spec and test-app function (including the
  normally ignored app file explicitly); scoped Prettier passed for all three E2E files.
• Hosted Functions E2E: functions-e2e (node 22.x) passed on commit
  7f31612815774d0b50c13ec56fea291ed5276883. Its log reports
  PASS test/e2e-functions/sub-orchestration-tags.spec.ts, 15/15 suites passed, and 43 tests
  passed. The new file contains one ordinary (non-skipped) test.
• All hosted PR checks passed, including lint/unit, CodeQL, Functions E2E, DTS E2E, general E2E,
  samples, build, and CLA.

Manual validation (only if runtime/behavior changed)

• Environment (OS, Node.js version, components): Windows; Node.js 24.14.0; Azure Functions Core
  Tools; Preview extension bundle [4.29.0, 5.0.0); Azurite/AzureStorage provider.
• Steps + observed results:
  1. Started the existing test app through the shared func start harness with in-repo
     durable-functions and core packages.
  2. Started a parent over HTTP; it scheduled a child with a fixed unique instance ID and two
     explicit tags, including an empty-string value.
  3. Waited for parent and child completion without arbitrary sleeps, queried the child through a
     test-only HTTP endpoint backed by the real Durable client, and observed the exact persisted tag
     map.
• Evidence (optional): Focused local real-host E2E passed. This validates the Preview extension and
  AzureStorage/Azurite provider path, not the Azure Durable Task Scheduler service.

---

Notes for reviewers

• .NET parity is pinned to
  TaskOrchestrationContextWrapper.cs at 8f1b135,
  which forwards options.Tags for retry and non-retry sub-orchestration paths.
• The corresponding
  SubOrchestrationOptions test
  pins tags alongside instance ID, version, and retry configuration.
• The full local Functions E2E suite was not run; the exact new spec was run against both
  origin/main (expected RED) and this branch (GREEN). The hosted full Functions E2E suite passed.

[Copilot]

Copilot review overview

🟡 Changes recommended

The options discriminator dereferences null, breaking previously tolerated positional JavaScript calls.

Review effort: Balanced
Findings: 1

Open (1)

• Guard null options to preserve positional call compatibility · New

What changed in this PR

Exposes tagged sub-orchestration scheduling through the Azure Functions facade while preserving positional overloads.

Changes:

• Adds and exports SubOrchestrationOptions.
• Adds options-object overloads with tag snapshotting.
• Tests initial and retried tag propagation.

File	Description
src/​orchestration-context.ts	Adds options normalization and overloads.
src/​index.ts	Exports the new options type.
test/​unit/​worker.spec.ts	Tests tag forwarding and retries.
CHANGELOG.md	Documents the API addition.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.