RFC: Improve WorkHub recall within the 32 most recent Sessions

# RFC: Improve WorkHub recall within the 32 most recent Sessions

- **Status:** Discussion draft, not approved for implementation. Proposed behavior below is not current product behavior.
- **Date:** 2026-09-14
- **Code baseline:** `54bf16aaf`
- **Goal:** Give the coordinator inexpensive task semantics and retrieval evidence while preserving the existing time-based candidate boundary.

## 1. Problem and current behavior

WorkHub builds candidates from Session headers on the same Runtime Host. It excludes archived Sessions, the coordination Session, special-role Sessions, subagents, and side conversations, then takes at most 32 in descending activity order. Activity uses `lastMessageAt ?? statusUpdatedAt ?? createdAt`.

Candidate generation takes no query text. Candidates contain names, workspaces, states, timestamps, and identity references; the coordination layer adds delegation identities where available. They contain neither task-content summaries nor text-search results. Similar or generic names leave the model with little distinguishing evidence.

There are two selection paths: the main coordination model selects after calling `tasks.candidates`, or an optional separate Intent / Recall adapter binds a routing decision. Separate Recall receives the current request, intent classification, and bounded candidate metadata, but not coordination conversation history. The optional adapter must not be treated as already enabled by default.

Code references:

- [Candidate filtering, ordering, and truncation: candidateSet](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/workhub-coordination-action-gate.ts)
- [Candidate projection and optional routing preparation](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/workhub-coordination-coordinator.ts)
- [Recall inputs, prompts, and policy](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/core/src/workhub-routing.ts)
- [Coordination prompt and tool boundary](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/hosted-execution-tool-profile.ts)

## 2. Fixed boundaries

1. **Strictly preserve the candidate set of the 32 most recent eligible Sessions.** BM25 must not add older Sessions or replace time-based selection with repository-wide or Host-wide relevance retrieval.
2. BM25 is a low-weight supporting signal within that set. No match does not imply irrelevance and should not eliminate a candidate. The initial direction is to avoid a second candidate truncation.
3. Summaries support routing and only need to describe the broad task topic. Staleness is acceptable; they are not precise, continuously updated progress reports.
4. The coordinator combines conversational links, time, summaries, and retrieval evidence. Existing Action Gate checks, explicit-creation rules, and permission boundaries remain independent.
5. This RFC discusses evidence generation and consumption, not a change to the default routing strategy.

## 3. Option: Infrequent Session summaries

After WorkHub-delegated work has a durable execution result, trigger a background summary-update check for the target Session. Prefer a Host-side trigger driven by target execution facts rather than delivery to an open WorkHub window. Summary generation must not delay the work result or append an ordinary user Turn to the task.

A summary should capture the task objective, relevant subjects, and main topic, optionally retaining a few distinguishing conclusions. It need not track every Turn, and deciding whether to refresh should not require another model call.

One candidate schedule refreshes at cumulative effective completion counts of `1, 2, 4, 8, 16, ...`. Exponentially increasing intervals reduce long-term cost. This draft does not assume a time-based refresh or an interval cap. A topic change could make an old summary misleading; explicit invalidation or another cheap refresh condition remains open.

Generation can use the previous summary plus bounded new content. Large deltas still require a defined truncation policy: incremental input is not automatically cheap. Store the covered source-record position to support deduplication, restart recovery, and protection against older generation results overwriting newer versions.

The existing [HostSessionEffectCoordinator](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/session-effect-coordinator.ts) and [model-call authority](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/execution-model-authority.ts) provide tool-free recap capabilities worth evaluating for reuse. Recap is not currently an automatically maintained routing summary. Storage in a header field, a separate derived record, or an existing artifact remains undecided.

Open questions: Does a completion count refer to a delegated Message or an execution Turn? How do failures, stops, and shared recovery Turns count? Should ordinary tasks participate, or only WorkHub-delegated work? Sessions without summaries must remain routable without synchronous backfilling.

## 4. Option: BM25 within the 32 Sessions

