PR: feat(matrix): isolate thread history and fix threaded reply placement

Target: openclaw/openclaw main
Branch name suggestion: feat/matrix-thread-context-isolation

Title

feat(matrix): isolate thread history and fix threaded reply placement

Summary

• Problem: Matrix threads were known to routing and session logic, but room-history tracking and message reads were room-flat. All messages in a room — regardless of which thread they belonged to — competed for the same context window. Separately, threaded bot replies included unconditional is_falling_back + m.in_reply_to fallback metadata in their event relations, causing Matrix clients (e.g. Element) to surface them in the main room timeline even when the intended target was a thread.

• Why it matters: Without per-thread context isolation, a busy Matrix room or DM pollutes every thread's LLM context with unrelated messages. With the send-path leak, thread replies appear as duplicated messages in the room timeline, confusing users and growing room scroll.

• What changed:

  • room-history.ts — room queues now carry per-thread sub-queues keyed by thread root event ID; watermarks are scoped by (agentId, roomId, threadRootId).
  • handler.ts — _threadRootId is threaded through all three room-history call sites (recordPending, prepareTrigger, consumeHistory).
  • messages.ts — Matrix read actions accept threadId; thread reads use the untyped v1 /relations/{threadId} endpoint with recurse: true, hydrate returned events, and filter by native thread root client-side; main-room reads filter out direct and indirect thread events and over-fetch to compensate.
  • tool-actions.ts — threadId is parsed and forwarded in sendMessage and readMessages action handlers.
  • send/formatting.ts — buildThreadRelation no longer unconditionally includes is_falling_back and m.in_reply_to; fallback metadata is only added when an explicit replyToId is supplied.
  • send.ts (editMessageMatrix) — when editing a threaded message, thread context now goes in m.new_content["m.relates_to"] (per spec) rather than the outer REPLACE relation level (which caused main-room surface via m.in_reply_to).

• What did NOT change: Session routing, DM allowlists, reaction handling, non-threaded group rooms, Telegram, or any other channel. The channels.matrix.dm.threadReplies config key already existed in the schema; no config schema changes are needed.

• Verification in this port:

  • focused Matrix tests passed: 4 files, 74 tests
  • extension TypeScript compile passed via tsconfig.extensions.json

Why This Is The Right OpenClaw Direction

This PR does not introduce a new threading model for OpenClaw. It brings the Matrix
extension into line with the isolation model that the Telegram extension already uses
for forum topics and DM topics.

Current Telegram behavior already treats thread identity as conversation identity:

• outbound sends preserve message_thread_id rather than stripping it, even in DMs,
  because silently dropping thread scope would misroute replies
• group session keys are built from chatId + messageThreadId, so topic traffic does
  not collapse into one flat group session
• session/thread binding logic persists topic-qualified conversation IDs such as
  -100200300:topic:77

In other words, Telegram in OpenClaw already behaves as "topic/thread = isolated
conversation scope". This Matrix change applies the same principle:

• thread root ID becomes part of history and watermark scope
• thread reads use the thread-specific endpoint
• main-room reads stop absorbing thread traffic by default
• thread sends stop advertising themselves as main-timeline fallbacks unless that
  fallback is explicitly requested

That consistency matters because it reduces channel-specific surprises:

• Telegram topics already preserve context isolation
• Matrix threads should not be the one major threaded channel where all room traffic
  still bleeds into every thread

Matrix vs Telegram Contrast

Telegram today

• Thread/topic identity is carried explicitly in outbound send params as
  message_thread_id.
• Session identity for group traffic includes thread/topic identity.
• Conversation binding persists topic-qualified IDs like chat:topic:thread.
• The implementation is deliberately cautious about not stripping thread scope, because
  that would misroute replies.

Matrix before this PR

• Thread identity was detected, but not consistently propagated into room-history
  storage and reads.
• History remained effectively flat per room.
• Main-room reads included thread traffic.
• Thread sends always advertised a fallback main-timeline reply shape.

Matrix after this PR

