feat(cli): add /loop command for periodic task execution

[wenshao]

Summary

• Add /loop slash command that periodically executes a prompt at a configurable interval
• Add LoopManager in core for framework-agnostic loop state management
• Integrate with AppContainer for automatic iteration scheduling on streaming completion

Closes #2638

Features

Command	Description
/loop 5m check if CI passed	Run every 5 minutes
/loop 30s --max 10 is server healthy?	Run every 30s, max 10 times
/loop status	Show active loop info
/loop stop	Cancel the active loop

• Interval support: 10s to 24h, default 10m
• Auto-pause after 3 consecutive failures
• Tab completion for subcommands and common intervals
• i18n for all user-facing strings
• waitingForResponse flag ensures normal user prompts don't interfere with loop scheduling

Test plan

• 24 unit tests covering interval parsing/formatting, loop lifecycle, failure handling, pause/resume, skipFirstIteration, timer cleanup, singleton management
• Manual: /loop 10s check date — verify iterations appear with headers
• Manual: /loop stop during active loop — verify clean stop
• Manual: /loop status — verify status display
• Manual: type a normal prompt during loop interval wait — verify it doesn't disrupt loop

🤖 Generated with Claude Code

[github-actions]

📋 Review Summary

This PR introduces a /loop command that enables periodic task execution at configurable intervals, along with a LoopManager class for framework-agnostic state management. The implementation is well-structured with comprehensive test coverage (24 unit tests), proper i18n support, and thoughtful UX features like auto-pause on failures and tab completion. Overall, this is a solid implementation that addresses the feature requirements effectively.

🔍 General Feedback

• Architecture: Clean separation between the CLI command layer (loopCommand.ts) and core logic (LoopManager), following the project's established patterns
• Test Coverage: Excellent unit test coverage for interval parsing/formatting, loop lifecycle, failure handling, pause/resume, and timer cleanup
• User Experience: Well-considered features including auto-pause after 3 consecutive failures, waitingForResponse flag to prevent interference from normal prompts, and clear status/stop subcommands
• Internationalization: All user-facing strings properly wrapped with t() for i18n support
• Type Safety: Strong TypeScript typing throughout with proper interfaces for LoopConfig and LoopState

🎯 Specific Feedback

🟡 High

• packages/cli/src/ui/AppContainer.tsx:934-967 - The useEffect that sets up the loop iteration callback has an empty dependency array but captures addMessage and historyManager via refs. While the ref pattern is correct, the t function used inside the callback could become stale if the locale changes. Consider adding t to the dependencies or using a ref for it as well.

• packages/cli/src/ui/AppContainer.tsx:969-1008 - The streaming state effect checks loopManager.isActive() and loopManager.isWaitingForResponse() but these values could change between renders. The effect only depends on streamingState, which means if the loop manager state changes, this effect won't re-run. Consider whether this could lead to missed notifications or stale state reads.

• packages/core/src/loop/loopManager.ts:183-186 - The onIterationComplete method keeps state accessible after loop completion but doesn't clear the timer. If stop() is called after completion, it will try to clear a potentially already-executed timer. While clearTimeout is idempotent, consider explicitly clearing timerId when the loop completes naturally.

🟢 Medium

• packages/cli/src/ui/commands/loopCommand.ts:58-71 - The parseLoopArgs function returns default values when no tokens are provided, but this results in an empty prompt which then fails validation in the action. Consider returning an error indicator earlier or documenting this flow more clearly.

• packages/core/src/loop/loopManager.ts:15 - The MAX_CONSECUTIVE_FAILURES constant is hardcoded as a module constant. Consider making this configurable via the LoopConfig interface to allow callers to customize the failure threshold.

• packages/core/src/loop/loopManager.ts:203-205 - The comment states "Keep state accessible briefly so caller can read final iteration count" but there's no mechanism to clean up this state. The state remains accessible until stop() is called or a new loop starts. Consider documenting this behavior or adding a cleanup timeout.

