What would you like to be added?
Add a read-only daemon API and TypeScript SDK method that return authoritative live session-state snapshots for several explicitly selected registered workspaces in one HTTP request. This is a proposed new capability, not an API that exists today; the route name, method, and response envelope are open to maintainer design.
Suggested behavior:
- Return a complete, memory-only snapshot for each selected workspace, with its canonical identity and the same session fields and
catalogVersion semantics as GET /workspaces/:workspace/sessions/live-state. Running and waiting transitions must appear in the snapshot even when catalogVersion is unchanged.
- Isolate failures per workspace. Unknown, untrusted, removed, or transitioning members should have explicit errors; a valid member should still succeed. An error must not look like a successful empty
sessions array, and an unknown selector must not fall back to the primary workspace.
- Preserve the existing workspace trust and runtime-generation boundaries. Reading the batch must not scan persisted catalogs, start ACP children, boot cold runtimes, or perform writes. A runtime replaced during the read must not yield a misleading successful member.
- Bound selected member count, concurrency, and response size. Use the read quota with clear per-workspace attribution. Advertise a distinct capability and provide an SDK method with cancellation; older daemons can keep using the single-workspace snapshot route.
The batch does not need a globally atomic snapshot across workspaces or a merged session feed. Existing single-workspace behavior should remain unchanged.
Why is this needed?
The current live-state API requires one request per workspace. The Web Shell polls each selected workspace at a default five-second interval: ten workspaces produce roughly 120 recurring snapshot requests per minute per client, before local refreshes and other reads. Each snapshot is inexpensive and memory-only, but HTTP and gateway requests still scale with workspace count.
#12249, delivered by #12254, batches persisted session catalogs. That route may scan stored history and is unsuitable for frequent execution-state refreshes. #11327 proposes workspace live-state SSE; its triage comment suggests batch reads as a smaller stateless option. This request tracks that option separately. If SSE is added later, a batch snapshot can also support initial state, reconciliation, and fallback.
Additional context
Source inspection of upstream main at 114be08f70726d1028eace3eb4137a32b6d9d686:
Acceptance scenarios: primary and secondary workspaces in one response; running → waiting → running → idle; a valid member beside an unknown, untrusted, or unavailable member; removal or runtime replacement during a read; capability fallback on an older daemon. Verify that one batch replaces N HTTP requests without adding persisted-storage or ACP work. This is a source-based feature proposal, not a tested batch implementation.
中文说明
希望增加什么能力？
为 daemon 增加只读接口和 TypeScript SDK 方法，在一次 HTTP 请求中读取多个显式选定、已注册 workspace 的权威会话运行状态快照。这是待新增能力，具体路由、方法和响应格式由维护者设计。
建议行为：
- 每个 workspace 返回完整、仅来自内存的快照，包含规范化归属身份，并沿用现有
GET /workspaces/:workspace/sessions/live-state 的会话字段和 catalogVersion 语义。运行、等待状态变化即使不推进 catalogVersion，也必须体现在快照中。
- 各 workspace 的失败相互隔离。未知、不可信、已移除或过渡中的成员返回明确错误，其他有效成员仍可成功；错误不能伪装成成功的空
sessions，未知 selector 不能回退到 primary。
- 保持现有信任与 runtime generation 边界。批量读取不扫描持久目录、不启动 ACP 子进程或冷 runtime，也不执行写入；读取期间 runtime 被替换时不能返回误导性的成功结果。
- 限制成员数、并发和响应大小，使用读取额度并明确各 workspace 的归属。公布独立 capability，SDK 支持取消；旧 daemon 的客户端继续使用单 workspace 快照接口。
无需跨 workspace 的全局原子快照或合并会话列表；现有单 workspace 行为保持不变。
为什么需要？
当前运行状态接口每个 workspace 各发一次请求。Web Shell 默认每 5 秒查询一次选定的 workspace：10 个 workspace 约产生每客户端每分钟 120 次周期性快照请求，尚未计入本地操作刷新及其他读取。单次快照只读内存、成本较低，但 HTTP 和网关请求数仍随 workspace 数量增长。
#12249 / #12254 解决的是持久会话目录批量读取，可能扫描磁盘历史，不适合作为高频运行状态查询。#11327 提议 workspace 状态 SSE，其分流意见建议先考虑批量读取这一较小的无状态方案。本 Issue 单独追踪该方案；未来若增加 SSE，批量快照也可用于初始状态、校准与降级。
当前依据与验收场景
上述固定提交的源码显示：现有运行状态接口一次只返回一个 workspace，Web Shell 也逐 workspace 查询。建议验证：一次返回 primary 和 secondary；运行 → 等待 → 运行 → 空闲；有效成员与未知、不可信或不可用成员并存；读取期间 workspace 移除或 runtime 替换；旧 daemon 的能力回退。应确认一次批量请求替代 N 次 HTTP 请求，且不增加持久存储或 ACP 工作。这是基于源码的功能建议，尚无批量实现的运行验证。
What would you like to be added?
Add a read-only daemon API and TypeScript SDK method that return authoritative live session-state snapshots for several explicitly selected registered workspaces in one HTTP request. This is a proposed new capability, not an API that exists today; the route name, method, and response envelope are open to maintainer design.
Suggested behavior:
catalogVersionsemantics asGET /workspaces/:workspace/sessions/live-state. Running and waiting transitions must appear in the snapshot even whencatalogVersionis unchanged.sessionsarray, and an unknown selector must not fall back to the primary workspace.The batch does not need a globally atomic snapshot across workspaces or a merged session feed. Existing single-workspace behavior should remain unchanged.
Why is this needed?
The current live-state API requires one request per workspace. The Web Shell polls each selected workspace at a default five-second interval: ten workspaces produce roughly 120 recurring snapshot requests per minute per client, before local refreshes and other reads. Each snapshot is inexpensive and memory-only, but HTTP and gateway requests still scale with workspace count.
#12249, delivered by #12254, batches persisted session catalogs. That route may scan stored history and is unsuitable for frequent execution-state refreshes. #11327 proposes workspace live-state SSE; its triage comment suggests batch reads as a smaller stateless option. This request tracks that option separately. If SSE is added later, a batch snapshot can also support initial state, reconciliation, and fallback.
Additional context
Source inspection of upstream
mainat114be08f70726d1028eace3eb4137a32b6d9d686:Acceptance scenarios: primary and secondary workspaces in one response; running → waiting → running → idle; a valid member beside an unknown, untrusted, or unavailable member; removal or runtime replacement during a read; capability fallback on an older daemon. Verify that one batch replaces N HTTP requests without adding persisted-storage or ACP work. This is a source-based feature proposal, not a tested batch implementation.
中文说明
希望增加什么能力？
为 daemon 增加只读接口和 TypeScript SDK 方法，在一次 HTTP 请求中读取多个显式选定、已注册 workspace 的权威会话运行状态快照。这是待新增能力，具体路由、方法和响应格式由维护者设计。
建议行为：
GET /workspaces/:workspace/sessions/live-state的会话字段和catalogVersion语义。运行、等待状态变化即使不推进catalogVersion，也必须体现在快照中。sessions，未知 selector 不能回退到 primary。无需跨 workspace 的全局原子快照或合并会话列表；现有单 workspace 行为保持不变。
为什么需要？
当前运行状态接口每个 workspace 各发一次请求。Web Shell 默认每 5 秒查询一次选定的 workspace：10 个 workspace 约产生每客户端每分钟 120 次周期性快照请求，尚未计入本地操作刷新及其他读取。单次快照只读内存、成本较低，但 HTTP 和网关请求数仍随 workspace 数量增长。
#12249 / #12254 解决的是持久会话目录批量读取，可能扫描磁盘历史，不适合作为高频运行状态查询。#11327 提议 workspace 状态 SSE，其分流意见建议先考虑批量读取这一较小的无状态方案。本 Issue 单独追踪该方案；未来若增加 SSE，批量快照也可用于初始状态、校准与降级。
当前依据与验收场景
上述固定提交的源码显示：现有运行状态接口一次只返回一个 workspace，Web Shell 也逐 workspace 查询。建议验证：一次返回 primary 和 secondary；运行 → 等待 → 运行 → 空闲；有效成员与未知、不可信或不可用成员并存；读取期间 workspace 移除或 runtime 替换；旧 daemon 的能力回退。应确认一次批量请求替代 N 次 HTTP 请求，且不增加持久存储或 ACP 工作。这是基于源码的功能建议，尚无批量实现的运行验证。