• Thread identity becomes part of inbound history scope, watermark scope, and read
  scope.
• Main-room reads exclude thread traffic by default.
• Thread sends stay thread-only unless a caller explicitly asks for fallback reply
  metadata.

The net effect is that Matrix becomes behaviorally much closer to Telegram’s proven
topic-isolation model.

Change Type

• Bug fix
• Feature
• Refactor required for the fix
• Docs
• Security hardening
• Chore/infra

Scope

• Gateway / orchestration
• Skills / tool execution
• Auth / tokens
• Memory / storage
• Integrations ← Matrix extension
• API / contracts
• UI / DX
• CI/CD / infra

Linked Issue / PR

• Closes #(thread leak / flat history issue)
• Related: existing channels.matrix.threadReplies config, threads.ts, thread-context.ts

Root Cause

Flat room history (inbound context leak):
room-history.ts maintained a single queue per room. handler.ts resolved _threadRootId correctly but never forwarded it into recordPending, prepareTrigger, or consumeHistory, so all room traffic — regardless of thread — was merged into one context window.

Reply placement leak (outbound):
buildThreadRelation in send/formatting.ts unconditionally returned:

{ "rel_type": "m.thread", "event_id": "$root",
  "is_falling_back": true,
  "m.in_reply_to": { "event_id": "$root" } }

The is_falling_back / m.in_reply_to combination is the spec signal for clients that do not support threads to surface the message in the main timeline. Supporting clients (Element Web) also respect it, resulting in visible duplicate messages.

Edit leak (editMessageMatrix):
When draft-stream previews were finalized via editMessageMatrix, the REPLACE event carried m.in_reply_to: { event_id: threadRoot } at the outer relation level. Because threadRoot is often the user's original DM (a main-room event), Synapse and some clients surfaced edited thread messages as replies to main-room events.

• Root cause: _threadRootId was resolved but not propagated; fallback metadata was unconditional; REPLACE events carried reply context at the wrong nesting level.
• Missing detection: no tests asserted that thread sends omit is_falling_back; no tests asserted thread-scoped history isolation.
• Contributing context: Matrix's optional is_falling_back semantics are easy to misread as "required for thread sends."

Prior Art In OpenClaw

Telegram already contains the core architectural pattern this PR is moving Matrix
toward:

• extensions/telegram/src/send.ts
  • preserves message_thread_id and explicitly warns against stripping DM topic
    thread IDs because doing so misroutes replies
• extensions/telegram/src/bot-core.ts
  • builds group session keys from buildTelegramGroupPeerId(chatId, messageThreadId)
• extensions/telegram/src/thread-bindings.test.ts
  • persists topic-qualified conversation IDs such as -100200300:topic:77

This is useful upstream context because it shows OpenClaw already endorses
thread/topic-qualified conversation identity on another major channel.

Files Changed

extensions/matrix/src/matrix/monitor/room-history.ts       core change
extensions/matrix/src/matrix/monitor/handler.ts            core change
extensions/matrix/src/matrix/actions/messages.ts           core change
extensions/matrix/src/tool-actions.ts                      core change
extensions/matrix/src/matrix/send/formatting.ts            bug fix
extensions/matrix/src/matrix/send.ts                       bug fix

extensions/matrix/src/matrix/monitor/room-history.test.ts  new tests
extensions/matrix/src/matrix/send.test.ts                   updated + new tests
extensions/matrix/src/matrix/actions/messages.test.ts       new tests (thread read path)

Verification

Commands used during the upstream port:

OPENCLAW_VITEST_INCLUDE_FILE=<tmp-json> vitest run --config test/vitest/vitest.extension-matrix.config.ts
node scripts/run-tsgo.mjs -p tsconfig.extensions.json --incremental --tsBuildInfoFile .artifacts/tsgo-cache/matrix-thread-pr.tsbuildinfo

Focused test result:

Test Files  3 passed (3)
Tests       58 passed (58)

Coverage added by this PR includes:

