feat: quick-query lane for read-only backend lookups (roadmap P1, Q1-Q5) - design proposal

[ngoanpv]

Background

Roadmap P1 (Q1–Q5) identifies the biggest missing link to the backend: today the only path is the async task queue, so a read-only, answerable-in-seconds question like "how do I configure MCP for OpenClaw?" degrades into filing a ticket — the user hears "task accepted" instead of an answer. The roadmap explicitly marks Q4 as touching architecture invariants and requiring design review, so I'm opening this proposal before any PR.

Precedent already in the tree: get_agent_task_status creates a hidden, high-priority control query through the coordinator (session_status) that waits behind an already-running coordinator turn but ahead of ordinary queued Work, with the result delivered through the announcement path. The proposal below generalizes exactly that mechanism.

Proposed design

Q1 — lane semantics

• A quick query never creates a user-visible Work item and never enters the owner FIFO tail. It slots behind the running coordinator turn, ahead of ordinary queued Work — same position as the existing status control query.
• Read-only only: look something up, explain usage, check state. Anything that writes, executes, or produces a deliverable stays with spawn_thinking.
• Latency cap (proposal: 15s). On timeout the query is promoted to an ordinary Work item, the user is told it's taking longer, and the eventual result arrives through the normal announcement path — so the worst case degrades exactly to today's behavior, never worse.
• The frontend bridges with a natural half-sentence ("let me check that"), and the result re-enters the conversation through the announcement path, reusing safe-window insertion and retry.
• If the user interrupts or starts a new turn while a quick query is in flight, the dangling query is dropped (no orphaned announcements).

Q2 — ACP adapter: generalize the control-query mechanism (coordinator session reuse, priority insertion, result correlation) from the session_status-specific code into a parameterized read-only query.

Q3 — frontend tool: new quick_lookup(question) tool plus PROMPT.md routing rules: quick for read-only factual/usage/state questions the backend can answer from knowledge or cheap inspection; spawn_thinking for anything else. When the backend is unavailable, the tool reports it and the model answers from its own knowledge with that caveat.

Q4 — architecture docs: §2 flow diagram gains the quick lane; §3 tool list gains quick_lookup. This issue is the review request for that invariant change.

Q5 — tests: priority insertion ahead of queued Work but behind the running turn; timeout promotion to Work; drop-on-interrupt; backend-unavailable fallback.

Open questions

1. Is 15s the right cap, and should it be configurable?
2. Should quick queries be observable anywhere (timeline/log) even though they create no user-visible Work, for debugging?
3. Concurrency: one in-flight quick query per owner (queue or reject the second)?
4. Should promotion-on-timeout create the Work silently, or only after telling the user?

I'll build a prototype on my fork in parallel and open the PR once the design is confirmed or adjusted here. Feedback very welcome — especially on the invariant implications in §2/§3.

[x-lixu]

感谢这份高质量的设计提案 👍

它与我们 roadmap 中的 P1 - 快速通道（backend quick query） 规划高度一致（见 docs/frontend-agent-roadmap.md）：你对 get_agent_task_status hidden control query 先例的定位、lane 语义（不建可见 Work、优先级插队、只读限定、延迟上限超时降级为正式 Work）的分析，与 roadmap Q1–Q3 的设计方向基本吻合。

几点说明：

1. 该方向已进入 roadmap，会按 Q1→Q5 推进；其中 Q4 涉及架构不变量，按 roadmap 要求需要明确的设计评审后才会动 architecture.md。
2. 你提案中的 15s 延迟上限与超时降级路径（最坏情况不劣于现状）正是我们倾向的兜底策略。
3. 在 Q1 设计定稿前暂不接受实现类 PR；设计评审有结论后会回到这里同步，也欢迎继续在本 issue 讨论细节（如 quick/spawn_thinking 的路由判定规则）。

再次感谢这么认真的前期调研。

[ngoanpv]

Thanks for the quick and thorough response — glad the direction matches Q1–Q3, and understood on holding implementation PRs until the Q1 design is finalized. I'll keep prototype exploration on my fork and bring nothing here until the review concludes.

Taking up the routing-rules invitation, here's a concrete proposal for the quick vs spawn_thinking decision, written so it can drop into PROMPT.md wording and test cases directly.

Route to quick_lookup only when all four hold:

1. Question, not directive — the user asks to know something, not to change, produce, or operate anything. Imperative intent always routes to spawn_thinking, even when the underlying action is cheap.
2. Read-only sourcing — the expected answer comes from knowledge, documentation/config lookup, or cheap inspection. No file writes, app control, code execution, or generated deliverables.
3. Voice-sized answer — the result is a short factual statement consumable in speech. "Briefly explain how X works" qualifies; "write me a guide for X" is a deliverable → spawn_thinking.
4. Not about prior Work — anything referencing earlier submitted work stays with get_agent_task_status, unchanged.

Ambiguity defaults to spawn_thinking. The asymmetry justifies it: misrouting a write into the quick lane must be impossible, while misrouting a question into spawn_thinking merely costs latency — exactly today's behavior. The quick lane stays a pure optimization with no new failure mode.

Worked examples (candidate PROMPT.md examples / test oracle):

Utterance	Route	Why
"OpenClaw 怎么配 MCP？"	quick	usage question, knowledge/docs
"帮我把 MCP 配好"	spawn_thinking	directive, writes config
"今天美元兑人民币多少？"	quick	read-only current fact
"我项目里用到 lodash 了吗？"	quick	cheap read-only inspection; timeout guard covers big repos
"上个任务做完了吗？"	get_agent_task_status	prior Work
"把查到的汇率存个文件"	spawn_thinking	write follows the lookup
"现在几点？"	get_current_time	frontend-local, no backend

One datapoint this exercise surfaced for open question 3 (concurrency): in voice, a follow-up quick question while one is in flight is natural ("那 OpenCode 呢？"). Queuing a second one (cap at 2, drop-oldest on interrupt) may fit conversation flow better than rejecting it. No strong opinion — flagging it for the Q1 decision.

Happy to go deeper on any of this, or on the timeout/observability questions, whenever useful for the review.

[x-lixu]

Excellent routing ruleset — thank you!

This formulation is exactly what the Q1 design review needs. A few observations from our side:

1. The four conditions are sound and directly testable. Conditions 1 (question vs directive) and 2 (read-only sourcing) mirror the safety boundary we care about most: the quick lane must never be a channel through which a mutation slips in. We'll encode these as explicit test cases in the routing spec.
2. The asymmetry argument is the right one. Misrouting a write into the quick lane is a correctness failure; misrouting a question into spawn_thinking is merely today's latency. Defaulting ambiguity to spawn_thinking keeps the quick lane a pure latency optimization with zero new failure modes — we'll keep this principle verbatim in the design doc.
3. One area worth pinning down during Q1: the boundary between condition 2's "cheap inspection" and operations that read but have side effects (e.g. anything that increments a counter, touches rate limits, or changes backend state like "check my quota"). We'll likely add an explicit allowlist rather than relying on model judgment for condition 2.

Nothing further needed from your side for now — the prototype work on your fork is the perfect place to keep exploring. We'll reference this comment thread when the Q1 routing spec goes to review, and ping you here with the conclusions.