📋 Review Summary

This PR implements a read-only daemon session task snapshot API (GET /session/:id/tasks) that allows web-shell to inspect background tasks while a prompt is streaming without interfering with the prompt queue. The implementation spans the ACP bridge, CLI server, SDK TypeScript client, and web-shell UI. Overall, the code is well-structured with good type safety, comprehensive test coverage, and follows existing project conventions. The design correctly separates concerns between layers and maintains the read-only, out-of-band nature of the endpoint.

🔍 General Feedback

• Positive architectural decisions: The implementation correctly keeps this as a read-only snapshot endpoint that bypasses the prompt FIFO queue, which is the core design goal. The separation between SERVE_STATUS_EXT_METHODS and SERVE_CONTROL_EXT_METHODS is a good pattern for distinguishing read-only vs mutation operations.
• Type safety: Excellent use of discriminated unions for task types (agent, shell, monitor) with exhaustive type checking via the never pattern in switch statements.
• Test coverage: Comprehensive unit tests across all layers (bridge, SDK, web-shell) with good edge case coverage.
• Documentation: Protocol documentation in qwen-serve-protocol.md clearly specifies the new endpoint and its constraints.
• Forward compatibility: Schema version (v: 1) and forward-compatible type patterns (e.g., string & {} for scope fields) follow the project's versioning conventions.

🎯 Specific Feedback

🟡 High

• File: packages/web-shell/client/utils/tasksCommand.ts:17-27 - The sanitizeTaskText function removes control characters but preserves ANSI escape sequences partially (it removes codes 0x7f-0x9f but ANSI color codes use \u001b[ sequences which start with 0x1b). The test at line 42 in tasksCommand.test.ts shows npm test[31m instead of the full escape sequence, suggesting the sanitization may not be fully effective. Consider using a more robust ANSI stripping library or a complete regex-based approach. Suggested fix: Use a regex like /\x1b\[[0-9;]*m/g to strip ANSI escape sequences completely, or leverage an existing library like ansi-regex that's already in the dependency tree.

🟢 Medium

• File: packages/cli/src/acp-integration/session/tasksSnapshot.ts:30-38 - The runtimeMs calculation uses Math.max(0, ...) which is defensive but the endTime ?? now pattern could produce misleading results for tasks that haven't been updated recently. If a task's endTime is never set but the task is no longer actually running, the runtime will keep growing. Suggested improvement: Add a comment explaining why this is acceptable (e.g., "Tasks are expected to have endTime set when completed; this is a defensive fallback for in-flight snapshots").

• File: packages/acp-bridge/src/status.ts:437-443 - The ServeSessionMonitorTaskStatus interface has ownerAgentId?: string as optional, which is good for forward compatibility, but there's no corresponding field in ServeSessionAgentTaskStatus to track child monitors. This asymmetry is probably intentional (the parent knows about children, not vice versa), but a brief comment would help future maintainers.

• File: packages/sdk-typescript/src/daemon/types.ts:815-820 - The DaemonSessionTasksStatus interface uses v: 1 literal instead of typeof STATUS_SCHEMA_VERSION like the bridge-side types. This creates a potential drift risk if the schema version is bumped in one place but not the other. Suggested fix: Import and use STATUS_SCHEMA_VERSION from the bridge package, or define the schema version constant in a shared location.

🔵 Low

• File: packages/cli/src/serve/server.ts:1430-1447 - The new /session/:id/tasks route handler follows the existing error handling pattern well. Consider extracting the session ID validation pattern (if (!sessionId) { res.status(400).json(...) }) into a shared helper since it's repeated across multiple route handlers. This is a minor consistency improvement, not a blocker.

• File: packages/web-shell/client/utils/tasksCommand.ts:107-117 - The error handling in handleTasksSlashCommand uses reportError(error, 'Failed to load tasks') but doesn't provide context about which session failed. Since this function doesn't have the session ID in its input, consider adding it for better debugging. Suggested enhancement: Add sessionId: string to the input parameter object.

• File: packages/web-shell/client/utils/tasksCommand.ts:91-96 - The output file path display uses fixed indentation ( output:) which may not align well for task IDs of varying lengths. This is a UI polish issue, not a functional problem.

• File: docs/developers/qwen-serve-protocol.md:899-907 - The protocol documentation shows an example with only an agent task type. Consider adding examples of shell and monitor task types to make the full schema clearer for API consumers.

✅ Highlights

• Excellent type design: The discriminated union pattern for task types with exhaustive checking (const _exhaustive: never = task) is textbook TypeScript best practice.
• Clean separation of concerns: The buildSessionTasksStatus function in tasksSnapshot.ts cleanly separates serialization logic from the HTTP layer, making it easy to test and reuse.
• Comprehensive test coverage: Tests cover empty task lists, control character sanitization, command dispatch, and the full SDK integration path. The test at bridge.test.ts verifying the status path bypasses the prompt queue is particularly important for the core design goal.
• Security-conscious: The whitelist approach to task serialization (explicitly naming fields rather than spreading objects) prevents accidental exposure of internal state. The comment at line 885 in qwen-serve-protocol.md explicitly calls out what is NOT exposed: "controllers, timers, offsets, pending messages, and raw registry objects are never exposed."
• Good error handling: Consistent use of sendBridgeError helper and proper error propagation through all layers.

Fix summary (58e1629)

Maintainer Verification Report

环境: macOS Darwin 25.4.0, Node.js v22.17.0
分支: codex/daemon-tasks-snapshot @ da3dbc31
测试时间: 2026-05-28

Build

Unit Tests

E2E: GET /session/:id/tasks (使用本地构建 + tmux)

通过 tmux 启动本地构建的 qwen serve --port 4171，进行完整 E2E 验证：

1. Capabilities 验证

✅ features 列表包含 "session_tasks"

2. 空状态查询

✅ GET /session/:id/tasks → {"v":1, "sessionId":"...", "now":..., "tasks":[]}

3. Background Shell Task 可见性 (核心场景)

发送 prompt 启动 sleep 30 && echo done 后台任务，在 prompt 完成后连续轮询 /tasks 端点：

✅ Poll 1: tasks=1 [shell] bg_70ab6685: sleep 30 && echo done status=running
✅ Poll 2: tasks=1 [shell] bg_70ab6685: status=running
✅ Poll 3: tasks=1 [shell] bg_70ab6685: status=running
...
✅ 完成后: status=completed, runtimeMs=30064, exitCode=0

关键验证: /tasks 端点在无 active prompt 时成功返回，绕过了 prompt FIFO 队列 (PR 核心目标)

4. 完整字段序列化

✅ {
  "kind": "shell", "id": "bg_70ab6685",
  "label": "sleep 30 && echo done",
  "status": "completed",
  "startTime": 1779930714150,
  "runtimeMs": 30064,
  "outputFile": "/Users/.../.qwen/tmp/.../shell-bg_70ab6685.output",
  "command": "sleep 30 && echo done",
  "cwd": "/Users/.../qwen-code-x2",
  "endTime": 1779930744214,
  "pid": 60492,
  "exitCode": 0
}

5. SDK Client 验证

✅ DaemonClient.sessionTasks(sessionId) → v=1, tasks=1, [shell] bg_70ab6685 status=completed

6. Edge Cases

结论

本 PR 功能验证通过，可以 merge。

核心目标 — web-shell 在 streaming 期间通过独立的 status 路径查询 background tasks snapshot，绕过 prompt FIFO — 已验证正常工作。涉及的 4 个包 (acp-bridge, cli, sdk, web-shell) 全部构建通过，750+ 单元测试全部通过，HTTP 端点/SDK/认证/边界情况均按预期工作。