• thread-only room-history queues stay isolated from main-room queues
• thread watermarks advance independently
• main-room reads filter out thread traffic
• thread reads use the all-event-type relations endpoint, hydrate encrypted events, summarize polls, and include the root event once
• thread sends omit fallback metadata unless explicitly requested
• threaded edits keep thread context on m.new_content

Key Diffs

send/formatting.ts — buildThreadRelation

Before:

export function buildThreadRelation(threadId: string, replyToId?: string): MatrixThreadRelation {
  const trimmed = threadId.trim();
  return {
    rel_type: RelationType.Thread,
    event_id: trimmed,
    is_falling_back: true,
    "m.in_reply_to": { event_id: replyToId?.trim() || trimmed },
  };
}

After:

export function buildThreadRelation(threadId: string, replyToId?: string): MatrixThreadRelation {
  const trimmed = threadId.trim();
  const relation: MatrixThreadRelation = {
    rel_type: RelationType.Thread,
    event_id: trimmed,
  };
  const fallbackReplyToId = replyToId?.trim();
  if (fallbackReplyToId) {
    relation.is_falling_back = true;
    relation["m.in_reply_to"] = { event_id: fallbackReplyToId };
  }
  return relation;
}

send.ts — editMessageMatrix thread context placement

Before:

const threadId = normalizeThreadId(opts.threadId);
if (threadId) {
  // Thread-aware replace: Synapse needs the thread context...
  replaceRelation["m.in_reply_to"] = { event_id: threadId };
}

After:

const threadId = normalizeThreadId(opts.threadId);
if (threadId) {
  // Per Matrix spec, m.new_content must carry the same thread relation
  // as the original event. Placing it here (not in the outer replace relation)
  // keeps Synapse thread indexing correct without surfacing the edit event
  // as a reply to the thread root in the main room timeline.
  (newContent as Record<string, unknown>)["m.relates_to"] = buildThreadRelation(threadId);
}

room-history.ts — thread sub-queues (abbreviated)

type RoomQueue = {
  entries: HistoryEntry[];
  baseIndex: number;
  generation: number;
  preparedTriggers: Map<string, PreparedTriggerResult>;
  threadQueues: Map<string, ThreadSubQueue>;   // ← new
};

// recordPending routes by threadRootId:
recordPending(roomId: string, entry: HistoryEntry, threadRootId?: string): void

// Watermark scope includes thread:
wmKey() → JSON.stringify({ agentId, roomId, scope: threadRootId ?? "main" })

handler.ts — _threadRootId threading

Three call sites updated:

roomHistoryTracker.recordPending(roomId, pendingEntry, _threadRootId);
roomHistoryTracker.prepareTrigger(_route.agentId, roomId, historyLimit, {...}, _threadRootId);
roomHistoryTracker.consumeHistory(_route.agentId, roomId, triggerSnapshot, _messageId, _threadRootId);

messages.ts — thread-aware reads

// Thread read: uses relations endpoint
GET /_matrix/client/v1/rooms/{roomId}/relations/{threadId}/m.thread

// Main-room read: filters out thread events
function isThreadEvent(event: MatrixRawEvent): boolean {
  return event.content?.["m.relates_to"]?.rel_type === "m.thread";
}
// + over-fetch multiplier to compensate for filtered events

Test Plan

Tests that must change

send.test.ts — existing test asserts pre-fix behavior:

// Before (incorrect — asserts the leak):
expect(content["m.relates_to"]).toMatchObject({
  rel_type: "m.thread",
  event_id: "$thread",
  "m.in_reply_to": { event_id: "$thread" },   // ← this must go
});

// After (correct):
expect(content["m.relates_to"]).toMatchObject({
  rel_type: "m.thread",
  event_id: "$thread",
});
expect(content["m.relates_to"]).not.toHaveProperty("is_falling_back");
expect(content["m.relates_to"]).not.toHaveProperty("m.in_reply_to");

New tests to add

send.test.ts:

• Thread send without replyToId → no is_falling_back, no m.in_reply_to
• Thread send with explicit replyToId → includes is_falling_back + m.in_reply_to
• editMessageMatrix with threadId → m.new_content contains thread relation; outer REPLACE relation has no m.in_reply_to

