Skip to content

docs(msteams): document replyStyle resolution precedence and thread context preservation#78835

Merged
amknight merged 2 commits intoopenclaw:mainfrom
harrisali0101:docs/msteams-replystyle-clarity
May 7, 2026
Merged

docs(msteams): document replyStyle resolution precedence and thread context preservation#78835
amknight merged 2 commits intoopenclaw:mainfrom
harrisali0101:docs/msteams-replystyle-clarity

Conversation

@harrisali0101
Copy link
Copy Markdown
Contributor

@harrisali0101 harrisali0101 commented May 7, 2026

Summary

Adds two subsections under the existing Reply style: threads vs posts section in docs/channels/msteams.md:

  1. Resolution precedence — explicit chain (per-channel → per-team → global → implicit default), plus the requireMention-derived implicit default that's currently undocumented (requireMention: true → thread, false → top-level).
  2. Thread context preservation — describes the behavior that fix(msteams): preserve proactive thread replies #78387 cemented: when replyStyle: thread is in effect, the original thread root (;messageid=<root>) is re-attached to outbound conversation references on both live and proactive sends. Notes the threadId ?? activityId fallback for legacy stored refs, and the deliberate "no thread suffix" behavior for replyStyle: top-level.

Why

We hit production confusion on a requireMention: false Teams channel where bot replies kept landing at the channel root instead of in the thread. The existing docs explain the Posts-vs-Threads UI tradeoff but don't surface that replyStyle defaults are conditional on requireMention, nor that thread-root context preservation depends on whether the replyStyle: thread branch is taken at send-time. Operators with no source-level visibility have nowhere to anchor their debugging.