• packages/cli/src/ui/commands/loopCommand.ts:236-245 - The completion function only provides completions for subcommands and preset intervals when the partial argument is empty or matches 'status'/'stop'. It doesn't provide any completion suggestions when the user is typing an interval or prompt, which could be a missed opportunity for UX improvement.

🔵 Low

• packages/core/src/loop/loopManager.ts:127-128 - The getState() method returns Readonly<LoopState> but the actual returned object is not frozen. Consider using Object.freeze() or creating a readonly copy to prevent accidental mutations from outside the class.

• packages/cli/src/ui/commands/loopCommand.ts:1 - The license header mentions "Qwen Team" and "Apache-2.0" which is consistent with the project. However, the JSDoc comment at the top of the file could benefit from an @module tag for better documentation generation.

• packages/core/src/loop/loopManager.test.ts:113-115 - The test "ignores onIterationComplete when not waiting for response" only tests one edge case. Consider adding a test for calling onIterationComplete when no loop is active (state is null) to ensure it doesn't throw.

• packages/cli/src/ui/AppContainer.tsx:44-45 - The imports getLoopManager and formatInterval are added to an existing import statement from @qwen-code/qwen-code-core. Consider grouping these with related imports for better readability.

• packages/core/src/loop/loopManager.ts:91-92 - The parseInterval function uses Math.round() for conversion but doesn't validate that the result fits within JavaScript's safe integer range. While practically not an issue for the allowed interval range (10s to 24h), adding a comment or validation could improve robustness.

✅ Highlights

• Excellent Test Coverage: The 24 unit tests comprehensively cover interval parsing/formatting edge cases, loop lifecycle, failure handling, pause/resume functionality, and singleton management
• Clean Architecture: The separation between LoopManager (core logic) and loopCommand (UI layer) follows the project's established patterns and makes the code highly maintainable
• Thoughtful UX Features: The auto-pause after 3 consecutive failures, waitingForResponse flag to prevent prompt interference, and clear status messages demonstrate careful consideration of real-world usage scenarios
• Proper Resource Cleanup: The stop() method properly clears timers, and the useEffect cleanup in AppContainer ensures the loop is stopped when the component unmounts
• Good Error Handling: Clear error messages for invalid intervals, missing prompts, and usage instructions with examples

[wenshao]

Thanks for the thorough review! Here's how I addressed each point:

High

1. t function stale in callback — t is a module-level import (not React state/prop), so it stays current even when locale changes trigger a re-render. No ref needed.

2. Streaming state effect reading stale loopManager state — getLoopManager() returns a singleton with mutable internal state. Each effect invocation calls the methods directly on the live instance, so isActive() / isWaitingForResponse() always reflect current state. The effect only needs streamingState as trigger — it's intentional.

3. timerId not cleared on natural completion — ✅ Fixed in a1ab9df. Now explicitly clears timerId when loop completes via maxIterations, even though no pending timer should exist at that point (defensive cleanup).

Medium

4. parseLoopArgs empty prompt flow — This is intentional: empty prompt → action shows usage help. Standard pattern used by other commands in the project.

5. MAX_CONSECUTIVE_FAILURES configurable — Good suggestion for a follow-up. Keeping it simple for v1 to avoid over-engineering the config surface.

6. State remains after completion — The state is only read once by AppContainer (to show "Loop completed" message) and then becomes inaccessible via /loop status (which checks isActive). Next /loop start or /loop stop call will clean it up.

7. Richer tab completion — Agreed this could be improved later. Current completions cover the most common use cases.

Low

8-9. Readonly / @module — Accepted as-is. Readonly<> is sufficient for the current consumer pattern.

10. Null state test — ✅ Added in a1ab9df. New test verifies onIterationComplete doesn't throw when no loop is active.

11-12. Import grouping / safe integer — Imports follow existing project conventions. MAX_INTERVAL_MS (24h) keeps values well within safe integer range.

[wenshao]

Code Review & Fix Summary

经过多轮代码审查，发现以下问题并在 commit 26fbe265 中修复：

1. Race Condition — 用户消息与 loop 迭代竞态（中）

