Carlos Florêncio
14 KiB
status, system, created, owners
| status | system | created | owners | |
|---|---|---|---|---|
| draft | tasks | 2026-08-31 |
|
Workflow Step Profile Session Lifecycle Requirements
Overview
The task system selects the task session that executes each workflow step. It owns this contract because a step's recipient determines task-session ownership. Each step chooses three related settings:
- The initial agent, an earlier step's agent session, or an agent profile.
- How the step obtains a session when it starts after a profile switch.
- What happens to its session when the workflow leaves it for another profile.
These settings let one workflow continue context for repeated work and use a fresh conversation for independent work.
Terminology
- Profile switch: A workflow transition that changes the effective agent profile.
- Start behavior: The destination step chooses whether to reuse an available session or start a new session.
- End behavior: The source step chooses whether to complete or park its session.
- Parked session: A nonterminal session whose runtime is stopped. Its conversation remains available.
- Profile re-entry: A profile switch to an agent profile that already has a session on the task.
Inspection of parked sessions and deferred destination launches is specified in queued session ownership. Selecting a conversation for reading is not a workflow re-entry or an explicit request to execute it.
Requirements
REQ-TASKS-WORKFLOW-PROFILE-SESSIONS-001: Configurable step profile-session lifecycle
Intent: Let a workflow author configure each step's conversation boundary with a conversation-preserving default and explicit completion when required.
User story: As a workflow author, I want each step to define how its session starts and ends, so repeated stages use the intended context.
Acceptance criteria
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.1: When a profile-only destination step selects Reuse an available session, Kandev shall reuse the newest eligible nonterminal session for that profile. When no session is available, Kandev shall create a new session. Explicit targets use requirement 002's exact conversation selection rules.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.2: When a destination step selects Start a new session, Kandev shall create a fresh conversation. It shall not reuse another session for that profile.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.3: When a source step selects Complete the session, Kandev shall complete its session during a profile switch. Kandev shall not automatically reuse that completed session later. Explicit conversation follow-ups follow task completion, without changing workflow ownership.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.4: When a source step selects Park the session, Kandev shall stop its runtime and keep the session nonterminal. The conversation shall remain available for reuse or manual follow-up.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.5: For existing profile-only steps, consecutive steps with the active session's profile shall keep that session when the destination uses the default or Reuse an available session start behavior. A profile-only destination with Start a new session shall always create a fresh conversation, even when its profile matches the active session. Explicit initial-session and earlier-step targets follow requirement 002, including fresh conversations with the same profile.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.6: When Kandev parks a session during a profile switch, its completion or stopped event shall not repeat transition actions for the destination step.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.7: When a workflow step is saved, reloaded, exported, imported, or synchronized, its start and end settings shall round-trip. Missing or invalid values shall use Reuse an available session and Park the session. An explicitly saved Complete the session value shall remain selected and shall retain its completion behavior.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.8: When an author edits a mutable workflow, one step selector shall show the recipient and a Session lifecycle setting above the searchable choices. That setting shall remain visible while the choices scroll or search has no results. It shall present separate When this step starts and When this step ends choices with visible explanations. For a new or unset step, Park the session shall be selected by default on desktop and phone surfaces.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.9: When the selector shows an agent profile, it shall show the same agent logo used by the new-task profile selector. The workflow-default choice shall use the generic agent icon.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.10: When a synchronized workflow is read-only, Kandev shall show the selected profile and both lifecycle settings. It shall not allow changes.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.11: When Kandev cannot prepare the destination session or record a parked switch, it shall stop the switch. The current session shall remain recoverable, and Kandev shall show the error.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.12: Changing one step's start or end setting shall not change another step's settings. A workflow can use all four start-and-end combinations.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.13: On a phone viewport, the selector shall use a touch-sized trigger and an inset bottom drawer. The drawer shall have one scroll region, safe-area spacing, keyboard-safe navigation, and no document-level horizontal overflow.
-
AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.14: If destination validation rejects an automatic transition after a turn completes, the current conversation shall accept another message without cancellation. The workflow step and primary session shall remain unchanged. This recovery shall not stop a newer turn or reopen a terminal session. Desktop and phone shall receive the recovered session state through the existing update channel.
REQ-TASKS-WORKFLOW-PROFILE-SESSIONS-002: Explicit workflow session recipients
Intent: Return a later step's prompt to the intended conversation without requiring its profile to be known when the workflow is authored.
Acceptance criteria
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.1: Every step shall offer Initial agent session. It shall refer to the task's original agent, resolved when the task obtains its first session, regardless of later primary-session or workflow-default changes.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.2: The selector shall offer each earlier step with an explicit profile override, labelled by step and profile. Two steps using the same profile shall remain distinct choices. Workflow editing shall not imply that these sessions already exist. Steps that inherit the workflow default are not source-step choices. Initial agent session reaches the original conversation, not every step that uses the default.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.3: With Initial agent session and Reuse an available session, a parked original conversation shall receive the step prompt. An unrelated newer session with the same profile shall not replace it.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.4: With an earlier-step target and Reuse an available session, the latest successfully selected conversation for that source step shall receive the prompt if it remains eligible. Re-entering the source step shall update that choice for later steps.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.5: With either explicit target and Start a new session, Kandev shall create a fresh conversation using that target's logical profile, even when the active session uses the same profile. It shall keep the identity of the original task conversation unchanged.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.6: When the referenced conversation is absent or terminal but its profile is known, Reuse an available session shall create a fresh conversation for that profile. It shall not revive a terminal conversation or select an unrelated conversation. The selector shall explain this fallback and the need to park a conversation for later reuse.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.7: When a step changes sessions, its predecessor's end setting shall govern the departing session. Reusing the already-active target shall keep it active. Each successful entry shall deliver the step prompt once to the selected session and show it as primary.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.8: Saving, reloading, duplicating, exporting, importing, and synchronizing a workflow shall preserve target meaning. Runtime bindings shall survive restart but shall not be copied to another task. Existing workflows without explicit targets shall retain their profile resolution and lifecycle behavior.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.9: An invalid, foreign, removed, or no-longer-earlier source step shall produce a visible configuration error. Unknown target kinds or conflicting routing choices shall be rejected. Runtime resolution failures shall stop entry without sending to another agent. The editor shall identify each affected step and let the author choose another valid target, clear the target, or undo the source change before saving. It shall not silently retarget a step when its source is moved or removed.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.10: If a task skips the referenced step, Kandev shall create a conversation from that step's configured profile. It shall not execute the skipped step's prompt or actions. If the source profile changes, later entries shall use its new profile with a fresh conversation instead of reusing an incompatible earlier binding.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.11: Desktop and phone selectors shall expose the same targets, lifecycle controls, explanations, and saved state. A phone shall use the existing inset drawer pattern, touch targets of at least 44 px, one scrolling list, and no document horizontal overflow. Synced workflows shall expose these values for inspection without editing.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-002.12: Conditional Override original session options shall remain a separate behavior. The editor and API shall prevent combining it with an explicit session target. Choosing a target shall not silently discard existing conditional rules.
REQ-TASKS-WORKFLOW-PROFILE-SESSIONS-003: Focus the recipient after a manual step move
Intent: Show the conversation selected by the step that the user enters.
Acceptance criteria
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-003.1: After a user moves the open task to a step, Kandev shall select that entry's committed recipient. This applies to new and reused conversations, including a destination with the same profile. A session pin established before the move shall not prevent this selection.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-003.2: Desktop shall activate the recipient's conversation tab. Phone shall show its chat and selected session in the session picker. Selecting the session shall not send another prompt or start another execution.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-003.3: A later manual session selection, task departure, closed preview, or newer move shall cancel the earlier pending focus. Returning to the same task shall not restore that intent. Background transitions shall retain their existing selection policy.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-003.4: Delayed, repeated, and reordered updates shall focus the matching recipient at most once. An unrelated session, stale entry, foreign session, or prepared route shall not qualify. Missing or ambiguous identity shall preserve the current view.
- AC-TASKS-WORKFLOW-PROFILE-SESSIONS-003.5: A failed move shall preserve the selected conversation and show the existing error. A queued entry without a committed recipient shall preserve selection until its recipient becomes available, subject to criterion 003.3. A step with no recipient shall not create one for navigation.
Implementation plans
Example
A task starts with Sol, which the user selects at task creation. Plan parks its session on exit. Implement selects Luna. Review selects Initial agent session and Reuse an available session. The Review prompt reaches the original Sol conversation. Selecting Start a new session on Review instead creates a fresh Sol conversation. Selecting Implement · Luna returns to Implement's eligible conversation, subject to Implement's end setting.
Out of scope
- A workflow-wide lifecycle setting or workflow-wide override.
- Lifecycle settings on transition edges.
- Reusing a session from a different agent profile.
- Keeping an inactive agent process or executor backend running.
- Automatic revival of a terminal session. Explicit completed-chat follow-ups belong to task completion; existing FAILED/CANCELLED recovery keeps its own rules.
- Automatically removing parked or historical sessions.
- Changing Office agent-session ownership or automation thread policies.
- Moving conditional original-session model settings into this selector.
- Choosing arbitrary session tabs while editing a reusable workflow.
- Referencing later steps, indirect target chains, or concurrent recipient fan-out.