```text
Existing eligibility filter + time ordering + at most 32 Sessions
→ Read bounded eventlog text from those Sessions
→ Run BM25 and aggregate by Session
→ Attach a weak relevance signal and a few matching excerpts
→ Coordinator decides
→ Existing Action Gate validates
```

Logs can supply keywords missing from titles and coarse summaries. The initial version should avoid a complex semantic-chunking, low-information classification, or deduplication pipeline, and avoid additional model calls.

One simple experimental option uses existing message boundaries: take a fixed number of recent user and assistant text messages per Session, cap each message's length, initially omit raw tool output, and use the highest message score as the Session score.

**This option is not selected yet.** It trades missing evidence for bounded cost: earlier details and error codes in tool output may be missed; a fixed message count does not mean fixed token cost; taking the maximum does not fully remove document-count effects or accidental matches.

Another simple comparison is one bounded text document per Session. It is more direct to implement, but multiple topics in a long task can dilute relevance. Compare examples before choosing; do not assume message-level retrieval is necessarily better.

### Scoring questions

- A prompt describing a signal as “low weight” cannot strictly control model reliance. Code-level scoring requires normalization, a bonus cap, and a defined interaction with time.
- Preserve the original time position so the coordinator can interpret recency references. No particular weighting formula or promise that the strongest lexical match ranks first is adopted yet.
- Tokenization for Chinese, English identifiers, paths, and error codes materially affects matches. Use real mixed-language requests to choose a simple implementation.
- The BM25 statistics corpus, index maintenance, and bounded-read strategy remain open. Regardless of how statistics are computed, results must come only from the current 32 candidates.
- A request such as “continue that one” can legitimately have no lexical match. Context-derived search terms and reference resolution in separate Recall need their own discussion; query expansion must not conceal missing context.
- Matching excerpts are data, never instructions or authorization.

## 5. Integration and consistency

Review both `tasks.candidates` and the optional Recall input projection so summaries and excerpts do not benefit only one path. Candidate discovery currently has no query parameter. Define whether the query comes from the admitted request or from tool input.

Retrieval adds evidence without redefining Session identity. The existing `candidateSetId` is derived from ordered candidate metadata and revalidated before writes. Avoid unnecessary invalidation caused solely by background summary updates or query-dependent scores, while retaining checks for real target changes. The versioning contract remains to be designed.

Duplicate terminal notifications must not increment completion counts twice. Summary generation for a Session should be coalesced or serialized. **Summary writes must not update the user-activity timestamp used for candidate ordering**, or background maintenance would change membership in the most recent 32.

Summary or retrieval failure should retain the existing metadata path and must not imply task creation.

## 6. Evaluation

Compare the same 32-candidate snapshots, requests, and model across:

1. Current name, workspace, state, and time baseline.
2. Baseline plus coarse summaries.
3. Baseline plus coarse summaries and low-weight BM25 evidence.

Include similar names, stale summaries, repetitive long logs, mixed-language terms, reference-only requests, no matches, and a target in time position 33. The last case verifies the fixed boundary; expanding retrieval is not a remedy in this RFC.

Measure correct-target rate, wrong-target rate, clarification rate, additional latency, bytes read, model input, and summary-call count. Do not assume an accuracy gain. If BM25 adds little value or increases misrouting, retaining summaries alone is an acceptable outcome.

## 7. Decisions for discussion

- Should we establish an infrequent-summary baseline before investing in BM25?
- Should initial BM25 use the best message score or one bounded document per Session? What text is included?
- Should weak relevance be encoded in code-level scoring or supplied as model evidence? What makes “low weight” verifiable?
- What is the unit of exponential summary counting, its initial scope, and the refresh behavior after topic changes?

These are open questions, not an approved implementation checklist.

---

中文原文（点击展开）

# RFC：WorkHub 最近 32 个 Session 内的召回增强

- 状态：讨论稿，未批准实施；以下候选方案不代表当前产品行为。
- 日期：2026-09-14
- 代码基线：`54bf16aaf`
- 讨论目标：在保持时间候选边界的前提下，给协调模型补充足够便宜的任务语义与检索证据。