After applying patch-package against 5.5 (until #78387 ships) and pinning replyStyle: "thread" explicitly per the precedence rules, every reply lands in the right place. Wanted that knowledge written down so the next operator doesn't re-discover it.

Real behavior proof

Pure documentation change — no source / runtime / config / surface impact. No tests, lint, or build steps to validate beyond the markdown render. Diff is +21/-0 in a single file.

Rendered preview (the two new subsections live under Reply style: threads vs posts → after the per-channel config example):

Resolution precedence — When the bot sends a reply into a channel, replyStyle is resolved from the most specific override down to the default. The first non-undefined value wins: per-channel, per-team, global, implicit default (derived from requireMention). […]

Thread context preservation — When replyStyle: thread is in effect and the bot was @mentioned from inside a channel thread, OpenClaw re-attaches the original thread root to the outbound conversation reference. The thread root is taken from the stored threadId on the conversation reference; older stored refs fall back to activityId. […]

References:

  • Behavior described matches extensions/msteams/src/policy.ts:243-244 (implicit default) and extensions/msteams/src/messenger.ts:570-604 (thread-root preservation, after fix(msteams): preserve proactive thread replies #78387).
  • Resolution chain matches extensions/msteams/src/policy.ts:239-241.

Checklist

  • American English
  • Single-purpose docs change, no mixed concerns
  • No CODEOWNERS-restricted files touched
  • No edits to behavior, tests, or config schema

@harrisali0101
docs(msteams): document replyStyle resolution precedence and thread c…
e201b46 
…ontext preservation

The existing replyStyle section explains the Posts-vs-Threads tradeoff but
doesn't document how the value is actually resolved at send-time, nor what
happens to thread-root context across configurations. Operators who hit
unexpected top-level posts (e.g., requireMention=false setups, long-running
agents whose proactive sends fall outside the live Bot Framework turn) have
no docs-side anchor for understanding which knob to flip.

Add two subsections under Reply Style:

1. Resolution precedence — channel > team > global > implicit default,
   plus the requireMention-derived implicit default.
2. Thread context preservation — describes that replyStyle=thread re-attaches
   the original thread root on outbound (live and proactive paths after
   openclaw#78387), with the threadId/activityId fallback for legacy stored refs.
   Calls out the deliberate "no thread suffix" behavior for replyStyle=top-level.

Pure documentation change, no behavior or surface impact.
@openclaw-barnacle openclaw-barnacle Bot added docs Improvements or additions to documentation channel: msteams Channel integration: msteams size: XS triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup. labels May 7, 2026
@harrisali0101 harrisali0101 mentioned this pull request May 7, 2026
Merged
@clawsweeper
Copy link
Copy Markdown
Contributor

clawsweeper Bot commented May 7, 2026 •
edited
Loading

Codex review: needs maintainer review before merge.

Summary
This PR adds Microsoft Teams docs for replyStyle resolution precedence, requireMention-derived defaults, and thread-root behavior for live and proactive replies.

Reproducibility: not applicable. this is a docs-only PR. The behavior being documented is source-verifiable in the Microsoft Teams policy, send-context, messenger, and focused tests.

Real behavior proof
Sufficient (live_output): For this docs-only change, the PR body includes an after-change rendered-preview excerpt of the new documentation and no runtime path changed.

Next step before merge
No repair lane; the PR has no narrow defect for automation and only needs normal maintainer review.

Security
Cleared: The diff only changes one markdown docs file and does not touch executable code, workflows, dependencies, secrets, or packaging.

Review details

Best possible solution:

Land the scoped docs update after normal maintainer review so operator-facing Microsoft Teams guidance matches existing reply policy and threading behavior.

Do we have a high-confidence way to reproduce the issue?

Not applicable: this is a docs-only PR. The behavior being documented is source-verifiable in the Microsoft Teams policy, send-context, messenger, and focused tests.

Is this the best way to solve the issue?

Yes: updating docs/channels/msteams.md is the narrow maintainable solution for documenting existing replyStyle precedence and thread-context behavior without changing runtime code.

What I checked:

Likely related people:

  • amknight: Merged the proactive thread reply implementation and tests that this docs PR describes in fix(msteams): preserve proactive thread replies #78387. (role: introduced behavior; confidence: high; commits: 28e27ca5d16a; files: extensions/msteams/src/messenger.ts, extensions/msteams/src/send-context.ts, extensions/msteams/src/messenger.test.ts)
  • vincentkoc: Recent history shows multiple maintenance edits to docs/channels/msteams.md immediately before this docs PR. (role: recent docs maintainer; confidence: medium; commits: 462b96b33fa9, f4a63940cc6d, 41268ded2d23; files: docs/channels/msteams.md)
  • steipete: Recent Microsoft Teams policy, messenger, and docs work touched the same behavior and surrounding files. (role: adjacent maintainer; confidence: medium; commits: 3f002b10d281, 7f3f108521f4, 08c4af0ddf62; files: extensions/msteams/src/policy.ts, extensions/msteams/src/messenger.ts, docs/channels/msteams.md)
  • sudie-codes: Earlier Microsoft Teams thread-routing work established related thread targeting behavior near the documented surface. (role: adjacent owner; confidence: medium; commits: 9edfefedf7bf; files: extensions/msteams/src/messenger.ts, extensions/msteams/src/monitor-handler/message-handler.ts, extensions/msteams/src/messenger.test.ts)

Codex review notes: model gpt-5.5, reasoning high; reviewed against 1ef85c7d4c30.

Re-review progress:

@clawsweeper clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 7, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 7, 2026
@clawsweeper clawsweeper Bot added the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 7, 2026
@openclaw-barnacle openclaw-barnacle Bot removed the proof: sufficient ClawSweeper judged the real behavior proof convincing. label May 7, 2026
@amknight
Copy link
Copy Markdown
Member

amknight commented May 7, 2026

LGTM

@amknight amknight merged commit 79d9b95 into openclaw:main May 7, 2026
40 of 43 checks passed
@github-actions github-actions Bot mentioned this pull request May 7, 2026
Open
@BradGroux BradGroux mentioned this pull request May 8, 2026
Draft
github-actions Bot pushed a commit to Desicool/openclaw that referenced this pull request May 9, 2026
@harrisali0101
docs(msteams): document replyStyle resolution precedence and thread c…
3eec863 
…ontext preservation (openclaw#78835)

The existing replyStyle section explains the Posts-vs-Threads tradeoff but
doesn't document how the value is actually resolved at send-time, nor what
happens to thread-root context across configurations. Operators who hit
unexpected top-level posts (e.g., requireMention=false setups, long-running
agents whose proactive sends fall outside the live Bot Framework turn) have
no docs-side anchor for understanding which knob to flip.

Add two subsections under Reply Style:

1. Resolution precedence — channel > team > global > implicit default,
   plus the requireMention-derived implicit default.
2. Thread context preservation — describes that replyStyle=thread re-attaches
   the original thread root on outbound (live and proactive paths after
   openclaw#78387), with the threadId/activityId fallback for legacy stored refs.
   Calls out the deliberate "no thread suffix" behavior for replyStyle=top-level.

Pure documentation change, no behavior or surface impact.
rogerdigital pushed a commit to rogerdigital/openclaw that referenced this pull request May 9, 2026
@harrisali0101 @rogerdigital
docs(msteams): document replyStyle resolution precedence and thread c…
a4828c5 
…ontext preservation (openclaw#78835)

The existing replyStyle section explains the Posts-vs-Threads tradeoff but
doesn't document how the value is actually resolved at send-time, nor what
happens to thread-root context across configurations. Operators who hit
unexpected top-level posts (e.g., requireMention=false setups, long-running
agents whose proactive sends fall outside the live Bot Framework turn) have
no docs-side anchor for understanding which knob to flip.

Add two subsections under Reply Style:

1. Resolution precedence — channel > team > global > implicit default,
   plus the requireMention-derived implicit default.
2. Thread context preservation — describes that replyStyle=thread re-attaches
   the original thread root on outbound (live and proactive paths after
   openclaw#78387), with the threadId/activityId fallback for legacy stored refs.
   Calls out the deliberate "no thread suffix" behavior for replyStyle=top-level.

Pure documentation change, no behavior or surface impact.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

channel: msteams Channel integration: msteams docs Improvements or additions to documentation size: XS triage: needs-real-behavior-proof Candidate: external PR needs after-fix proof from a real setup.

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@harrisali0101 @amknight