Files
kandev/docs/plans/resume-prompt-queue/plan.md
T
2026-09-09 21:32:38 +01:00

150 lines
6.3 KiB
Markdown

---
created: 2026-09-09
status: complete
requirements:
- REQ-TASKS-RESUME-PROMPT-QUEUE-001
system_design:
- ../../specs/tasks/system-design/resume-prompt-queue.md
legacy_specs: []
---
# Implementation Plan: Resume Prompt Queue
## Overview
Enable Send during resume through the existing durable queue. First close the
readiness race at admission. Then enable the composer and verify the user flow.
Requirement: [REQ-TASKS-RESUME-PROMPT-QUEUE-001](../../specs/tasks/requirements/resume-prompt-queue.md).
Design: [Resume prompt queue](../../specs/tasks/system-design/resume-prompt-queue.md).
## Scope
### In scope
- Existing queue-capable sessions during resume or initial startup.
- Task chat and Quick Chat on desktop and mobile.
- Persistence before draft clearing, automatic dispatch, and current queue policy.
- Focused regression coverage and a public documentation update during implementation.
### Out of scope
- New session creation without queue identity or terminal input emulation.
- New queue storage, timers, schedulers, settings, or public API actions.
- Changed Auto-run, merge, recovery, workflow, or cancellation policy.
## Technical approach
### Admission and dispatch
Before this change, `QueueHandlers.wsQueueMessage` persisted and published
without a readiness recheck. Add an internal automatic-dispatch collaborator and wire the
orchestrator through the existing queue-handler registration.
Reuse guarded identity-aware reservation and task admission. Preserve Auto-run
OFF. Do not use the manual drain endpoint, which enables Auto-run.
The post-admission check and `handleAgentBootReady` cover either event order.
An accepted admission remains successful if immediate dispatch is deferred.
### Composer
`deriveSessionInputMode` already maps `STARTING` to `queue`. Reuse that selected
session mode and complete queue identity for startup eligibility.
`useChatInputContainer` permits submission only when that eligibility exists.
`isPreparingEnvironment` alone remains insufficient.
`useMessageHandler` retains its submission-time state read and payload builder.
`useQueueAdmissionAction` must not silently report success without identity or
an operation token. Failed attempts preserve the draft and attachments.
### Documentation
During implementation, update the queue guidance in
`docs/public/sessions-and-review.md`. This is a how-to section: explain Send
during resume, the queued indicator, Auto-run OFF, and failed-resume recovery.
The public documentation update is included with the implementation.
## Tests
All suffixes below refer to `AC-TASKS-RESUME-PROMPT-QUEUE-001`.
| Criteria | Evidence |
| --- | --- |
| `.3`, `.4`, `.5`, `.7`, `.8` | New `resume_prompt_queue_test.go`: admission before/after boot readiness, concurrent checks, paused queue, failed resume, stale identity |
| `.3`, `.4`, `.5` | `handlers/queue_handlers_test.go`: actual `wsQueueMessage` calls the automatic check only after successful admission |
| `.1`, `.6`, `.9` | `use-chat-input-container.test.ts`: button/capability gate matrix, identity unavailable, preparation-only, existing blockers |
| `.1`, `.2`, `.8` | `use-message-handler.test.ts`: current-session routing and complete queued payload |
| `.2`, `.6`, `.8` | `use-queue.test.ts` and `use-chat-input-state.test.ts`: rejected/no-op admission preserves content, accepted admission clears it |
The backend tests use channel barriers for ordering. They count actual prompt
dispatches and retain existing boot-ready and queue-policy regression tests.
## E2E tests
Add `e2e/tests/session/session-resume-prompt-queue.spec.ts` for `chromium`.
Add `mobile-session-resume-prompt-queue.spec.ts` for `mobile-chrome`.
Shared scenarios belong in `e2e/helpers/session-resume-prompt-queue.ts`.
Cover a real delayed resume, Send, visible queue admission, then one resulting
turn after readiness (`.1` through `.4`). Cover reload after admission (`.8`).
Cover Auto-run OFF and failure recovery (`.5`, `.7`). Use task chat for the
full lifecycle matrix and Quick Chat for shared composer admission and delivery.
The mobile case uses tap, confirms the target is reachable, and asserts no
horizontal overflow (`.9`).
Reuse session recovery and queue fixtures. The current git-delay shim can hold
workspace preparation. If resume reuses its workspace, use a deterministic
mock-agent readiness barrier. Delaying only a browser response cannot prove
that the backend agent is still resuming.
Update the initial-start test in `session-recovery.spec.ts` where queue
eligibility replaces its previous disabled-Send assertion. Keep coverage for
preparation without queue identity. Disable inherited retries for regressions.
## Work orders
- [x] [Task 01: Close queue admission readiness race](task-01-admission-readiness.md)
- [x] [Task 02: Enable Send during resume](task-02-resume-composer.md)
Order: Task 01, then Task 02. Both tasks are complete. Work was sequential in
this session.
## Verification results
Task 01 and Task 02 implementation and focused verification are complete.
Task 02 verification on 2026-09-09:
- Frontend unit suite: passed, 150 tests across 10 files.
- Frontend typecheck and i18n check: passed.
- Desktop resume, Quick Chat, and layout E2E: passed, 3 tests.
- Mobile resume, touch target, and overflow E2E: passed, 1 test.
- Existing session-recovery startup E2E: passed, 1 test.
- Backend focused suites: passed, including 16 handler tests, 23 orchestrator
tests, 6 readiness tests with `-race`, 1 handler race test, and 12 mock-agent
tests.
- Public documentation validation: passed, 61 tests and 46 published pages.
- `rtk git diff --check`: passed.
Design validation on 2026-09-09:
- `rtk python3 scripts/lint-spec-files.test.py`: passed, 30 tests.
- `rtk python3 scripts/lint-spec-files.py --all`: passed.
- `rtk git diff --check`: passed.
Task 01 verification on 2026-09-09:
- Focused handler suite: passed, 16 tests.
- Focused orchestrator suite: passed, 23 tests.
- New readiness and identity cases with `-race`: passed, 6 tests.
- Handler readiness callback with `-race`: passed, 1 test.
## Risks
- The one-shot boot-ready event can precede queue insertion.
- A manual drain would silently enable a paused queue.
- Presentation startup can precede queue identity hydration.
- A silent admission no-op can clear an unsaved draft.
- Browser-only delays can conceal a backend readiness race in E2E.
- Queue admission must preserve initial-prompt order during normal startup.