263 lines
15 KiB
Markdown
263 lines
15 KiB
Markdown
---
|
|
status: draft
|
|
system: tasks
|
|
requirements:
|
|
- REQ-TASKS-COMPLETION-001
|
|
- REQ-TASKS-COMPLETION-002
|
|
---
|
|
|
|
# Task Completion System Design
|
|
|
|
## Purpose and boundaries
|
|
|
|
The task system owns workflow completion and conversation admission. Runtime
|
|
shutdown releases execution resources; it does not establish permanent loss of
|
|
conversation access. Agent runtime restoration and workspace recovery retain
|
|
their current owners and authorization checks.
|
|
|
|
| Requirement | Design sections |
|
|
| --- | --- |
|
|
| `REQ-TASKS-COMPLETION-001` | Step contract, Migration, Entry and notification |
|
|
| `REQ-TASKS-COMPLETION-002` | Explicit resume, Follow-up ownership, Cleanup and races, User interface |
|
|
|
|
## Step contract
|
|
|
|
Use `CompleteTaskOnEnter bool` and `complete_task_on_enter` in JSON, YAML, and
|
|
SQL. The naming follows `cancel_triggers_turn_complete`. Responses and current
|
|
exports include false explicitly. PATCH uses presence-aware decoding: omission
|
|
preserves the value, false disables it, and explicit null is rejected.
|
|
Create defaults an omitted value to false and rejects null or non-booleans.
|
|
|
|
Completion requires both final-step eligibility and an enabled setting.
|
|
Persist the setting on its step across reorder operations, but ignore it while
|
|
that step is non-final. The new final step uses its own saved value; reordering
|
|
does not transfer or automatically enable completion. The editor derives
|
|
visibility from the current draft order, and the backend evaluates the committed
|
|
order. Saving or discarding the order and settings uses existing coordination.
|
|
|
|
Carry the field through both task and workflow step models, `StepDefinition`,
|
|
the embedded workflow loader, task DTO conversion, workflow controller request
|
|
types, `stepevents`, MCP schemas and handlers, and all repository projections.
|
|
`workflow_steps.complete_task_on_enter` uses the repository's integer boolean
|
|
convention with a non-null zero default. Both repositories initialize this
|
|
shared table; neither constructor may erase or bypass migration decisions.
|
|
|
|
Frontend types, workflow API, boot hydration, WebSocket merges, step drafts,
|
|
save/rollback, workflow creation, and duplication carry the same boolean.
|
|
Partial WebSocket updates that omit it retain the saved value.
|
|
|
|
Portable export advances to version 2. Each version-2 step requires a boolean
|
|
completion field. Import and sync accept versions 1 and 2. At the version-1
|
|
boundary only, omitted values are materialized using the old name-and-final
|
|
predicate; explicit false always wins. Reject null in either version.
|
|
Normalize the whole workflow before converting individual steps, because legacy
|
|
final-position detection needs all steps. Export always emits version 2.
|
|
Thus current authored definitions never depend on names at runtime.
|
|
|
|
Sync applies normalized values and includes the field in equality checks.
|
|
Version-1 sync files remain authoritative legacy input until their authors
|
|
upgrade them; local editing of synced rows stays disabled. An invalid version-2
|
|
file follows existing freeze-and-report sync behavior.
|
|
|
|
Built-in YAML declares the field explicitly for every step. Preserve each
|
|
template's old behavior: qualifying final steps are true; other steps are false.
|
|
Do not make the final PR step in Improve Kandev terminal merely because it is
|
|
last. Update stored template definitions and workspace bootstrap paths too.
|
|
|
|
## Migration
|
|
|
|
The workflow repository owns the semantic backfill, after required additive
|
|
schema changes and before serving requests or starting sync. Task repository
|
|
projection/bootstrap initialization adds the same column before its own writers
|
|
need it. It does not independently infer or backfill completion.
|
|
|
|
Use one transaction and a durable `kandev_meta` key,
|
|
`workflow_complete_task_on_enter_backfill_v1`. Inside the transaction, read the
|
|
marker, backfill legacy steps and stored template JSON, then record completion.
|
|
Use the existing portable Go normalization for trimmed case-insensitive names
|
|
and final position. A final step has no sibling with a greater position,
|
|
matching `GetNextStepByPosition`; tied maximum positions retain that definition.
|
|
Preserve row timestamps and IDs. The transaction rolls back the marker and all
|
|
backfill writes on failure. Startup fails if this required migration fails.
|
|
|
|
Replay skips the semantic backfill after the marker. It must not use
|
|
`WHERE complete_task_on_enter = 0` as a recurring migration. Fresh startup writes
|
|
explicit built-in values and records the marker before ordinary user writes.
|
|
Template backfill preserves unrelated JSON fields and respects explicit values.
|
|
Required-store conformance covers actual constructor order, fresh SQLite and
|
|
PostgreSQL, old-schema upgrade, replay after disabling, and failure/retry.
|
|
Historical release fixtures remain truthful snapshots; add assertions or a
|
|
dedicated legacy fixture rather than editing old releases to contain new columns.
|
|
|
|
## Entry and notification
|
|
|
|
Replace the name test in `IsTerminalStep` with the explicit boolean while
|
|
retaining final-position eligibility. A step completes work only when it has
|
|
no successor and its setting is true.
|
|
Keep the old name predicate private to legacy conversion/migration. Audit all
|
|
callers, including task creation, `task/service.service_workflow`,
|
|
`orchestrator.workflow_store`, queued moves, automated transitions, and
|
|
`task_launch_workflow`. Every caller must resolve the actual successor or
|
|
equivalent final-position evidence; passing nil without a lookup is not proof.
|
|
|
|
Persist step and task-state changes through existing guarded transition and
|
|
ledger operations. A checked final entry completes a nonterminal task; an
|
|
unchecked or non-final entry follows existing nonterminal/reopen behavior.
|
|
Do not convert FAILED or
|
|
CANCELLED to success. Saving the checkbox does not reevaluate resident tasks.
|
|
Do not add transition actions or replay on-enter during Resume.
|
|
|
|
Parent rollups and dependencies use committed task state. Remove name- or
|
|
step-membership fallback from `annotateTerminalChildSteps` and terminal receipt
|
|
handling. Preserve `DependencyStatusForTask`'s existing state-only resolution.
|
|
Completion events follow the
|
|
successful state write, never a speculative target lookup. Preserve existing
|
|
operation deduplication, failure/cancellation rollups, archived-child filtering,
|
|
and success-only dependency launches. Upgrade does not rewrite resident tasks
|
|
or fire old completion events; pre-existing persisted completion stays intact.
|
|
|
|
## Explicit resume
|
|
|
|
Reuse `session.recover` with `action: resume`. Admit completed recovery only
|
|
through this explicit operation or a session-pinned follow-up send. Carry a
|
|
narrow internal completed-resume permission through `LaunchSession` and
|
|
`executor.ResumeOptions`; automatic `session.ensure`, status reads, generic
|
|
open-time launch, and startup recovery never infer that permission.
|
|
|
|
Authorize the task/session pair and prompt access before side effects. Under
|
|
the existing lifecycle/cancel guards, reload the exact session and task, verify
|
|
archive and runtime ownership, and claim the current completed state/version.
|
|
Require the expected execution generation as well as state where a callback
|
|
can replace the session during recovery. Do not weaken global terminal guards.
|
|
|
|
Extend `allowsSessionStartingRecovery` only for an explicitly claimed completed
|
|
resume. Permit absent `executors_running` after cleanup; retain recoverable task
|
|
environment and profile checks. Reuse stale-execution cleanup, provider token
|
|
restoration, and native/CLI/history fallback. Persist `STARTING` and clear
|
|
`CompletedAt` through the guarded writer before credentials are issued. Retain
|
|
prior execution and turn history; do not clear ACP/provider identity.
|
|
|
|
At readiness, settle into the existing input-capable state without sending a
|
|
synthetic workflow or task-description prompt. Preserve current initial-message
|
|
backfill only for genuinely absent launch history. The next user send starts
|
|
one new conversational turn after the old one. No new session ID or queue
|
|
incarnation is allocated by Resume.
|
|
|
|
`message_target_session.go` continues to prefer live primary, then live
|
|
fallback. Completed siblings must not shadow a live session. With no live
|
|
session, a completed primary, or the newest completed session if no primary
|
|
exists, can be selected and pinned. An explicit completed `session_id` always
|
|
targets that session. Authorization and validation precede the same resume
|
|
admission, which runs before `ProcessOnTurnStart` and message persistence.
|
|
FAILED/CANCELLED dispatch continues to reject with its existing error code.
|
|
|
|
## Follow-up ownership
|
|
|
|
A message on a completed task is conversation work. Runtime running, waiting,
|
|
failed, and finished events do not reopen that task or replay workflow entry,
|
|
turn-start, turn-complete, completion-signal, or parent notification effects.
|
|
Existing explicit task moves/state APIs remain the way to reopen workflow work.
|
|
|
|
For an explicitly resumed completed session on a still-active task, persist a
|
|
session metadata marker `completion_follow_up` in the guarded resume claim.
|
|
It records conversational-only ownership independently of the mutable session
|
|
state. Such a session stays excluded from automatic profile reuse and cannot
|
|
become primary merely because it resumes. Automatic workflow triggers and
|
|
runtime task-state reconciliation skip it. An explicit workflow handoff may
|
|
clear the marker only while establishing that session's workflow ownership.
|
|
An ordinary send, page activation, or automatic reuse lookup cannot clear it.
|
|
|
|
Pinned user and MCP sends, queued dispatch, streaming completion, agent exit,
|
|
and failure publication consume the same ownership predicate. This protects a
|
|
retired profile conversation even after its state becomes `WAITING_FOR_INPUT`.
|
|
Preserve primary IDs, profile routing, step history, and current queue policy.
|
|
|
|
## Cleanup and races
|
|
|
|
For successful task completion, stop collapsing an ordinary child conversation
|
|
to `COMPLETED` in `setSessionWaitingForInputIfRequestedWithHook`. Settle it with
|
|
the existing root-task waiting behavior. Keep task status completed and retain
|
|
the fail-closed idle resource reclamation. Do not change failed/cancelled task
|
|
receipt rules through this branch.
|
|
|
|
Use current-turn clarification lookup; any active clarification retains its
|
|
existing barrier and late-answer path. Historical answered or expired bundles
|
|
remain history. A lookup error cannot justify closing the conversation.
|
|
|
|
Cleanup and resumed execution must use the same lifecycle ownership boundary.
|
|
An old receipt, stop callback, stream frame, or reclaim operation carries its
|
|
execution identity; after a newer resume claim it cannot clear queues or stop
|
|
the replacement runtime. Preserve retired-execution tombstones. Release guards
|
|
before waiting for callbacks that need those guards.
|
|
|
|
Queue admission and readiness use the existing queue-incarnation and dispatch
|
|
reservation contract. Never clear pending messages solely because the old
|
|
execution completed. Duplicate Resume joins or returns the existing attempt.
|
|
A later stop/archive/delete wins over stale recovery writes. A failed launch
|
|
uses existing recoverable error state without changing completed task state;
|
|
retain the follow-up marker for retry and preserve queued/unsent content.
|
|
|
|
## User interface
|
|
|
|
`SessionStoppedBanner` completed mode has primary Resume and secondary New
|
|
Agent. Reuse `useSessionRecoveryActions` and existing recovery error feedback.
|
|
Show busy state, disable duplicate actions, and restore the composer from the
|
|
authoritative session update. Missing profile feedback stays visible. New
|
|
Agent retains its dialog and intentional new-conversation behavior.
|
|
|
|
Keep the completed-chat open-time gate in session-resumption hooks. Extend
|
|
recovery hook tests for response success/failure, session switching while a
|
|
request is pending, and busy cleanup. Do not let a late response modify another
|
|
chat's recovery feedback or selected session.
|
|
|
|
Show the completion checkbox only in the final step's entry/general settings,
|
|
outside the conditional turn-complete controls. It remains available when the
|
|
final step has no actions. Put the description inside an adjacent info icon
|
|
using the existing HelpTip interaction: hover or focus on desktop, tap on touch.
|
|
Do not render the description permanently below the checkbox. Suggested text:
|
|
"Marks the task complete when it enters this final step. You can still continue
|
|
the conversation." Give the icon a localized accessible name. Use coordinated
|
|
dirty/save/discard state and read-only sync treatment. Localize all copy.
|
|
|
|
### Mobile composition
|
|
|
|
The existing `task-layout.tsx` phone layout and inline stopped-session banner
|
|
are the chat exemplar. Keep the transcript's single scroll owner and the
|
|
composer area's safe-area spacing. Stack Resume then New Agent on phones;
|
|
retain compact side-by-side buttons on fine-pointer desktop. Phone/coarse
|
|
pointer actions have at least 44 px active height; no unconditional desktop
|
|
`min-h-11` sizing is introduced.
|
|
|
|
The step editor's `CancelCompletionToggle` supplies the checkbox/label pattern;
|
|
the existing mobile workflow step selector supplies focused navigation. Use a
|
|
44 px tappable label and a touch-accessible info icon. Disclose wrapping helper
|
|
text through the existing touch help surface; do not require hover or add a
|
|
new standalone modal. Opening help must not toggle the checkbox.
|
|
An inline setting fits this short choice. Both viewports share draft and save
|
|
logic. Preserve keyboard focus, one settings scroll region, no horizontal page
|
|
overflow, and access to Save changes above safe-area insets.
|
|
|
|
## Verification and observability
|
|
|
|
Use barrier-based Go tests for resume/stop, reclaim/resume, stale receipt/new
|
|
execution, double Resume, and readiness/queue admission. Assert the preserved
|
|
task, primary session, provider token, history, queue order, and emitted events.
|
|
Test both database dialects at migration boundaries. Use existing structured
|
|
logs with task/session/execution identity and resume outcome; do not log tokens.
|
|
|
|
Desktop and mobile Playwright tests save/reload the final-step checkbox, complete
|
|
checked final steps, send from unchecked final steps, and Resume a persisted
|
|
completed chat. Reorder tests prove the control moves to the current final
|
|
step and a previously checked non-final step cannot complete work. Help tests
|
|
prove hover/focus/tap disclosure and that opening help does not toggle the value.
|
|
Assert a second agent response, unchanged session count and history, and no
|
|
task reopen or duplicate completion. Include a retired non-primary session and
|
|
active clarification regression. Run against freshly built production assets.
|
|
|
|
## Related decisions
|
|
|
|
- [Separate task completion from conversation availability](../../../decisions/2026-09-09-task-completion-conversation-availability.md)
|
|
- [Replayable migrations](../../../decisions/0027-replayable-schema-migrations.md)
|
|
- [Profile-switch session policy](../../../decisions/2026-08-31-workflow-profile-session-switch-policy.md)
|
|
- [Current-turn clarification ownership](../../../decisions/2026-08-14-current-turn-clarification-ownership.md)
|