work-ally 0.2.0-alpha.1

package/docs/completed/SPEC-group-chat-sender-identity.md

@@ -0,0 +1,301 @@
+# Group Chat Sender Identity Spec
+
+## Status
+
+- Target project: `work-ally`
+- Audience: implementation engineer
+- Scope: Feishu channel, for future group-chat enablement
+- Goal: preserve speaker identity in group-chat prompts sent to Codex
+- Status: implemented; group-chat now follows minimal explicit-trigger policy
+
+## Summary
+
+This spec defines one feature for future Feishu group-chat support:
+
+- private chat: do not add sender identity metadata to the prompt
+- group chat: always add sender identity metadata to the prompt
+
+The problem is not whether `work-ally` can see the sender identity. It already can.
+The problem is that the current prompt builder ignores that identity and sends only the raw message text to Codex.
+
+That is acceptable in private chat, but it is not sufficient for a future group thread where multiple people may speak in the same topic.
+
+## Background
+
+`work-ally` currently targets Feishu private chat only. The inbound Feishu normalization path already captures:
+
+- `senderId`
+- `senderName`
+- `conversationRef.chatType`
+
+However, current prompt construction still reduces an inbound message to:
+
+- `message.text.trim()`
+
+That means the bridge currently discards speaker identity at prompt time.
+
+For a one-person private chat, this is mostly fine because the human speaker is effectively constant.
+
+For a future group-chat thread, this becomes a correctness problem.
+
+If two or more humans speak inside the same thread and Codex only sees raw message text, it cannot reliably tell:
+
+- who is asking a question
+- who is correcting an earlier statement
+- whether two consecutive messages came from the same person or from different people
+
+## Problem Statement
+
+In a future Feishu group-chat thread, multiple humans may participate in the same topic. If `work-ally` forwards only raw message text to Codex, the model loses speaker attribution.
+
+Without speaker attribution, these become ambiguous:
+
+```text
+Can you summarize the plan?
+Actually focus on timeline risk.
+```
+
+This could mean:
+
+- one user refining their own request
+- a second user redirecting the discussion
+- two stakeholders disagreeing
+
+The model needs to know who said what.
+
+## Current State In `work-ally`
+
+### What already exists
+
+`work-ally` can already distinguish chat type and sender identity at the channel-normalization layer.
+
+Relevant files:
+
+- `work-ally/bridge/src/channels/feishu/normalize.ts`
+- `work-ally/bridge/src/types.ts`
+- `work-ally/bridge/src/receiver.ts`
+
+Current behavior:
+
+- `senderName` is read from Feishu inbound payloads
+- `senderId` is preserved in the normalized message object
+- `chatType` is stored in `conversationRef.chatType`
+- prompt construction ignores all of the above and uses only message text
+
+### Current shipped boundary
+
+Feishu normalization now accepts `group`, but the adapter only forwards a minimal safe subset of group traffic: explicit calls, control commands, or direct replies to assistant messages.
+
+## Feature Goal
+
+Define a stable prompt format so that every accepted group message delivered to Codex contains speaker identity metadata.
+
+The intended rule is:
+
+- private chat: unchanged prompt behavior
+- group chat: identity-aware prompt behavior
+
+## Non-goals
+
+This feature now participates in shipped group-chat behavior, but only under the minimal explicit-trigger policy described above.
+
+This feature does not define:
+
+- group access control
+- mention gating
+- group session routing
+- topic/thread selection rules
+- outbound response formatting for groups
+
+Those can be handled separately.
+
+## Why This Feature Is Needed
+
+### 1. Group-chat reasoning requires speaker attribution
+
+The model must know whether a new message came from:
+
+- the same person as before
+- a different person with a different role
+- a participant responding to another participant rather than to the assistant
+
+Without speaker identity, the model’s understanding of the thread is materially weaker.
+
+### 2. The required data is already available
+
+This is not blocked on platform capability.
+
+Feishu already provides sender identity, and `work-ally` already captures it during normalization.
+
+So the feature is mainly a prompt-design and plumbing task.
+
+### 3. Private chat does not need the same treatment
+
+Always adding sender identity to every prompt would add noise in private chat.
+
+The right policy is asymmetric:
+
+- private chat stays minimal
+- group chat carries identity metadata
+
+## Product Requirement
+
+### Private chat rule
+
+For Feishu `p2p` / `single` conversations:
+
+- keep the prompt content-first
+- do not prepend sender identity metadata
+
+### Group chat rule
+
+For Feishu `group` conversations:
+
+- prepend sender identity metadata before the original message body
+- include both display name and stable sender id when possible
+
+This is mandatory for group-chat prompts.
+
+## Recommended Prompt Shape
+
+Do not rewrite the message inline as `Allen: <message>`.
+
+That approach mixes metadata into user content and is harder to evolve.
+
+Instead, use a small structured envelope.
+
+Recommended group-chat prompt shape:
+
+```text
+Channel: Feishu
+Chat type: group
+Sender: Allen
+Sender ID: ou_xxx
+
+Message:
+请你总结一下这个方案的风险
+```
+
+This format keeps speaker metadata separate from the user’s original content.
+
+## Sender Identity Rules
+
+For group prompts:
+
+1. Use `senderName` when present and non-empty.
+2. Fall back to `senderId` if no display name is available.
+3. Always include `senderId` somewhere in the metadata block for disambiguation.
+
+Reason:
+
+- two people may share the same visible name
+- display names can change
+- some events may not provide a useful human-readable name
+
+## Technical Route
+
+### Step 1. Keep chat type and sender fields in normalized contracts
+
+This mostly already exists.
+
+The implementation should verify that future group-chat acceptance preserves:
+
+- `message.senderId`
+- `message.senderName`
+- `message.conversationRef.chatType`
+
+No major redesign is required here.
+
+### Step 2. Implement the policy in `Receiver.buildPrompt()`
+
+The current prompt builder is the correct control point.
+
+Recommended logic:
+
+- if `chatType` is `group`, return the structured identity envelope
+- otherwise return `message.text.trim()`
+
+This keeps the feature centralized and avoids channel adapters mutating the message body directly.
+
+### Step 3. Do not overwrite raw inbound text
+
+The normalized `message.text` should remain the original extracted inbound text.
+
+Identity metadata should be added only at prompt-construction time.
+
+This preserves:
+
+- archive fidelity
+- debugging clarity
+- future reuse of the raw text for other features
+
+### Step 4. Keep archives and diagnostics understandable
+
+Current archives already store inbound `senderId` and `text`.
+
+If needed, future work may additionally record the final prompt envelope used for the turn. That is optional for this feature, but the implementation engineer should keep debuggability in mind.
+
+## Acceptance Criteria
+
+- private chat prompts remain unchanged
+- group chat prompts always include speaker identity metadata before the message body
+- group chat prompts include `senderName` when available
+- group chat prompts fall back cleanly to `senderId` when `senderName` is absent
+- group chat prompts still include `senderId` even when `senderName` exists
+- the feature does not mutate the raw inbound `message.text`
+- the prompt format is consistent across group turns
+
+## Testing Guidance
+
+### Unit tests to add or revise
+
+- `work-ally/tests/unit/channel/feishu-normalize.test.mjs`
+  - ensure `senderName`, `senderId`, and `chatType` remain preserved
+  - ensure accepted group events keep normalized sender identity intact
+
+- receiver-level prompt tests
+  - private chat returns `message.text.trim()` only
+  - group chat returns structured identity envelope
+  - missing `senderName` falls back to `senderId`
+  - group prompt contains both display name and stable id when available
+
+### Manual verification checklist
+
+- send a private message and confirm the prompt does not include sender metadata
+- simulate a group message from user A and confirm the prompt identifies A
+- simulate a second group message from user B in the same thread and confirm the prompt identifies B distinctly
+- test duplicate display names and confirm `senderId` remains available in the prompt metadata
+
+## Risks And Tradeoffs
+
+### Token overhead
+
+Adding sender metadata increases token count slightly.
+
+This is acceptable in group chat because the information is necessary for correct multi-speaker reasoning.
+
+### Context pollution risk
+
+If implemented as `Name: message`, metadata can blur into the message body.
+
+That is why this spec recommends a structured metadata block instead of inline prefix mutation.
+
+### Future compatibility
+
+This structured format composes cleanly with future features such as:
+
+- quoted-message context
+- mention-based routing
+- per-speaker rules
+- richer group session policies
+
+## Final Recommendation
+
+Implement this as a prompt-envelope feature with one strict rule:
+
+- private chat: no sender metadata
+- group chat: sender metadata is mandatory
+
+The sender metadata should be added in the prompt builder, not baked into normalized raw message text.
+
+This gives future group-chat threads the minimum identity fidelity required for Codex to reason correctly about multi-person conversations without unnecessarily polluting private-chat prompts.

package/docs/completed/SPEC-middleware-exception-visibility.md

@@ -0,0 +1,227 @@
+# Middleware Exception Visibility
+
+## Status
+
+- Target project: `work-ally`
+- Audience: product owner / implementation engineer
+- Scope: bridge / channel / runtime abnormal-path visibility for Feishu-facing users
+- Status: shipped baseline / 2026-03-16
+- Goal: ensure the middleware never silently swallows failures that matter to the user
+
+## Summary
+
+`work-ally` 作为中间层，正常路径可以轻量，但异常路径必须透明。
+
+最近真实问题已经证明：
+
+- 消息可能进桥了
+- 中间层内部可能报错了
+- 用户面前却只看到“没人理我”
+
+这对中间层是不可接受的。
+
+一句话：
+
+> 只要用户已经把消息交给中间层，中间层就不能再让用户靠猜来判断发生了什么。
+
+## Background
+
+近期真实使用里暴露出两个典型问题：
+
+1. 消息进入 `handleInbound` 后，因为中间层内部异常，没有成功产出任何对用户可见的反馈
+2. 某些异常只写进日志，没有及时回告坐在飞书前的人类
+
+这直接暴露出一个产品缺口：
+
+- 中间层把异常“吃在内部”了
+- 用户既无法绕过中间层确认真相，也无法判断是消息没收到、处理中、恢复中，还是已经失败
+
+## Problem Statement
+
+当前异常透明度不足主要体现在四类场景。
+
+### 1. Message accepted, but no visible outcome
+
+消息已经被桥接层接住，但随后：
+
+- 发送链路异常
+- 状态文件损坏
+- runtime / bridge 局部错误
+
+导致这轮没有对用户产生任何明确结果。
+
+### 2. Failure exists only in logs
+
+中间层知道：
+
+- delivery unavailable
+- reaction 发送失败
+- runtime 恢复失败
+- receipt / dedupe 异常
+
+但用户不知道。
+
+### 3. Retry semantics are inconsistent
+
+如果本轮处理中途失败：
+
+- 用户期望系统要么明确告知失败
+- 要么保证后续重试还能成功进入
+
+如果既没告知，又把后续重投吞掉，就是严重产品缺陷。
+
+### 4. Abnormal paths are not modeled as first-class product states
+
+当前系统已经有一部分异常提示，但还没有形成稳定判断：
+
+- 什么异常必须立刻对用户可见
+- 什么异常可以后台自愈后静默恢复
+- 什么异常必须明确要求用户重发或重试
+
+### 5. Stale redelivery can resurrect old work unexpectedly
+
+如果某条消息第一次进入 bridge 时中途失败，渠道之后可能会重投同一个 `message_id`。
+
+当前如果中间层只把这类失败当成“允许后续重试”，但没有识别“会话其实已经继续前进”，就会出现一种很差的体验：
+
+- 用户已经聊到后面了
+- 系统却在几分钟甚至几小时后，突然又把前面那条旧消息重新做一遍
+
+这不是正常恢复，而是**过期工作被意外复活**。
+
+## Product Decision
+
+建立一条硬规则：
+
+### Rule 1
+
+只要用户消息已经进入中间层，系统就必须保证二选一：
+
+- 要么给出用户可见结果
+- 要么给出用户可见异常状态
+
+不能既无结果又无异常提示。
+
+### Rule 2
+
+只要异常导致“本轮可能没有被稳定送达”，就必须进入用户可见路径。
+
+### Rule 3
+
+如果异常发生在出站链路，且本轮未成功完成，则不能把该消息静默标记成已完成。
+
+### Rule 4
+
+日志是排障材料，不是用户通知机制。
+
+### Rule 5
+
+如果同一个 inbound message 是平台重投，但当前会话已经被更晚的用户消息推进到下一阶段，中间层必须把这次重投识别为**过期重放**并抑制，而不是把旧任务重新做一遍。
+
+## Goals
+
+1. 杜绝“消息被吞了，但用户不知道”
+2. 让异常状态成为对话产品的一部分，而不是仅存在于日志中
+3. 让重试 / 重投语义稳定，不再把失败消息误判成已完成
+4. 让用户明确知道当前是：处理中、恢复中、失败需重发，还是等待操作
+
+## Non-goals
+
+本次不做：
+
+- 完整运维看板
+- 所有内部错误都逐条暴露给用户
+- 把底层堆栈直接发给飞书用户
+
+目标不是“异常细节外泄”，而是“异常语义透明”。
+
+## Scope
+
+V1 重点覆盖：
+
+1. inbound 已接收后发生的本地中间层异常
+2. channel outbound / delivery failure
+3. runtime recovery failure
+4. receipt / dedupe 与重投语义
+5. 中间层自愈与用户可见状态之间的最小合同
+6. stale inbound redelivery / duplicate replay 的抑制与可追溯性
+
+## Required Product Behavior
+
+### 1. Inbound accepted + handling failed
+
+如果消息已经 accepted，但本轮处理未完成：
+
+- 不能静默结束
+- 不能把 receipt 标成已完成
+- 应允许重投再次进入，或明确提示用户重发
+
+### 2. Secondary status send failed
+
+如果像 reaction、progress、status 这类提示发送失败：
+
+- 不应让主流程整体无声失败
+- 应记录 delivery issue
+- 如影响用户理解当前状态，应在后续可用时补发系统状态或最终失败说明
+
+### 3. Recovery failed
+
+如果系统尝试恢复但失败：
+
+- 不能继续伪装成“正在工作中”
+- 必须明确告诉用户：本轮未恢复，请重发上一条消息
+
+### 4. Health / state corruption
+
+如果本地状态文件损坏：
+
+- 中间层应优先自我修复或降级
+- 不允许因此直接吞掉当前用户消息
+
+### 5. Stale redelivery after the user has moved on
+
+如果同一个 `message_id` 被平台再次投递，但系统已经能确认：
+
+- 这条消息之前来过
+- 当前会话已经被更新的用户消息推进过
+
+则不应再把这条旧消息当作新任务重新执行。
+
+要求：
+
+- 对用户不再突然冒出旧任务回复
+- 对 archive / timeline 仍保留可追溯事件
+- 若会话尚未继续前进，则仍允许同一条消息在失败后再次重试
+
+## Implementation Direction
+
+优先实现方向：
+
+1. 任何 receipt 完成标记，都必须只发生在用户可见结果已稳定产出之后
+2. health / delivery 状态文件读取应容错，不能反过来拖垮正常消息处理
+3. delivery unavailable / recovery failed / swallowed-risk 事件应进入统一异常通知语义
+4. conversation view 与 archive 中应保留这些异常事件，便于之后回溯和解释
+
+## Acceptance Criteria
+
+1. 任一已接收用户消息，不能再出现“日志里知道失败、用户侧完全无感”的吞消息场景
+2. 出站链路失败时，不会把当前消息误判成 completed，从而吞掉后续重投
+3. runtime 恢复失败时，用户能收到明确的“需要重发”提示
+4. 中间层内部状态文件损坏时，消息处理仍可继续，或至少能给出明确异常回告
+5. 相关异常在 archive / conversation view 中可追溯
+
+## Open Questions
+
+1. 哪些 delivery failure 需要立刻发系统消息，哪些只需写健康状态并等待后续补发
+2. 是否需要一条统一的“本轮处理中出现异常，但系统仍在尝试恢复”文案合同
+3. 是否需要把 swallowed-risk 场景单独纳入 `/status` 输出
+
+## Product Judgment
+
+中间层的价值，不是把消息转一下，而是把复杂性吃掉。
+
+如果中间层在异常路径里不透明，那它不是在帮用户，而是在制造新的不确定性。
+
+所以这条专题的判断非常硬：
+
+> 中间层可以出错，但不能在用户视角里“无声出错”。

package/docs/completed/SPEC-nightly-memory-digest-visibility.md

@@ -0,0 +1,121 @@
+# Nightly Memory Digest Visibility
+
+## Status
+
+- Target project: `work-ally`
+- Audience: implementation engineer / product owner
+- Scope: nightly memory digest result visibility in Feishu-facing flows
+- Status: implemented in current branch
+- Goal: make the nightly digest execution result visible to the user instead of remaining a background-only mechanism
+
+## Summary
+
+这份专题定义的是一个已经落地的产品补口：
+
+- nightly memory digest 不再只是后台写文件
+- 用户需要知道它有没有跑
+- 用户需要知道它跑出了什么结果
+- 即使结论是“无新增稳定记忆”，也应被明确告诉用户
+
+一句话：
+
+> nightly memory digest 现在是“后台执行 + 桌面写回 + 对话内结果通知”的闭环，而不是静默后台任务。
+
+## Background
+
+原先 nightly digest 的工程链路已经存在：
+
+- scheduler 会按计划触发 `nightly-memory-digest`
+- routine 会读取当天 archive
+- digest 结果会写入 `journal/` 与 `MEMORY.md`
+- 运行记录会进入 `.system/runs/` 与 `.system/runtime/routines-state.json`
+
+但在真实使用里暴露出一个明显问题：
+
+- 用户不知道任务到底有没有执行
+- 用户不知道“没有新内容”是因为没跑，还是因为跑了但无新增
+- 用户也不知道本次提炼到底更新了什么
+
+因此，这条链路虽然工程上成立，产品上却还缺最后一公里的可见性。
+
+## Problem Statement
+
+nightly digest 如果只在后台写文件，会让用户陷入三种歧义：
+
+1. 今天到底跑没跑
+2. 跑了是成功、失败，还是没有产出
+3. 这次提炼影响了什么长期记忆
+
+这类问题不应该要求用户自己去翻文件判断。
+
+## Shipped Model
+
+当前已落地行为如下。
+
+### 1. 默认调度时间仍是 assistant 本地时区 23:00
+
+- 默认 routine 定义为 `0 23 * * *`
+- 调度解释使用 assistant 当前配置的本地时区
+- 在中国时区下，就是每天 23:00 触发
+
+### 2. digest 完成后会生成一段面向用户的摘要
+
+routine 执行完成后，会从 digest reply 中解析三段内容：
+
+- 摘要
+- 当日日记
+- 长期记忆
+
+其中摘要不会原样暴露内部结构，而是转成面向用户的系统消息文案。
+
+### 3. 如存在可用 Feishu 投递目标，会主动推送系统消息
+
+当前投递目标解析顺序是：
+
+1. 最近一次 Feishu 会话
+2. `defaultPushTarget`
+3. 仅有一个 allowlisted user 时的兜底目标
+
+只要存在可用目标，digest 完成后就会主动发出一条系统消息，告诉用户本次记忆整理结果。
+
+### 4. “无新增稳定记忆”也会明确告知
+
+如果 digest 结论是本次没有新增稳定记忆，系统消息会明确表达这一点，而不是静默结束。
+
+这能把“没跑”和“跑了但无新增”区分开。
+
+### 5. 运行记录仍保留在文件系统里
+
+除对话内通知外，工程侧仍保留可追溯记录：
+
+- `.system/runtime/routines-state.json`：记录最近一次 slot
+- `.system/runs/latest.json`：记录最近一次执行结果
+- `.system/runs/*.json`：保留历史运行结果
+
+也就是说，这个 feature 的方向不是用系统消息替代文件追踪，而是在文件追踪之外补上用户可见结果层。
+
+## Non-goals
+
+本次已落地范围不包括：
+
+- 独立的 routine 管理面板
+- digest 失败后的重试中心
+- digest 历史结果列表 UI
+- 对 `NOW.md` 的自动改写
+- 无 Feishu 可投递目标时的额外补发机制
+
+## Product Judgment
+
+这条补口的核心判断有三条：
+
+1. nightly digest 是长期协作能力，不应保持静默后台态
+2. “无新增稳定记忆”本身也是结果，应该被通知
+3. 用户侧看到的是结果摘要，不是原始运行日志；原始日志继续留在文件系统里
+
+## Acceptance Criteria
+
+- nightly memory digest 在默认配置下按 assistant 本地时区 23:00 调度
+- 执行完成后，如存在可用 Feishu 投递目标，会主动推送系统消息
+- 系统消息能区分“有更新”与“无新增稳定记忆”
+- digest 仍只写回 `journal/` 与 `MEMORY.md`，不改写 `NOW.md`
+- 最近一次执行结果仍可在 `.system/runtime/routines-state.json` 与 `.system/runs/latest.json` 中追溯