Carlos Florêncio
4.2 KiB
created, status, requirements, system_design, legacy_specs
| created | status | requirements | system_design | legacy_specs | ||
|---|---|---|---|---|---|---|
| 2026-08-31 | draft |
|
|
Implementation Plan: Workflow Step Session Lifecycle
Overview
Replace the combined three-value policy with separate step-start and step-end settings. Then update session routing, the combined agent selector, tests, and documentation.
The change builds on the safe parking and callback handling already implemented in PR 3225.
Scope
In scope
- Two per-step enums for session start and end behavior.
- Removal of the unshipped combined policy.
- Source-step end behavior and destination-step start behavior in session routing.
- All four start-and-end combinations.
- Clear lifecycle labels and helper messages.
- Agent logos in profile rows and the selected-profile trigger.
- Desktop popover and mobile inset drawer behavior.
- Persistence, API, templates, portable formats, sync, tests, and public docs.
Out of scope
- Workflow-wide or transition-edge settings.
- A new task-session state.
- Office or automation session ownership.
- Automatic cleanup of parked sessions.
- Conditional original-session model settings.
Technical approach
Split the contract
Replace profile_session_policy with:
profile_session_start_policy:reuseornew.profile_session_end_policy:completeorpark.
Use reuse and complete as defaults. Remove the old enum and every old
mapping because the contract is not released.
Split routing inputs
Refactor profile switching to accept a destination start setting and a source end setting. The start setting controls lookup or creation. The end setting controls completion or parking.
Thread the source step or normalized end setting through every transition path. The workflow engine core does not change. Its integration boundary changes when a path currently retains only the destination step.
Keep the current stop-intent, lifecycle guard, promotion, queue rollback, and credential preflight protections.
Simplify the selector
Keep profile search as the first view. Add a Session lifecycle row with this compact summary:
Reuse on start · Complete on end
The lifecycle view has two groups:
- When this step starts
- Reuse an available session
- Start a new session
- When this step ends
- Complete the session
- Park the session
Show short descriptions from the system design. Remove the old combined labels.
Use AgentLogo for actual profiles in rows and the trigger. Use the generic
agent icon for the workflow-default choice.
Mobile design contract
Keep the inset bottom drawer on phones. The lifecycle view contains both groups in one scroll region. Rows have a 44 px active dimension. Back returns to the profile list. Close returns focus to the trigger.
Desktop and mobile share filtering, normalization, draft updates, dirty state, and save behavior.
Tests
- Persistence and portable tests cover both defaults and independent round trips.
- Orchestrator tests cover the four combinations and prove source/destination ownership.
- Existing race and error-path tests remain.
- Frontend tests cover copy, logos, both groups, summaries, dirty state, and read-only behavior.
E2E tests
- Desktop saves two steps with different lifecycle combinations and proves all four runtime outcomes.
- Mobile selects both settings, saves, reloads, returns focus, and remains viewport-contained.
Work orders
- Task 01: Split the step lifecycle contract
- Task 02: Route source and destination behavior
- Task 03: Simplify the selector and add agent logos
- Task 04: Prove all lifecycle combinations
Risks
- A transition path can use the destination end setting by mistake.
- Direct engine entry can lose the source step after task state changes.
- Retaining the old field creates two sources of truth.
- UI text can imply that end behavior applies after every agent turn.
- The mobile lifecycle view can become too tall without one scroll owner.