Files
kandev/docs/specs/tasks/requirements/workflow-profile-session-lifecycle.md
T
2026-09-02 19:50:14 +00:00

103 lines
4.9 KiB
Markdown

---
status: draft
system: tasks
created: 2026-08-31
owners:
- kandev
---
# Workflow Step Profile Session Lifecycle Requirements
## Overview
The task system selects the task session that executes each fixed-profile
workflow step. Each step chooses three related settings:
- The agent profile that executes the step.
- 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.
## Requirements
### REQ-TASKS-WORKFLOW-PROFILE-SESSIONS-001: Configurable step profile-session lifecycle
**Intent:** Let a workflow author configure each step's conversation boundary
without changing existing workflow behavior.
**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 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.
- **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 reuse that completed session later.
- **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:** When consecutive workflow steps
resolve to the active session's profile, Kandev shall keep the active session.
The start and end settings shall have no effect.
- **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 **Complete the session**.
- **AC-TASKS-WORKFLOW-PROFILE-SESSIONS-001.8:** When an author edits a mutable
workflow, one step selector shall show the agent profile and a **Session
lifecycle** setting. The lifecycle setting shall present separate **When this
step starts** and **When this step ends** choices with visible explanations.
- **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.
## 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.
- Reviving a terminal `COMPLETED`, `FAILED`, or `CANCELLED` session.
- Automatically removing parked or historical sessions.
- Changing Office agent-session ownership or automation thread policies.
- Moving conditional original-session model settings into this selector.