cli: queue messages (json-io + interactive) with backpressure + queue UI

[marius-kilocode]

Implements reliable message queueing in the CLI so clients can enqueue messages even before the extension/agent is ready.

• Queue inbound --json-io stdin messages and deliver when the extension is ready and the agent can accept them (approval gating + backpressure).
• Queue interactive user messages when the agent is busy; show a fixed queued preview above the input.
• ESC/cancel clears all locally queued messages (outgoing + stdin queue).
• Add tests for queueing/backpressure/clear behavior.
• Docs: cli/docs/MESSAGE_QUEUE.md and cli/docs/AGENT_MANAGER_JSON_IO_QUEUE_SPEC.md.

Changeset included: .changeset/cli-json-io-message-queueing.md.

Out of scope: Agent manager integration

[changeset-bot]

🦋 Changeset detected

Latest commit: 0cc2576

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@kilocode/cli	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[Copilot]

Pull request overview

This PR implements a comprehensive message queueing system for the CLI to handle both inbound JSON-IO stdin messages and interactive user messages. The implementation adds backpressure management to ensure messages are delivered sequentially only when the extension/agent is ready to process them.

Key Changes

• Added SequentialWorkQueue utility for reliable message delivery with retry logic and backpressure
• Implemented stdin message queueing for --json-io mode with state-aware delivery gating
• Added interactive user message queueing with UI preview showing queued messages
• Integrated ESC/cancel to clear all queued messages (both outgoing and stdin)

Reviewed changes

Copilot reviewed 13 out of 14 changed files in this pull request and generated 7 comments.

Show a summary per file

File	Description
cli/src/utils/sequential-work-queue.ts	New generic work queue with retry, backpressure, and sequential processing
cli/src/state/hooks/useStdinJsonHandler.ts	Refactored to queue stdin messages until service is ready and agent can accept them
cli/src/state/hooks/useOutgoingMessageQueue.ts	New hook managing outgoing user message queue with backpressure
cli/src/state/hooks/useMessageHandler.ts	Updated to enqueue messages when agent is busy or not ready
cli/src/ui/components/CommandInput.tsx	Added UI preview box showing next queued message
cli/src/state/atoms/queuedMessages.ts	New atoms for queue state and clear signals
cli/src/state/atoms/actions.ts	Cancel action now clears all message queues
cli/src/state/hooks/__tests__/useStdinJsonHandler.test.ts	Added comprehensive tests for stdin queue backpressure
cli/src/state/hooks/__tests__/useOutgoingMessageQueue.test.ts	New tests for outgoing message queue behavior
cli/src/ui/components/__tests__/CommandInput.test.tsx	Updated mocks to support queue UI
cli/src/state/atoms/__tests__/modelValidation.test.ts	Fixed mock to preserve actual exports
cli/src/state/atoms/__tests__/config.test.ts	Fixed mock to preserve actual exports
.changeset/cli-json-io-message-queueing.md	Changeset documenting the patch
pnpm-lock.yaml	Dependency lock file updates

Files not reviewed (1)

• pnpm-lock.yaml: Language not supported

[kiloconnect]

Code Review Summary

Status: 8 Issues Found | Recommendation: Address before merge

Overview

Severity	Count
CRITICAL	0
WARNING	5
SUGGESTION	3

Issue Details (click to expand)

WARNING

File	Line	Issue
cli/src/state/hooks/useMessageHandler.ts	N/A	When a message is enqueued, the function returns early without waiting for delivery confirmation. This could lead to race conditions if the caller expects the message to be sent.
cli/src/state/hooks/useStdinJsonHandler.ts	N/A	The createStateChangeWaiter function is duplicated - it's defined in state-change-waiter.ts and imported, but the pattern is also used inline. Consider consolidating.
cli/src/utils/wait-for-agent-reaction.ts	41	Missing test coverage for wait-for-agent-reaction.ts utility. While it's tested indirectly through processor tests, direct unit tests would improve confidence.
cli/src/utils/sequential-work-queue.ts	142	The new sequential-work-queue.ts utility has test coverage but could benefit from additional edge case tests (e.g., concurrent enqueue during drain).
.changeset/cli-json-io-message-queueing.md	5	The PR description mentions documentation files cli/docs/MESSAGE_QUEUEING.md but no such documentation was added. Consider adding documentation for the new queueing behavior.

SUGGESTION

File	Line	Issue
cli/src/state/hooks/useOutgoingMessageQueue.ts	N/A	Indentation inconsistency in the process callback (lines 87-122) and useOutgoingMessageQueue hook (lines 209-226).
cli/src/state/hooks/useStdinJsonHandler.ts	N/A	Indentation inconsistency in the canProcess callback (lines 135-167) and process callback (lines 168-199).
cli/src/state/hooks/useMessageHandler.ts	N/A	The payload variable is defined but only used once. Consider inlining it or restructuring for clarity.

Positive Observations

• ✅ Good test coverage for the new queue processors (useOutgoingMessageQueue.test.ts, useStdinJsonHandler.test.ts)
• ✅ Good test coverage for SequentialWorkQueue utility
• ✅ Good test coverage for state-change-waiter utility
• ✅ Clean separation of concerns with the processor factory pattern
• ✅ Proper cleanup with dispose() methods
• ✅ Backpressure handling to prevent message flooding
• ✅ Followup question handling to drop stale messages

Files Reviewed (14 files)

• .changeset/cli-json-io-message-queueing.md - 1 issue
• cli/src/state/atoms/__tests__/config.test.ts - 0 issues (test refactoring)
• cli/src/state/atoms/__tests__/modelValidation.test.ts - 0 issues (test refactoring)
• cli/src/state/atoms/actions.ts - 0 issues
• cli/src/state/atoms/queuedMessages.ts - 0 issues
• cli/src/state/atoms/ui.ts - 0 issues
• cli/src/state/hooks/__tests__/useOutgoingMessageQueue.test.ts - 0 issues
• cli/src/state/hooks/__tests__/useStdinJsonHandler.test.ts - 0 issues
• cli/src/state/hooks/useMessageHandler.ts - 2 issues
• cli/src/state/hooks/useOutgoingMessageQueue.ts - 1 issue
• cli/src/state/hooks/useStdinJsonHandler.ts - 2 issues
• cli/src/ui/components/CommandInput.tsx - 0 issues
• cli/src/ui/components/__tests__/CommandInput.test.tsx - 0 issues
• cli/src/utils/__tests__/sequential-work-queue.test.ts - 0 issues
• cli/src/utils/__tests__/state-change-waiter.test.ts - 0 issues
• cli/src/utils/sequential-work-queue.ts - 1 issue
• cli/src/utils/state-change-waiter.ts - 0 issues
• cli/src/utils/wait-for-agent-reaction.ts - 1 issue

---

Fix these issues in Kilo Cloud