## 1. 问题与现状

WorkHub 当前从同一 Runtime Host 的 Session headers 构造候选：排除已归档、协调会话、特殊 role、子 Agent 与 side conversation，按最近活动降序取最多 32 个。活动时间使用 `lastMessageAt ?? statusUpdatedAt ?? createdAt`。

候选生成不接收查询文本。基础信息只有任务名称、工作区、状态、时间和身份引用，协调层另外补充存在时的委派标识；没有任务内容摘要或正文检索结果。名称相似或过于笼统时，模型缺少区分证据。

当前存在两条选择路径：主协调模型调用 `tasks.candidates` 后选择；或通过可选的独立 Intent / Recall 模型绑定路由决定。独立 Recall 仅收到当前请求、意图分类和有界候选元数据，没有协调对话历史。不能把可选适配器视为已默认启用。

代码入口：

- [候选筛选、排序和截断：candidateSet](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/workhub-coordination-action-gate.ts)
- [候选投影与可选路由准备](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/workhub-coordination-coordinator.ts)
- [Recall 输入、提示词和 Policy](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/core/src/workhub-routing.ts)
- [协调模型提示词和工具边界](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/hosted-execution-tool-profile.ts)

## 2. 已明确的边界

1. **严格保留最近 32 个 Session 的时间候选集合。** BM25 不从集合外补入旧任务，也不做全库相关性替代时间召回。
2. BM25 是集合内部低权重的辅助信号。零命中不等于不相关，不应据此淘汰候选；初步方向是不再做第二次候选截断。
3. 摘要服务于路由，只需粗略描述任务主题。允许陈旧，不要求维护精确的最新进度报告。
4. 协调模型结合对话关联、时间、摘要和检索证据选择目标；既有 Action Gate、显式新建规则与权限边界保持独立。
5. 本 RFC 讨论证据如何生成和使用，不宣布路由默认策略切换。

## 3. 候选方案：低频 Session 摘要

在 WorkHub 委派工作获得持久执行结果后，为目标 Session 触发一次后台摘要更新检查。建议触发点位于 Host，由目标执行事实驱动，而不是依赖 WorkHub 窗口收到结果。摘要生成不阻塞工作结果返回，不在任务中追加普通用户轮次。

摘要以任务目标、涉及对象和主要工作主题为核心，可保留少量识别性结论。无需逐轮同步进展，也无需为更新判断再调用一个模型。

频率的候选规则是：累计有效完成次数到 `1、2、4、8、16…` 时更新。指数间隔符合长期使用时降低成本的目标；本稿不默认加入固定时间刷新或间隔上限。中途主题改变可能导致摘要失真，是否提供显式失效或其他便宜的刷新条件仍需讨论。

生成输入可以是旧摘要与新增的有界内容。若增量过大，需要明确截断方法，不能假定“增量”天然便宜。摘要应携带覆盖到的源记录位置，以支持去重、重启恢复和防止旧生成结果覆盖新版本。

现有 [HostSessionEffectCoordinator](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/session-effect-coordinator.ts) 和 [模型调用能力](https://github.com/apache/maka/blob/54bf16aaff0d2f35a9461201d1b7d2a46fdf7710/packages/runtime-host/src/server/execution-model-authority.ts) 已有 tool-free recap，可评估复用；现有 recap 不等同于自动维护的路由摘要。字段落在 header、独立派生记录还是现有 artifact 中，尚未决定。

开放问题：一次“完成”按委派消息还是执行 Turn 计数？失败、停止、共享恢复 Turn 如何处理？仅 WorkHub 委派触发，还是普通任务也参与？没有摘要的任务保持可路由，不要求同步补全。

## 4. 候选方案：32 个 Session 内的 BM25

```text
现有筛选 + 时间排序 + 最多 32 个 Session
→ 读取这些 Session 的有界 eventlog 文本
→ BM25 检索并按 Session 汇总
→ 附加弱相关性信号与少量命中片段
→ 协调模型判断
→ 既有 Action Gate 校验
```

希望利用日志补充标题和粗摘要缺失的关键词，但不在第一版引入复杂的语义切片、自动低信息识别、去重流水线或额外模型调用。

一个可实验的简化选项：直接沿用现有消息边界，每个 Session 取最近固定条数的用户与 assistant 文本，每条限制长度，暂不纳入原始工具输出；计算消息得分后，Session 只取最高命中分。

**该选项尚未选定。** 它以可控成本换取证据遗漏：较早细节和工具输出中的错误码可能无法命中；固定条数不等于固定 token 成本；取最高分也无法彻底消除日志数量差异和偶然命中的影响。

另一个应对照的简单选项是每个 Session 取固定文本预算作为一个文档。它实现更直接，但长任务的多个主题可能互相稀释。通过样例比较后再选择，不预设分片方案必然更好。

### 评分需要明确的事

- “低权重”若只写进模型提示词，无法严格限制模型对该信号的依赖；若在代码里赋分，需要定义归一化、加分上限，以及如何与时间结合。
- 保留原始时间位置，让最终模型仍能识别“刚才、最近”的线索。暂不承诺某个权重公式或最高相关任务必定排首位。
- 中文、英文标识符、路径、错误码的分词会显著影响有效命中，需要用真实混合语言请求选择简单实现。
- BM25 的统计语料范围、索引更新与有界读取方式待定；无论统计如何实现，搜索结果只能来自本次 32 个候选。
- 查询若只有“继续刚才那个”，可以自然零命中。是否利用协调上下文生成检索词，以及独立 Recall 的指代信息如何传递，需要单独讨论，不能靠扩大检索词掩盖上下文丢失。
- 命中片段作为数据呈现，不赋予指令或授权地位。

## 5. 接入与一致性

摘要和命中片段需要同时检查 `tasks.candidates` 与可选 Recall 的输入投影，避免只在一条路径生效。候选发现接口当前没有查询参数，查询应从本次已接纳请求提取还是由工具提供，需要明确接口合同。

检索是附加证据，不重新定义 Session 身份。当前 `candidateSetId` 基于有序候选元数据生成，写入时重验；应避免仅因后台摘要更新或查询相关得分变化就无谓地使候选集合失效，同时保留真实目标变化的校验。具体版本策略待设计。

重复终态通知不重复计数，同一 Session 的摘要生成应合并或串行处理。摘要写入不应更新用于候选排序的用户活动时间，否则后台维护会改变最近 32 个的组成。摘要和检索失败时，应保留现有元数据路径，不能隐式新建任务。

## 6. 如何判断值得实现

使用相同的 32 个候选快照、请求和模型，对照：

1. 当前名称、工作区、状态和时间基线。
2. 基线 + 粗摘要。
3. 基线 + 粗摘要 + 低权重 BM25 证据。

覆盖同名任务、陈旧摘要、长日志重复内容、中英混合词、纯指代请求、零命中，以及目标位于时间第 33 位的情况。最后一项验证边界保持，不以扩大召回作为修复。

观察正确目标率、误选率、澄清率，以及额外延迟、读取量、模型输入和摘要调用次数。不预设准确率收益；如 BM25 增量很小或增加误选，可以只保留摘要。

## 7. 本轮讨论希望收敛的决策

- 是否先做低频摘要并建立基线，再决定 BM25 的投入？
- BM25 初版使用消息最高分还是每 Session 一个有界文档？文本范围如何限定？
- 弱相关性信号由代码赋分还是作为模型参考？“低权重”的可验证含义是什么？
- 指数摘要的计数单位、首轮范围，以及主题改变时是否需要刷新？

本文保留这些问题为开放讨论，不把探索性方案转写为已批准的实施清单。

Start with candidateSet in packages/runtime-host/src/server/workhub-coordination-action-gate.ts, then read the coordinator, routing, and hosted execution tool profile references. This is an unapproved discussion draft with multiple open design questions, so first compare the summary and BM25 options and seek a decision before implementation; no concrete done criteria are established.

Written by the indexing model from the issue text.