room-history.test.ts:

• recordPending with threadRootId routes to thread sub-queue
• prepareTrigger scoped to thread returns only that thread's entries
• consumeHistory advances watermark per thread independently
• Main-room and thread histories do not cross-contaminate
• Thread sub-queue FIFO eviction at MAX_THREAD_QUEUES_PER_ROOM

messages.test.ts:

• readMatrixMessages with threadId → uses relations endpoint, includes root event
• readMatrixMessages without threadId → main-room endpoint, filters out thread events
• Over-fetch compensates for filtered events on subsequent pages

Diagram

Before (flat history):
  DM room messages:  [A][B][C][T1a][T1b][T2a]
  Thread T1 context: [A][B][C][T1a][T1b][T2a]  ← entire room mixed in
  Thread T2 context: [A][B][C][T1a][T1b][T2a]  ← same flat soup

After (thread-scoped):
  DM room messages:  [A][B][C]
  Thread T1 context: [T1a][T1b]                 ← only T1's turns
  Thread T2 context: [T2a]                       ← only T2's turns

Before (send leak):
  Thread reply:  { rel_type: "m.thread", is_falling_back: true, m.in_reply_to: $root }
  Visible in:    thread timeline + main room timeline

After (thread-only send):
  Thread reply:  { rel_type: "m.thread" }        ← no fallback metadata
  Visible in:    thread timeline only

User-visible / Behavior Changes

• Thread replies no longer appear as duplicate messages in the main room timeline.
• Each Matrix thread now has its own isolated LLM context — replies in thread T1 do not see messages from thread T2 or from the main room.
• editMessageMatrix for threaded messages correctly places thread context in m.new_content per the Matrix spec; Synapse keeps edited messages in the thread timeline.
• Callers of buildThreadRelation that relied on unconditional is_falling_back must now pass an explicit replyToId to preserve that behavior. No production caller currently does this.
• Config: channels.matrix.dm.threadReplies already existed; setting it to "always" now reliably keeps all DM replies thread-scoped. No new config keys.
• Behavioral alignment: Matrix now behaves more like Telegram topics in OpenClaw, where
  thread/topic traffic is treated as its own conversation scope instead of flattening
  into the parent room.

Security Impact

• New permissions/capabilities? No
• Secrets/tokens handling changed? No
• New/changed network calls? Yes — thread reads use a different Matrix endpoint (/relations/{threadId} with recurse: true). Same auth, same homeserver, narrower scope.
• Command/tool execution surface changed? No
• Data access scope changed? Yes — agents receive narrower context (thread-only history instead of full room). This is a reduction in scope, not an expansion.
• Risk/mitigation: None beyond standard Matrix API call behavior.

Repro + Verification

Environment

• Runtime: Docker container, OpenClaw gateway
• Channel: Matrix DM with channels.matrix.dm.threadReplies = "always"
• Model: any (context isolation is pre-model)

Steps

1. Configure channels.matrix.dm.threadReplies = "always".
2. Send DM message A → bot replies in thread T1 (rooted at A).
3. Send DM message B (new message, not in T1) → bot replies in thread T2 (rooted at B).
4. Reply to thread T1 with message C.
5. Inspect the context.compiled entry in the bot's trajectory JSONL for the T1 reply to C.

Expected

• Trajectory shows messages_to_llm: 2 (A + T1 bot reply) — not 4 or more.
• Bot reply is in thread T1, not visible in main room timeline.
• Thread T2 exists independently; its context.compiled shows messages_to_llm: 0 then messages_to_llm: 2 (only B + T2 reply), with no T1 content.

Actual (pre-fix)

• All DM messages + all thread replies merged into a single context.
• Thread replies appeared in main room timeline via is_falling_back.
• Draft-stream edits re-introduced m.in_reply_to to the main room even after the initial send was corrected.

Evidence