问题：loop 迭代通过 addMessage 和用户消息共享同一个 useMessageQueue。当 loop timer 在用户 AI 响应期间触发时，executeIteration 设 waitingForResponse=true 并通过 addMessage 排队，用户响应完成后 completion effect 误将用户响应当作 loop 迭代完成处理，loop prompt 的实际响应被忽略，导致 loop 行为错乱。

修复：loop 迭代使用独立的提交路径（loopSubmitRef + submitQueryRef），不再经过 useMessageQueue。新增 loopInitiatedStreamRef 区分 loop 和用户发起的 stream。

2. 嵌套 Slash 命令不一致（中）

问题：首次迭代通过 submit_prompt 返回 Part[]，绕过 isSlashCommand() 检查；后续迭代通过 addMessage 传入 string，会触发 slash 命令解析。如果 prompt 是 /review 等命令，首次作为纯文本发送，后续会被当作命令执行。

修复：所有迭代统一通过 Part[] 提交，与首次迭代路径一致。

3. 错误检测不可靠（中）

问题：仅检查 history 最后一条是否为 MessageType.ERROR。但 API 流式错误存在 pendingRetryErrorItem 中（不进入 history），tool 执行错误存为 tool_group 类型。大多数实际错误被漏判，连续失败自动暂停机制基本不生效。

修复：新增 pendingGeminiHistoryItems 检查 + 向后扫描 history 直到 MessageType.USER，捕获 ERROR 和 tool_group 中的 ToolCallStatus.Error。

4. 其他修复

• /btw 命令不再误清 loop flag（btw 是旁路命令，不影响主 stream）
• /loop stop 时丢弃 loopSubmitRef 中残留的排队 prompt
• 首次迭代 completion 通过 loopSubmitRef === null 判断为 loop 响应

Remaining Items (Low Priority)

• resume() 方法已实现但无 /loop resume UI 入口
• 8 个 i18n key 未添加到翻译文件（fallback 英文正常工作）
• getState() 返回 Readonly<LoopState> 但暴露可变引用（编译时约束足够）

[Copilot]

Pull request overview

Adds a new /loop CLI slash command backed by a framework-agnostic LoopManager in core, with CLI integration that schedules subsequent iterations when streaming completes.

Changes:

• Introduces LoopManager (+ interval parse/format helpers, singleton accessors) and unit tests in packages/core.
• Adds /loop command implementation in the CLI and registers it in BuiltinCommandLoader.
• Integrates loop iteration triggering/completion handling into AppContainer.

Reviewed changes

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

Show a summary per file

File	Description
packages/core/src/loop/loopManager.ts	Implements core loop state machine, interval helpers, and singleton accessors.
packages/core/src/loop/loopManager.test.ts	Adds Vitest coverage for parsing/formatting and loop lifecycle behavior.
packages/core/src/loop/index.ts	Exposes loop module exports.
packages/core/src/index.ts	Re-exports loop module from core public API.
packages/cli/src/ui/commands/loopCommand.ts	Implements /loop start/status/stop + interval bounds and completions.
packages/cli/src/ui/AppContainer.tsx	Wires loop iteration callback to prompt submission and marks completion on stream idle.
packages/cli/src/services/BuiltinCommandLoader.ts	Registers the new loop built-in command.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

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

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 16 out of 16 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 5 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wenshao]

PR vs Claude Code 功能对比

功能矩阵

功能	PR	Claude Code
多任务并发（最多 50）	✅	✅
命名循环 --id	✅	❌
迭代限制 --max N	✅	❌
/loop pause / resume	✅	❌
/loop status（含倒计时）	✅	❌
/loop stop（原子操作）	✅	❌（需 CronList→CronDelete）
/loop list	✅	❌（需 CronList 工具调用）
/loop restore	✅	❌（自动恢复）
指数退避（2x→4x）	✅	❌
连续失败自动暂停（3 次）	✅	❌
Safety timer（3s）	✅	❌
漂移保护（动态收敛）	✅	❌（固定 1s 轮询）
文件持久化	✅ v2 + v1 迁移	✅
多会话锁（PID+heartbeat）	✅	✅
Jitter 负载分散	✅ 10%/30s cap	✅ 10%/15min cap
自动过期	✅ 7 天（可配置，可禁用）	✅ 7 天（GrowthBook）
错过任务检测	✅	✅
Feature gate	✅ 4 项 settings	✅ GrowthBook+env
Trailing every 语法	✅	✅
亚分钟间隔（10s）	✅	❌（cron 最小 1 分钟）
--all 批量操作	✅	❌
Tab 补全	✅	❌
i18n 国际化	✅	❌
单元测试	✅ 119 tests	❌ 0 tests

