Repository navigation
Messaging: external ingress, Provider contracts and Outbox #46
Description
Remaining outcome — reconciled 2026-09-30
Feature Project: IM Identities & Messaging. Milestone: v1.1.
The local canonical Messaging baseline is already delivered: SQLite Source Event / Channel placement / multi-Bot Inbox Admission (#254/#278), joined-Channel discovery and unified message queries (#304). Do not rebuild these as an unstarted foundation.
This issue now owns the remaining provider-neutral extension and external side-effect contracts required by #117/#12:
- verified external Messaging Ingress and trusted Reply Route;
- live Provider Registration / Provider Operation contracts and Fiber cleanup;
- Capability versus Human Service Grant enforcement;
- durable Outbox intent/attempt/outcome, explicit unknown outcome and bounded reconciliation;
- authenticated replay/revision/recall/echo handling and external attachment evidence as each real tracer needs them.
Messaging remains the canonical application-owned SQLite authority. dsh-im must not own PersonaBot identity, Inbox/Wake policy, Session mapping or authorization. Browser Consumers cross Typert/API Gateway; provider SDK objects and secrets stay Host-side.
Next runnable slice
Deliver only the Provider contracts and durable outbound path exercised by #117, with its binding/credential lifecycle and real-provider evidence. First inbound acceptance is #12: an authorized work-group @mention → PersonaBot Inbox/Orchestrator → reply in the original group/topic. Do not require unrelated provider breadth before that path.
Remaining acceptance
- Canonical transaction produces authenticated external Source Event/placement/admission and exact policy snapshot, then notifies after commit.
- First adapter uses Provider Registration/Operation contracts; core routing/schema has no provider-specific branch.
- Outbox records intent before an external call and separates receipt, definite failure and unknown outcome; no blind retry.
- Revoked grants, stale routes, removed credentials and disposed Registrations fail closed.
- Focused replay/echo and crash-window tests cover the exercised tracer.
- Existing local Messaging behavior and committed-output producer compatibility remain intact.
Related: #48/#78/#117/#12. Historical #30 is retired; existing claim comments remain scoped as recorded.
Historical scope before 2026-09-30 reconciliation (superseded where inconsistent)
Outcome
实现 SQLite-authoritative Messaging deep module，并把 browser RPC、模型 tools、Bridge/webhook/system producers 做成薄 Consumers。废弃“每 Channel 一份 NDJSON 是 runtime authority”的旧方案。
本票同时拥有 provider-neutral 的 extension contract；具体 Feishu/Lark、Slack、Discord transport 由 #48 的 Provider Plugins/Registrations 实现，不能把 SDK 或 provider 分支写进 Messaging core。
Stable seams and ownership
- Messaging Ingress Service Definition（application-defined）：接受 authenticated adapter 提交的 normalized evidence；Messaging Provider 在一个 SQLite transaction 中完成 Source Event/Revision、echo correlation、Channel placement、policy snapshot、Inbox Admission/Attention。
- Messaging Provider Registry（application-defined Registry）：保存当前 live Provider Registrations。Registration 只声明 provider metadata、account factory、capabilities 与 Provider Operation Provider；随 owning Fiber dispose 撤销。
- Provider Operation Service Definition（application-defined）：reply、proactive post、attachment fetch/upload、current-message fetch、outcome reconcile 等 named operations，具有明确 result/error/cancellation/idempotency semantics。
- Durable authority：Source Event、Messaging Policy revision、Admission/Decision、Outbox Intent/attempt/outcome 都属于
botharness.db，不是 Cordis Event 或 SessionEvent。 - Live notification：只在 commit 后发 Cordis Event / internal notifier；重启从 durable pending projection 补偿。
- Agent delivery：Bot Attention: causal aggregation, escalation and recovery acceptance #47 把 committed attention 经 Wake/Delivery Policy 送入 DSH Agent Inbox 的已验证安全边界；真正进入模型的表示才进入 DSH Session history。
- Host/client：read models 与 commands 只经 TypertRemoteService → API Gateway；UI 不直接读 tables 或 provider SDK。
Provider Registry 是 runtime composition，不是授权。Agent Scope、Access policy、Inbox Trigger、Provider Capability 与 Service Grant 是不同轴，不能互相代替。
Provider-neutral ingress contract
Core 只接收完成认证的最小 evidence：
- provider id、Provider Account Fingerprint、Bridge id；
- provider event/message id、kind、timestamp、可选 revision/version；
- authenticated Actor identity；
- external conversation、surface kind（DM/group）、thread/root/reply identities；
- normalized content parts、attachment locators；
- echo/own-sender/correlation evidence；
- advertised Provider Capabilities；
- 可构造 trusted Reply Route 的非秘密 locator；
- 可选 bounded namespaced provider evidence；任意 raw payload 不进入 model/UI。
Slack channel + thread_ts、Discord parent/thread、飞书 root/parent/thread 必须保留，不可压成一个会丢因果关系的 chat_id。Provider-specific extras 留在 namespaced evidence；core 不出现 if provider === ... routing。
Domain scope
- verified Actor/system context、Membership、authorization 与 stable ingress dedupe。
- immutable Source Event / Source Revision / tombstone；optional Channel placement。
- PersonaBot-owned Inbox Trigger、Wake Policy revision、Inbox Admission、Attention Unit/Decision。
- trusted Reply Route、per-account Provider Capability、Human Service Grant。
- Outbox Intent / attempt / receipt /
unknown-outcome与 bounded reconciliation。 - provider echo、causation/correlation、trusted Bot-hop guard、content-addressed attachments。
Model-facing Consumers
- Inbox/source read 与 history/list 使用 bounded cursor pagination。
- Reply 只接受
sourceEventId + content，Host 从 Source Event 的 trusted Reply Route 选择 provider/account/destination。 - proactive Service Action 是 provider-specific capability，不复用 reply/channel send 绕过 Grant。
- 默认只对 current Orchestrator 暴露完整 Messaging tools；Assignment Session 只读 explicit granted context。
Acceptance criteria
- 一个 command transaction 原子完成 event/revision、placement、admission/attention、exact policy revision 与必要 outbox facts；post-commit 才通知。
- fake Provider Registration contract suite 证明同一 normalized ingress/reply contract 可被两个 provider 实现，且 core schema/主链无 provider branch。
- 并发 ingress、duplicate/replay、out-of-order revision、recall、echo 与 Bot-hop-limit tests。
- stale source、revoked grant、unsupported capability、credential rotation/removal、unknown outcome 均 fail closed 且返回 stable errors。
- external side effects 有 crash-window/fault-injection tests；每次先写 Outbox Intent，再记录 attempt 与 receipt/failure/unknown-outcome，不盲目自动重发。
- Provider Registration 随 Fiber 生命周期撤销；一个 provider 故障不阻断其他 provider。
- migration plan 把旧 Channel/roster operational records 单向迁入；成功后无双写/第二 authority。
- API/RPC/tools 只调用 deep module，不直连 tables。
- representative transaction/pagination/search benchmarks 与 DB/WAL diagnostics。
Blocked by
- Foundation：operational database owner / writer lease / schema generation #79 operational database foundation。
V1 compatibility obligation
- PersonaBot output: committed-output extension event #125 的 application-defined PersonaBot Output Committed Cordis Event 是稳定 producer contract。Messaging: external ingress, Provider contracts and Outbox #46 迁移或替换当前 Channel writer 后，必须在同一 canonical message commit 成功后继续由 PersonaBot Plugin 发出该 process-local event。
- migration tests 必须证明不会漏发、双发，且 provider Outbox outcome 不会伪装成尚未提交的 PersonaBot Channel output。
- Bot activity: revisioned live sync and reconnect #121/v1.1: read-model 实时同步流（post-commit frames） #67 的 live frames 仍是 read-model invalidation；它们不能替代 PersonaBot output: committed-output extension event #125 output notification。
Related
- Bot Attention: causal aggregation, escalation and recovery acceptance #47 Bot Inbox / Orchestrator coordination。
- IM identities and messaging: provider coordination #48 External messaging Bridge Provider Plugins。
- IM tracer: work-group @Bot → PersonaBot Inbox → same-topic reply #12 first real external reply acceptance。
- Research：Feishu/Lark Messaging provider contract（events / capabilities / identity） #78 Feishu/Lark provider-specific evidence。
References
- 架构地基：显式 Session 归属与 deep modules（GrokBot-on-DSH 对齐） #71；ADR-0036～0039、ADR-0041。
docs/research/2026-09-21-letta-channels-external-im-bridge.md- Letta Channels architecture
- Letta channel plugin contract
Published dsh-im provider spec
- IM tracer: dsh-im outbound adapter and explicit Bot binding #117 is the first concrete Consumer of this ticket's Messaging Provider Registration and Provider Operation seams.
- Keep provider-specific dsh-im lifecycle, opaque bot/target references and compatibility checks out of Messaging core.
Activity
[-]v1.1: Channel store 与消息工具（inbox_list / channel_read / channel_history / channel_send）[/-][+]v1.1: Messaging deep module 与 Inbox/Channel/Outbox tools[/+]25 remaining items
Add explicit Profile IM grants and durable outbound text records (#587)
DoodleBears commentedon Sep 30, 2026
Agent work outcome
codex/local/01a0f14c-5338-7020-853b-0fe54b87aa95(not a DSH Session)a3d88bbab25d2479ae435c9a8c1441c747cea20eThe Human bound the real Lark account/destination in Profile, sent a text and confirmed receipt, then authorized merge. Exact final head
db2ce29cddb4406c0d8240373aa71526a992807dpassed GitHub lint/format/typecheck/test/build/docs and CodeRabbit checks; local integration was 1462 pass / 1 skip. Canonical grant, intent and one settled accepted attempt were verified without another external send. Main integration retains the concurrent Human Inbox reply, usage and Host file actions.Released legacy dsh-im remains disabled. The compatible authenticated-account/checked-send contract is proposed in xmanrui/dsh-im#293 and has not been accepted or released. This does not complete #117's compatible pinned artifact or #46/#78's inbound scope.
The Human clarified work-group collaboration as the priority. #12 now verifies work-group @bot → the bound PersonaBot Inbox/Orchestrator → trusted same-group/topic reply; DM is a compatibility follow-up. See #12 (comment).
DoodleBears commentedon Oct 1, 2026
Agent work claim — ingress contracts exercised by #12 only
codex/local/01a0f14c-5338-7020-853b-0fe54b87aa95(not a DSH Session)codex/12-im-group-tracerNo other active claim is recorded in this bounded ingress scope. The integrated behavior and Human E2E acceptance belong to #12; this task does not take unrelated #47 recovery work or prebuild provider breadth.
DoodleBears commentedon Oct 1, 2026
Agent work outcome — waiting for real Human E2E input
codex/local/01a0f14c-5338-7020-853b-0fe54b87aa95(not a DSH Session)codex/12-im-group-tracer6422a716(retained locally; no issue PR published)The canonical mention → Source Event/Inbox → owning Orchestrator → checked original-topic Outbox reply implementation and Client reception/source-detail controls are retained. Final focused receive/send/UI coverage passes 28 tests; typecheck, lint, formatting, build, release-ledger and final docs build pass. The earlier full suite passed 1615 tests with 1 skipped. A cold-start account-registration race and a stale concurrent reception toggle were reproduced and fixed.
The same live task Host is authenticated and receiving with the original grant revision. The current audit still finds zero real external Source Events and zero source-reply intents. Real Human topic input has been required for three consecutive goal turns; fixtures, a borrowed Human identity or a fabricated screenshot cannot replace that evidence.
Remaining acceptance: Human mention inside an existing authorized test-group topic, exclusion of an ordinary unmentioned message, native model
bridge_reply, visible same-topic platform receipt, source-detail screenshots and restart without duplicate reply. Once real input arrives, this task can resume and finish the E2E before publishing the issue PR; each published issue PR still requires the agreed goal pause for Human QA. Keep #12 and the broader #46 open. No production enablement or merge is claimed.DoodleBears commentedon Oct 1, 2026
Agent work claim — real Lark input verification resumed
codex/local/01a0f14c-5338-7020-853b-0fe54b87aa95(not a DSH Session)codex/12-im-group-tracerThe Human has sent the real QA-group/topic inputs and explicitly authorized Computer Use to send further test messages in BotHarness IM QA #78. Resume the same bounded #12 tracer and the #46 contracts it exercises, diagnose the current lack of canonical ingress, then finish real source/admission/model/topic-reply evidence. No broader #46 takeover. No issue PR or completion claim yet; pause for Human QA after publishing the evidence-bearing #12 PR.
docs(im): normalize screenshot evidence to declared PNG format
DoodleBears commentedon Oct 1, 2026
Agent work outcome — paused for Human QA
codex/local/01a0f14c-5338-7020-853b-0fe54b87aa95(not a DSH Session)codex/12-im-group-tracerReal Human-origin Computer Use in the authorized Lark QA group verified
BH12-FINAL44-TOPIC-03→ PersonaBotbridge_reply→ visibleBH12-FINAL44-OKwithin the same existing topic and own bound identity. An unmentioned message is excluded. Cold restart retains exactly one Source Event, one handled Inbox Admission and one provider-accepted reply, with no local Channel placement or Assignment, no error, and the same live grant revision. Chrome verified the real retained source-detail modal and reception state after restart; the PR embeds six screenshots with capture provenance.Final code on main
7fe56622, schema 44: 1683 tests passed / 1 skipped; typecheck, build, lint, formatting, bilingual ledgers and 268-page docs build passed. Evidence-only commits do not change the verified runtime. Current provider consumer is text-only; formatted rich posts are excluded rather than claimed as supported.The agreed goal is now paused immediately after the issue PR. Human QA and merge authorization remain pending. Qualified temporary provider proof does not establish an upstream release or production rollout. No subsequent ticket implementation starts before Human instruction.
This task implements only the bounded #46 ingress/reply contracts exercised by #12. The broader #46 remains open; shared Channel routing, ordinary traffic, history, autonomous topic following and provider breadth are not completed by this PR.
DoodleBears commentedon Oct 1, 2026
Agent work claim — PR #655 merge verification
codex/local/01a0f14c-5338-7020-853b-0fe54b87aa95(not a DSH Session)codex/12-im-group-tracerfeat(im): route work-group mentions to PersonaBot Inbox and reply in …
DoodleBears commentedon Oct 1, 2026
Agent work outcome
codex/local/01a0f14c-5338-7020-853b-0fe54b87aa95(not a DSH Session)7237c53ffe0fa3abf0219aea0b67878031388a3e