• Trajectory JSONL inspection confirmed messages_to_llm: 2 for a thread reply with 1 prior exchange (session file named *-topic-$<threadRootId>.trajectory.jsonl).
• Main room session showed separate trajectory file with its own independent history.
• grep -c 'replaceRelation\["m.in_reply_to"\]' dist/send-*.js → 0 after fix (confirmed in deployed container).
• Compiled send bundle contains newContent["m.relates_to"] = buildThreadRelation(threadId) (per-spec placement).

Human Verification

• Verified: thread replies stay in thread, not visible in main DM room timeline (live Matrix client, post-fix restart).
• Verified: context.compiled.messages in trajectory JSONL contains only thread-scoped messages.
• Verified: send bundle reflects both fixes (bundle grep, source file inspection).
• Verified: existing focused Matrix test suite passes (room-history.test.ts, threads.test.ts, send.test.ts, messages.test.ts).
• Not yet verified: behavior across non-DM group rooms with active threads (only DM threading tested live); behavior with encrypted rooms (logic is pre-encryption layer).

Real behavior proof

• Behavior or issue addressed: Matrix native thread reads now exercise the current untyped recursive v1 relations path, keep thread reads isolated by native thread root, preserve indirect child relations under threaded events, and avoid default fallback reply metadata in thread reply payloads. Current PR head is 60b0c9244f01d1e99c74e47c285e84a81a138970 after rebasing onto current origin/main; the Matrix implementation diff exercised by the live proof is unchanged by the rebase.
• Real environment tested: Karabo OpenClaw Matrix runtime credentials against the live Matrix/Synapse-compatible homeserver. The proof used a temporary private Matrix room; raw tokens, room IDs, and event IDs are redacted and represented only as hashes.
• Exact steps or command run after this patch: On 2026-05-14T08:05:36Z, using the current Matrix implementation, then rebased cleanly to head 60b0c9244f01d1e99c74e47c285e84a81a138970; created a temporary private Matrix room, sent one main-room message, two native thread roots, one direct m.thread reply under each root, and one indirect m.replace edit relation under Thread A's reply. Queried GET /_matrix/client/v1/rooms/{roomId}/relations/{threadRootId}?dir=f&limit=20&recurse=true with no /m.thread or /m.room.message path segment, then applied the same bounded parent-chain thread filter used by readMatrixMessages({ threadId }).
• Evidence after fix: Redacted copied live output from the current-head real Matrix setup. Summary: captured at 2026-05-14T08:05:36Z; runtime account hash e51963bdfce8; homeserver hash 74c7bd2b1a2b; room hash b4f71058d518; request path GET /_matrix/client/v1/rooms/{roomId}/relations/{threadRootId}?dir=f&limit=20&recurse=true; stale typed /m.thread and /m.thread/m.room.message path segments were not used; Thread A relation hashes ['2eac1aa671a0', '498a5a89fcf4']; Thread B relation hashes ['3b22215ca715']; Thread A filtered hashes ['667870547242', '2eac1aa671a0', '498a5a89fcf4']; Thread B filtered hashes ['938b4b1e0d0f', '3b22215ca715']; cleanup left temporary proof room. Full redacted output:

{
  "captured_at_utc": "2026-05-14T08:05:36Z",
  "checks": {
    "client_filter_excludes_unrelated_main": true,
    "client_filter_includes_thread_a_root_reply_edit": true,
    "edit_a_is_indirect_child_relation": true,
    "recursive_query_used": true,
    "reply_a_fallback_absent": true,
    "reply_b_fallback_absent": true,
    "thread_a_direct_reply_returned": true,
    "thread_a_excludes_thread_b_reply": true,
    "thread_a_indirect_edit_returned": true,
    "thread_b_direct_reply_returned": true,
    "thread_b_excludes_thread_a_reply": true,
    "typed_m_thread_segment_absent": true,
    "untyped_endpoint_path_used": true
  },
  "cleanup": "left temporary proof room",
  "current_head_client_side_filter_result": {
    "thread_a_filtered_event_hashes": [
      "667870547242",
      "2eac1aa671a0",
      "498a5a89fcf4"
    ],
    "thread_b_filtered_event_hashes": [
      "938b4b1e0d0f",
      "3b22215ca715"
    ]
  },
  "current_request_path_template": "GET /_matrix/client/v1/rooms/{roomId}/relations/{threadRootId}?dir=f&limit=20&recurse=true",
  "event_hashes": {
    "main": "f6ffd45208ab",
    "thread_a_indirect_edit": "498a5a89fcf4",
    "thread_a_reply": "2eac1aa671a0",
    "thread_a_root": "667870547242",
    "thread_b_reply": "3b22215ca715",
    "thread_b_root": "938b4b1e0d0f"
  },
  "homeserver_hash": "74c7bd2b1a2b",
  "overall_real_behavior_proof_passed": true,
  "pr_head": "60b0c9244f01d1e99c74e47c285e84a81a138970",
  "reply_relation_shapes": {
    "thread_a_has_is_falling_back": false,
    "thread_a_has_m_in_reply_to": false,
    "thread_a_indirect_edit_relation_keys": [
      "event_id",
      "rel_type"
    ],
    "thread_a_relation_keys": [
      "event_id",
      "rel_type"
    ],
    "thread_b_has_is_falling_back": false,
    "thread_b_has_m_in_reply_to": false,
    "thread_b_relation_keys": [
      "event_id",
      "rel_type"
    ]
  },
  "room_hash": "b4f71058d518",
  "runtime_account_hash": "e51963bdfce8",
  "untyped_recursive_relations": {
    "thread_a_next_batch_present": false,
    "thread_a_prev_batch_present": false,
    "thread_a_relation_event_hashes": [
      "2eac1aa671a0",
      "498a5a89fcf4"
    ],
    "thread_b_next_batch_present": false,
    "thread_b_prev_batch_present": false,
    "thread_b_relation_event_hashes": [
      "3b22215ca715"
    ]
  }
}

• Observed result after fix: The untyped recursive relations response for Thread A returned Thread A's direct reply and the indirect edit relation under that reply; the Thread B response returned only Thread B's reply. The current-head client-side filter kept Thread A root/reply/edit together, kept Thread B root/reply together, excluded the unrelated main-room message, and did not cross-contaminate Thread A and Thread B. Direct thread reply relation payloads contained only event_id and rel_type; is_falling_back and m.in_reply_to were absent. The temporary proof room was left after the run. Overall proof passed: True.
• What was not tested: Live encrypted Matrix rooms, live non-DM group rooms, and live multi-page relation pagination were not tested in this proof. Those paths remain covered by focused tests and source inspection; this proof specifically covers the current untyped recursive relations path and indirect child-relation filtering requested by ClawSweeper.

Compatibility / Migration

• Backward compatible? Yes
• Config/env changes? No — dm.threadReplies already in schema; defaults unchanged
• Migration needed? No

The only breaking change is for callers of buildThreadRelation that depended on the unconditional is_falling_back. No such callers exist outside the extension.

Risks and Mitigations

• Risk: Synapse loses thread timeline membership for edited messages if it relied on the outer m.in_reply_to in REPLACE events.

  • Mitigation: Per Matrix spec, REPLACE events determine thread membership from m.new_content["m.relates_to"], not the outer REPLACE relation. Test confirmed edited messages remain in thread timeline post-fix.

• Risk: Thread sub-queue memory growth in rooms with many long-lived threads.

  • Mitigation: MAX_THREAD_QUEUES_PER_ROOM = 50 cap with FIFO eviction; per-queue entry cap inherited from room queue.

• Risk: Over-fetch multiplier for main-room reads (3×) could increase Matrix API call volume.

  • Mitigation: Multiplier only applies when thread events are present; first page respects requested limit exactly; subsequent pages only over-fetch if first page was under-limit after filtering.

• Risk: messages.test.ts thread read path tests require mocking the /relations endpoint.

  • Mitigation: Existing test harness already mocks Matrix client responses; thread endpoint mock follows same pattern.