Hand off big one-time jobs from chat to a durable workflow

Summary

Part of #1543 (Phase 7). When a request is bigger than a chat plan can handle, the planner proposes a one-time durable workflow. Approve & run starts it, the plan ends, and Phase 6b posts the summary back into the chat.

User Value

"Review these 200 documents against our checklist" doesn't fit in a plan: 8 steps by default and 30 at most, 900 s per run by default, and no loops. Durable workflows have For each and Repeat, run for up to 24 hours, and recover from failures. The user gets the job done without building a workflow by hand.

Proposed Behavior

The planner detects work beyond plan limits and proposes a one-time durable workflow through the Phase 2 builder, using v3 For each where needed.
Approve & run starts it. Like Phase 5, the plan is forced to manual approval.
The builder sets the one-time workflow's alerts to notify-only, because the chat post-back is already the signal.
After it completes, the workflow is disabled automatically and marked as one-time in its provenance.

Acceptance Criteria

A 200-document review is handed off, runs durably, and posts one summary back into the chat.
The one-time workflow's alerts are notify-only, and it's disabled after it completes.
Functional tests, feature doc, release notes and config.py version.

Notes

Roadmap: §6, Phase 7. Related gotchas in §8: 31 (orchestration deadlines), 40 (result size), 55 (two signals for one run).
Open decision (§9), with the recommendation: disable and label one-time workflows after they complete rather than archiving them; the user can delete them.
Depends on: Phase 4 (Let chat orchestration propose workflows with an Approve, Deny and Edit card #1547) and Phase 6b (Post workflow results back into chat and answer follow-ups from them #1546).

Update roadmap status: Phase 7's settled 7a design and two follow-ups

Add the v3 For each hand-off builder and draft service

Phase 7a: keep the hand-off sidecar on the server step record

Add the workflow hand-off accept-and-run routes

Phase 7a: record how a one-time hand-off ended

Re-prove a hand-off report's lineage before reading it

Document the hand-off report's lineage re-proof

Bump version to 0.261.281 for the 7b hand-off card

Bump version to 0.261.282 for the 7b hand-off card

Bump version to 0.261.287 for the 7b hand-off card

Bump version to 0.261.288 for the 7b hand-off card

Bump version to 0.261.290 for the 7b hand-off card

Bump version to 0.261.291 for the 7b hand-off card

Bump version to 0.261.293 for the 7b hand-off card

Bump version to 0.261.294 for the 7b hand-off card

Ignore all foundry_consent harness build outputs

Bump version to 0.261.295 for the 7b hand-off card

Show workflow hand-offs under a chat answer in V2 (Phase 7b)

Document the V2 workflow hand-off card (Phase 7b)

Bump version to 0.261.256 for the V2 workflow hand-off card (Phase 7b)

Update roadmap status: 7b done; the capability is complete

Phase 7 complete

All three parts are merged into paullizer-react-v2-ui. The hand-off is behind Hand Off Large Work From Chat (enable_chat_orchestration_workflow_handoff), which is off by default.

7a, the server hand-off: Phase 7a: hand off large chat requests to a one-time workflow (server, 0.261.238) #1640 (0.261.250), merged as 15feec6.
7a follow-up, re-proving a hand-off report's lineage before it's read: Phase 7a follow-up: re-prove a hand-off report's lineage before reading it (0.261.252) #1647 (0.261.252), merged as 16f42e4.
7b, the V2 hand-off card: Show workflow hand-offs under a chat answer in V2 (Phase 7b) #1683 (0.261.295), merged as 167096e.

Acceptance criteria

A 200-document review is handed off, runs durably, and posts one summary back into the chat. functional_tests/test_workflow_handoff_end_to_end.py runs 3 and 200 documents through the real accept route, the durable runtime and runner (For each, then the report), the result store and reader, and 6b's delivery worker, and ends with one summary in the chat. Cosmos DB, the model, the per-document analysis, document listing and the lease heartbeat are faked. At 200 documents the report is read in pages of at most 100 records and 128 KiB.
The one-time workflow's alerts are notify-only, and it doesn't run again. Instead of being disabled after it completes, it's created disabled, with a manual trigger and two notify-only alert rules. The runtime records a one-time status when the run ends, and workflow_run refuses to start it again (workflow_one_time: "It was created for a single run. Open it in Workflows to run it again.").
Functional tests, the feature doc CHAT_ORCHESTRATION_WORKFLOW_HANDOFF.md, the fix doc WORKFLOW_HANDOFF_RESULT_LINEAGE_FIX.md, release notes and a version for each part. 7b adds Playwright coverage: test_v2_orchestration_workflow_handoff_card.py, test_v2_orchestration_workflow_handoff_plan.py and test_v2_orchestration_workflow_handoff_run_status.py.

Verified from tests and review, not on a live tenant.

Where it differs from the issue

There's no Approve & run button. The plan always needs manual approval, and then the hand-off card under the answer asks again. Accept creates the one-time workflow and queues its run, or Start its run appears if the workflow already exists. Edit opens it in the workflow editor, and saving accepts the edited version after a confirmation. Decline marks it Declined, and Try again appears after an error that can be retried.
The run's deadline is 24 hours. By default each user can start 5 hand-offs in any rolling 24 hours (Hand-offs from chat per user per day).
Loops are capped at 2,000 items. Only an all_matches document query that goes over the cap pauses the run.

Validation on each PR's final head

Phase 7a: hand off large chat requests to a one-time workflow (server, 0.261.238) #1640 at 319b268: CI 11/11. The CodeQL check passed and listed 4 notes: three in Phase 7a: hand off large chat requests to a one-time workflow (server, 0.261.238) #1640's tests (#3976, #3977 and #3978), and an import cycle in functions_workflow_limits.py that was already open as #3525.
Phase 7a follow-up: re-prove a hand-off report's lineage before reading it (0.261.252) #1647 at 6d45bb8: reader 81/81, off-golden 10/10 and builder 32/32, each under pytest and pytest -O. CI 11/11, and no new alerts.
Show workflow hand-offs under a chat answer in V2 (Phase 7b) #1683 at 1b2598f: CI 11/11, and CodeQL reported no new alerts with 0 annotations. The full rerun was on 4417d28, two commits earlier:
- Node: 205/205.
- Playwright: 178 passed. The 6 failures, in test_v2_orchestration_plan_card.py, predate 7b and happen only under pytest; the file passes 7/7 as a script.
- 92 passed under -O, and 525 functional tests passed.
- Docs: coverage 7/7, quality 6/6 and catalog parity 6/6.
- The last two commits, a .gitignore addition and the version renumber, got the docs checks only.
- The review's mutations: 21 of 25 killed, one equivalent, and three test gaps listed below.

Follow-ups (not blocking)

The card shows no item count before Accept.
The bell has no row specific to a hand-off.
The paused text keys on the waiting reason paused, because a pause has no reason code.
Retry is hidden when the capability allowlist has workflow_handoff but not workflow_run.
The editor round-trip test needs npm ci in CI.
Three test gaps found by mutating 7b in review. Nothing fails if a 401 on an edited save is reported as a 400 instead of reaching the editor, if the URL Access check reads only the draft and not the save payload, or if Try again appears whatever state the re-read leaves.
Each report read re-proves the lineage, so reading a 200-document report makes 1,409 result-store loads. A proof cache is the likely fix.
7a's 0.261.250 release note still says users can't accept a hand-off in the browser, which is no longer true.
Playwright teardown hits 11 errors from five URLs that Bring V2 User Settings to profile parity with an admin-style layout #1691 added and the tests don't stub. That's for paullizer-react-v2-ui to fix.
CodeQL notes still open on paullizer-react-v2-ui: #3976, #3977 and #3978 in Phase 7a: hand off large chat requests to a one-time workflow (server, 0.261.238) #1640's tests. The import cycle between functions_workflow_limits.py and functions_settings.py predates Phase 7 (#3523 to #3526). #4009 and #4010, on the same cycle, were first reported right after Phase 7a: hand off large chat requests to a one-time workflow (server, 0.261.238) #1640 merged, on import lines older than it.

This issue is ready to close.

Navigation Menu

Repository navigation

Hand off big one-time jobs from chat to a durable workflow #1549

Summary

User Value

Proposed Behavior

Acceptance Criteria

Notes

5 remaining items

Phase 7 complete

Acceptance criteria

Where it differs from the issue

Validation on each PR's final head

Follow-ups (not blocking)

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Hand off big one-time jobs from chat to a durable workflow #1549

Description

Summary

User Value

Proposed Behavior

Acceptance Criteria

Notes

Activity

5 remaining items

paullizer commented on Oct 8, 2026

Phase 7 complete

Acceptance criteria

Where it differs from the issue

Validation on each PR's final head

Follow-ups (not blocking)

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions