feat(reward-memory): recall guidance before outbound messages

[huangruiteng]

Summary

• add an opt-in reward_memory.outbound capability that recalls relevant guidance at the actual Lark send/reply boundary
• bind the agent-only review digest to recipient, message, and purpose so changed intent requires a fresh recall
• preserve default-off behavior, fail open on provider errors and urgent delivery, and keep send authority outside recalled memory
• stop interpreting opaque turn instance IDs as timestamps
• document the contract in English and Chinese and add focused regression coverage

Validation

• 78 passed across outbound guidance, agent-turn recall, and Lark send/reply suites
• reward-memory-recall-application-smoke: ok
• Ruff and changed-file Python compilation passed
• git diff --check origin/main...HEAD passed
• standard LoopX pre-merge canary passed: 18/18 selected checks, 0 failures, 0 warnings, 0 manual holds
• public/private boundary scan passed for all 11 changed files

Boundaries

• this is an agent review step, not user approval and not delivery authorization
• no private/local artifacts or credentials are included
• no real outbound message was sent during validation

Scope review

The capability stays with the existing Reward Memory owner and integrates only at the shipped Lark send/reply call sites. A broader automatic wrapper for every possible outbound provider is intentionally not introduced here.

This PR is submitted for review and is not being merged as part of this request.

[huangruiteng]

Request changes conclusion (author-owned PR; GitHub blocks formal self-review)

English verdict: REQUEST_CHANGES

动机

这个 PR 解决的是一个真实的发送前决策缺口：LoopX 目前可以积累 Reward Memory，但 Lark send / reply 在真正写出消息前不会自动取回与当前收件人、内容和目的相关的历史指导。结果是 Agent 可能在已有“先尝试安全替代方案、再升级求助”等经验时仍直接发出消息。新行为把召回放在已存在的身份校验、群成员校验和 provider dry-run 之后、实际 provider 写入之前，并把 review digest 绑定到 profile、chat、placement、文本和 purpose；这比在更上层做一个泛化 wrapper 更贴近真正的副作用边界。

改动思路

入口仍是 lark-inbox send/reply。CLI 根据 goal_id + agent_id 解析默认关闭的 Reward Memory 实验；只有 automatic_recall 和 outbound_message.before_send 都启用、且 corpus 的 peer_ref 精确匹配当前 Agent 时才安装 hook。发送器完成原有 destination/profile、身份、成员和 provider preview 校验后生成 intent digest，hook 对明确语料执行一次有界 soft-preference 召回，并返回 outbound_guidance_review_v0。存在 guidance 且不是 urgent 时，首次调用在 provider write 之前停在 agent_review_required；Agent 用精确 digest 重试后才继续。禁用、无配置、空召回、provider 不可用或 urgent 都保留原发送路径，召回不授予发送权限，也不投影为用户 gate。

具体改动

• 生产代码新增约 231 行：reward_memory/outbound.py 负责 scope、checkpoint、query、digest 和 review 决策；lark_inbox.py 增加两个 CLI 参数、结果渲染和 send/reply 接线；inbox_reply.py 在 provider write 前调用 hook 并把结果附回 receipt。
• 文档新增约 143 行，说明中英文配置、两步调用和边界；测试新增 225 行，覆盖 digest 绑定、urgent/provider failure、默认关闭、send/reply 写前停止、真实 CLI 接线与 opaque turn id。
• agent_turn_recall 的小修正不再把 opaque turn_instance_id 当 ISO 时间，而以当前 UTC 时间作为 observed_at，并透传 reason_code。

关键代码讲解

1. outbound_guidance_hook（loopx/capabilities/reward_memory/outbound.py）是能力所有者：它验证精确 Agent scope，只接受 soft_preference，计算与 intent/identity/purpose/guidance 绑定的 digest，并明确保持 grants_new_action_authority=false。
2. _deliver_lark_inbox_outbound（loopx/extensions/lark/inbox_reply.py）仍是副作用所有者：旧的身份、成员、mention 和 provider-preview 检查不变；hook 只插在 dry-run 成功与实际 send 之间，因此未确认 guidance 时不会发生外部写入。
3. handle_lark_inbox_command（loopx/cli_commands/lark_inbox.py）把 capability 接到两个已发布入口，但这里也是当前阻塞点：它直接读取新 Namespace 字段，没有兼容旧的直接调用者。

对主干的风险

有 1 个阻塞问题。精确 head 6a09e96fef10fc0aa1ffd2a31bd194bf707b758b 的必需 pytest check 为红；失败可在本地稳定复现：

uv run --with pytest python -m pytest -q tests/capabilities/test_outbound_guidance.py tests/extensions/test_lark_event_collector_routing.py::test_cli_send_resolves_route_and_forwards_safe_delivery_flags

结果为 1 failed, 10 passed。已有 caller test_cli_send_resolves_route_and_forwards_safe_delivery_flags 直接构造 argparse.Namespace，其中没有新字段；handle_lark_inbox_command 在 loopx/cli_commands/lark_inbox.py:665 读取 args.message_purpose 时抛出 AttributeError。这意味着默认关闭并没有对所有既有 handler 调用路径保持可观察兼容，也使仓库要求的全量测试失败。最小修复是在 handler 边界用 getattr(args, "message_purpose", "unspecified") 与 getattr(args, "reviewed_guidance_digest", None)（send/reply 两处统一处理），或同步迁移所有受支持的直接 caller；回归测试应保留一个没有新属性的旧 Namespace，并断言 hook 为 None、原参数继续转发。其余聚焦能力测试、diff check、build、sign-off、dependency review 和 Windows check 均通过；SonarCloud 的非阻塞 analysis job 也红，但独立 SonarCloud Code Analysis 为绿。

我的整体评价

能力边界和机制规模总体相称：它复用了现有发送器与 Reward Memory runtime，没有新建发送权限或持久状态；默认关闭、精确 scope、intent-bound digest、urgent/failure fail-open，以及“Agent review 不是用户审批”的语义都表达清楚。当前不能给出无阻塞结论，因为 exact head 破坏了已有 handler caller 并使必需 pytest 红。修复 Namespace 向后兼容、补上对应回归测试并让 required checks 转绿后，我预期可以快速复审；没有要求扩大能力范围或重做架构。

[huangruiteng]

Review follow-up — blocker fixed

The reported legacy argparse.Namespace regression is fixed in 4b97d749667933356316f5b3c6236ee9948d953e. Both send and reply now default missing message_purpose to unspecified and missing reviewed_guidance_digest to None. The existing routing caller remains unchanged; it now also asserts that default-off delivery receives no hook. New parameterized coverage checks both legacy handler paths and exact forwarding of delivery flags.

No remaining blocker found in the reviewed diff. The original failure was reproduced before the fix (1 failed, 10 passed).

Product and architecture judgment

• Motivation: recall reviewed operating guidance at the existing outbound side-effect boundary, without creating another sender or permission system.
• Coverage: the new compatibility tests restore the advertised default-off behavior for direct handler callers. Opt-in tests retain intent-bound acknowledgement, urgent/provider-unavailable continuation, scoped recall, and zero writes before review.
• Main risk: optional recall can delay an enabled agent's send pending agent acknowledgement; this is explicitly documented and is not a user approval gate. Existing identity, membership, destination, idempotency and readback checks retain authority.
• Review lenses: purpose is an explicit enum rather than text classification; generic code has no project-specific decision rule; activation is default-off; recalled soft preferences grant no new authority. The digest proves acknowledgement, not reasoning quality.
• Bounded refactor pass: kept the compatibility default at the handler boundary. No new abstraction or broader provider interception is needed for this fix.

Validation

• Relevant outbound, agent-turn, routing and Lark reaction suites: 83 passed.
• Reward-memory recall/application smoke: passed under the supported project Python runtime. A first invocation with the host's older Python lacked tomllib; rerunning under the supported runtime passed.
• Ruff on changed code/tests, Python compilation, committed and working-tree diff hygiene: passed.
• Standard canary premerge --from-git-diff: 18/18 selected checks passed, plus direct diff/compile checks; 0 failures, 0 manual holds. Coverage includes extension/runtime, CLI/control-plane, public documentation and public/private boundaries.
• Public/private scan reviewed: only generic documented .local/ examples; no private state, credentials, raw traces or local operating evidence included. Generated dependency-lock output remains untracked and excluded.
• No live outbound message was sent during validation.

Merge decision: self-merged with explicit owner authorization as 9d70e1e34710786da1716241237b774605ec69d7. Exact-head pytest aggregation, both test shards, static checks, Windows tests, both builds, dependency review and DCO passed. Deployment/publication jobs were skipped as expected for a PR; the non-blocking Sonar analysis was still running at merge time. Installed-runtime activation and read-only preflight are validated separately; no live-send permission is inferred from merge.

[now-ing]

Design question: guidance recall for Goal Topic auto-replies

Thanks for #3968 — the digest-bound review loop is a clean boundary. OUTBOUND.md explicitly leaves one case open ("other tools and Goal Topic auto-replies are not intercepted by this integration", loopx/capabilities/reward_memory/OUTBOUND.md:7-9), and while extending the Goal Topic connection surface (#3983) we kept bumping into the same tension, so I wanted to ask which direction you see before sketching anything.

On the CLI path the loop closes because a CLI operator can read the guidance and rerun with --reviewed-guidance-digest (outbound.py:136-138; inbox_reply.py:386-395). But a direct_session auto-reply has no such operator: process_lark_goal_topic_event calls answer(...) and then reply_lark_event_inbox(..., execute=True) without before_send (goal_topic_runtime.py:891,926), and the standalone reply_lark_goal_topic goes straight to im +messages-reply (goal_topic_connections.py:1307). So the review loop is unsatisfiable there — today the runtime resolves that by skipping recall entirely. Three directions we can see:

1. Urgent-like advisory recall — run recall, attach guidance to telemetry/effect receipt, continue delivery (the urgent carve-out already works this way, OUTBOUND.md:47-48). Trade-off: no acknowledgement proof at all; guidance becomes informational.
2. Goal-level pre-authorization — let the experiment config pre-acknowledge the auto-reply surface with a standing digest per goal/topic. Trade-off: keeps the digest shape, but the digest is defined to bind intent/destination/message ("Changes invalidate it"), so a standing acknowledgement dilutes what it proves.
3. Degrade to queued_for_agent — when guidance is non-empty, defer like async_inbox does (goal_topic_runtime.py:886) so the reviewed CLI path handles it. Trade-off: preserves review semantics exactly, but auto-replies stall whenever guidance is configured and no agent lane is available — and direct_session exists precisely for when one isn't.

One smaller note either way: the purpose enum (unspecified|help|progress|urgent) has no obvious slot for an auto-reply. Do you already have a plan for this gap, or would you welcome a prototype of one of the directions above?

[huangruiteng]

Thanks @now-ing — the coverage gap is real, and the three trade-offs are well identified. I would welcome a focused follow-up prototype, but recommend a fourth direction: let the answering agent consume the guidance and review the exact outbound candidate inside the existing session workflow.

One clarification: #3968's acknowledgement is by the executing agent, not a human CLI operator. answer_lark_goal_topic already opens/resumes or routes to a model session and waits for its result. The missing part is that process_lark_goal_topic_event currently receives only the answer/effect result and then sends it; it has no continuation for presenting outbound guidance and obtaining a decision on that candidate. The low-level standalone reply helper has no model context at all. This is an orchestration gap, not a reason to manufacture standing acknowledgement.

Recommended contract

1. Resolve the actual bound Goal/agent/session and explicit recall opt-in. Do not use the legacy fallback agent name as evidence of memory-scope ownership. Unbound/unconfigured routes keep existing behavior, with a content-free coverage reason where useful.
2. Prefer presenting bounded, correctly scoped communication guidance before drafting, so it can improve the answer rather than merely appear in telemetry. Reuse Reward Memory's scope/freshness/provider machinery; do not blindly reuse the quota-specific agent-turn-recall packet for a chat event.
3. At final delivery, prepare the exact candidate through the existing sender's normalization, placement and provider preflight. When review is required, give the guidance and that candidate to the answering session through a bounded review continuation. A small explicit result such as approve/revise/decline is sufficient; it is not user approval or send authority.
4. Accept acknowledgement only for the exact guidance/intent digest. A revised candidate must be prepared and reviewed under its new digest. In particular, the current whitespace normalization/1,200-character truncation must happen before review, not silently change approved text afterward. Bound continuation/revision attempts; no recursive recall loop.
5. Keep delivery, deduplication, readback and source-event ACK with their existing owners. Review completion is not delivery completion. A replay must not duplicate the send; a review failure must not ACK the source as successfully answered. Preserve the existing empty/unavailable-memory behavior, but distinguish that from a failed review of guidance that was successfully retrieved—never fabricate an acknowledgement for the latter.

Pre-draft context delivery and final-candidate acknowledgement prove different things. The former should be labeled as context delivery, not represented by the existing exact-message review digest. Neither proves reasoning quality or factual correctness.

The proposed alternatives

• Advisory recall: reasonable as an explicitly named context-only mode, but attaching guidance only to telemetry after generation does not let the agent use it. Auto-reply must not implicitly mean urgent or bypass review.
• Standing Goal digest: not recommended. Goal configuration can opt into the workflow, but cannot acknowledge unknown future messages or destinations.
• Always queue for another agent: not the default. It changes direct-session liveness and can strand replies. An explicit fallback is possible when a bound review-capable session is unavailable; the pending/error state must remain recoverable and visible, without inventing a user approval gate.

On purpose: auto-reply is an origin/delivery mode, not a communicative purpose. An automatic reply can be help, progress or neither. Keep unspecified when no purpose is explicitly known; do not infer urgency from automation. Add a separate typed origin field only if an active caller needs it.

Scope and acceptance

Please keep this separate from the reconnect/root-reuse fix. Start with one real direct-session caller and a narrow preparation/review seam; do not add a universal outbound interceptor or make the low-level reply helper launch models. Reward Memory owns recall; the session owns reasoning; the Lark sender owns transport checks. A typed decision contract is useful, but a broad TS migration is not required for this prototype.

Acceptance should cover default-off parity, exact identity isolation, guidance actually reaching the model before its decision, changed-message/destination/guidance invalidation, bounded failure/retry, and zero duplicate send/early ACK on replay. Use an isolated session harness and synthetic transport, not live group messages. I checked the merged contract and current call paths for this reply; this is a design recommendation, not a claim that auto-reply recall is already implemented or runtime-qualified.