PR 独有（Claude Code 没有的 12 项）

1. --id 命名循环 + --all 批量操作
2. --max N 迭代限制
3. pause / resume（手动 + 失败自动暂停）
4. 指数退避（2x/4x cap）
5. Safety timer（非 AI 命令防挂起）
6. /loop status（含 next fire 倒计时、过期时间）
7. /loop stop（原子操作，无需 job ID）
8. 漂移保护（动态收敛 vs 固定 1s 轮询）
9. 亚分钟间隔（10 秒 vs 1 分钟）
10. Tab 补全（子命令 + loop ID）
11. 119 个单元测试（5 个文件）
12. 设计文档 + 用户文档

Claude Code 独有（PR 没有的 3 项）

1. 自动恢复 — 启动时自动恢复，无需手动 /loop restore
2. GrowthBook 远程调控 — 运维秒级生效的 jitter/expiry 参数调整
3. One-shot 反向 jitter — 一次性任务提前触发（避免 :00/:30 峰值）

架构差异

	PR	Claude Code
调度引擎	setTimeout + 动态漂移保护	setInterval(1s) 轮询
用户接口	/loop 子命令（确定性解析）	LLM prompt → CronCreate 工具
最小粒度	10 秒	1 分钟（cron 限制）
空闲 CPU	零（timer 挂起）	每秒遍历所有任务

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 4 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[wenshao]

[Copilot]

Pull request overview

Copilot reviewed 18 out of 18 changed files in this pull request and generated 2 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tanzhenxin]

Closing in favor of #2731

Hi @wenshao — thank you for the thorough work on this PR. The implementation is well-engineered, with solid persistence, backoff, and multi-session coordination. However, after reviewing both approaches, we're going with #2731 and closing this one. Here's why:

1. Tool-based interface vs. slash-command-only
The most significant divergence. The target architecture exposes scheduling to the LLM via declarative tools (cron_create, cron_list, cron_delete), meaning the model can autonomously schedule, inspect, and cancel jobs as part of agentic workflows — not just when the user explicitly types /loop. The /loop skill is intentionally just syntactic sugar over these tools. Your PR keeps scheduling entirely in slash-command space, which fundamentally limits the model's ability to use scheduling as a capability during multi-step reasoning.

2. Integration breadth
PR #2731 integrates at all three execution levels (interactive CLI, non-interactive CLI, ACP session), whereas this PR focuses primarily on the interactive CLI path with a LoopManager singleton that would need additional work to support the other modes. The tool-based design in #2731 makes this multi-surface integration natural, since tools are already available across all execution contexts.

3. Scope and surface area
This PR adds features not present in the target design — pause/resume/restore lifecycle, named loops with --id, exponential backoff, --max iteration caps. While individually useful, they increase the API surface and maintenance burden without matching what the system expects. The simpler model in #2731 (create/list/delete, auto-expiry, fire-and-forget) aligns with the principle of keeping the scheduling layer thin and letting the LLM handle higher-level logic.

4. Scheduling primitive: cron expressions vs. setTimeout
The upstream design uses 5-field cron expressions as the scheduling primitive, which naturally maps to standard scheduling semantics and is what the storage format, tool interfaces, and human-readable display are all built around. The setTimeout approach enables sub-minute granularity but introduces drift-protection complexity and diverges from the cron model the rest of the system assumes.

Again, the engineering quality here is genuinely strong — the drift protection, FNV-1a jitter, and backoff logic are well thought out. Some of those ideas (particularly the backoff and persistence format) may be worth revisiting as enhancements to the merged approach. Thank you for the contribution.