@gakr-gakr/matrix 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,285 @@
+# Changelog
+
+## 2026.5.19
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.5.17
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+### Fixes
+
+- Matrix/E2EE: stop requesting MSC4222 `state_after` sync responses so homeservers with incomplete state-after data do not leave fresh encrypted rooms without outbound room encryptors. Fixes #82515. Thanks @nickdecooman.
+
+## 2026.5.16
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.5.14
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.5.12
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.5.10
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.5.8
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.5.6
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.5.4
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.5.3
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.5.2
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## Unreleased
+
+### Changes
+
+- Matrix/E2EE: add `autobot matrix encryption setup` to enable Matrix encryption, bootstrap recovery, and print verification status from one setup flow. Thanks @gumadeiras.
+
+### Fixes
+
+- Matrix/E2EE: close the owner-side device verification loop when SAS lands via the CLI. `verify confirm-sas` now (1) awaits the rust-crypto verifier promise so the done-exchange and any cross-signing uploads triggered by `crossSignDevice` settle before the verb returns, (2) cross-signs the bot device on the auto-confirmed inbound SAS path (previously skipped), and (3) calls `trustOwnIdentityAfterSelfVerification` from the standalone `confirmMatrixVerificationSas` action so the operator's Element X clears the "Verify" prompt without waiting for a passive sync tick [AI-assisted]. Thanks @nklock.
+- Matrix/E2EE: stabilize recovery and broken-device QA flows while avoiding device-cleanup sync races that could leave shutdown-time crypto work running. Thanks @gumadeiras.
+
+## 2026.4.25
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.4.20
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+## 2026.4.19-beta.1
+
+### Changes
+
+- Version alignment with core AutoBot release numbers.
+
+This file tracks Matrix-related release notes for the local `@gakr-gakr/matrix`
+plugin since the `matrix-js-sdk` migration. Source release notes live in
+`../../changelog.md`; exact repeated entries inside the same version are
+collapsed here.
+
+## 2026.4.15-beta.2
+
+### Fixes
+
+- Matrix/pairing: block DM pairing-store entries from authorizing room control commands [AI-assisted]. (#67294) Thanks @pgondhi987.
+- Docker/build: verify `@matrix-org/matrix-sdk-crypto-nodejs` native bindings with `find` under `node_modules` instead of a hardcoded `.pnpm/...` path so pnpm v10+ virtual-store layouts no longer fail the image build. (#67143) thanks @ly85206559.
+- Matrix/E2EE: keep startup bootstrap conservative for passwordless token-auth bots, still attempt the guarded repair pass without requiring `channels.matrix.password`, and document the remaining password-UIA limitation. (#66228) Thanks @SARAMALI15792.
+- Matrix/commands: skip DM pairing-store reads on room traffic now that room control-command authorization ignores pairing-store entries, keeping the room path narrower without changing room auth behavior. (#67325) Thanks @gumadeiras.
+
+## 2026.4.15-beta.1
+
+### Changes
+
+- QA/Matrix: split Matrix live QA into a source-linked `qa-matrix` runner and keep repo-private `qa-*` surfaces out of packaged and published builds. (#66723) Thanks @gumadeiras.
+
+### Fixes
+
+- Matrix/security: normalize sandboxed profile avatar params, preserve `mxc://` avatar URLs, and surface gmail watcher stop failures during reload. (#64701) Thanks @slepybear.
+- Docker/build: verify `@matrix-org/matrix-sdk-crypto-nodejs` native bindings with `find` under `node_modules` instead of a hardcoded `.pnpm/...` path so pnpm v10+ virtual-store layouts no longer fail the image build. (#67143) Thanks @ly85206559.
+- Matrix/E2EE: keep startup bootstrap conservative for passwordless token-auth bots, still attempt the guarded repair pass without requiring `channels.matrix.password`, and document the remaining password-UIA limitation. (#66228) Thanks @SARAMALI15792.
+- Matrix/commands: skip DM pairing-store reads on room traffic now that room control-command authorization ignores pairing-store entries, keeping the room path narrower without changing room auth behavior. (#67325) Thanks @gumadeiras.
+- Matrix/security: block DM pairing-store entries from authorizing room control commands. (#67294) Thanks @pgondhi987.
+
+## 2026.4.12
+
+### Changes
+
+- Matrix/partial streaming: add MSC4357 live markers to draft preview sends and edits so supporting Matrix clients can render a live/typewriter animation and stop it when the final edit lands. (#63513) Thanks @TigerInYourDream.
+
+### Fixes
+
+- Matrix/mentions: keep room mention gating strict while accepting visible `@displayName` Matrix URI labels, so `requireMention` works for non-AutoBot Matrix clients again. (#64796) Thanks @hclsys.
+- Channels/replay dedupe: standardize replay claims, retryable-failure release, and post-success commit behavior across Telegram, Discord, Slack, Mattermost, WhatsApp, Matrix, LINE, Feishu, Zalo, Nextcloud Talk, TLON, Nostr, Voice Call, and shared plugin interactive callbacks so duplicate deliveries stay reply-once after success but retry cleanly after pre-delivery failures. Thanks @vincentkoc.
+
+## 2026.4.10
+
+### Changes
+
+- QA/Matrix: add a live `autobot qa matrix` lane backed by a disposable Matrix homeserver, shared live-transport seams, and Matrix-specific transport coverage for threading, reactions, restart, and allowlist behavior. (#64489) Thanks @gumadeiras.
+- Matrix/partial streaming: add MSC4357 live markers to draft preview sends and edits so supporting Matrix clients can render a live/typewriter animation and stop it when the final edit lands. (#63513) Thanks @TigerInYourDream.
+
+### Fixes
+
+- Gateway/thread routing: preserve Slack, Telegram, Mattermost, Matrix, ACP, restart-sentinel, and agent announce delivery targets so subagent, cron, stream-relay, session fallback, and restart messages land back in the originating thread, topic, or room casing. (#54840, #57056, #63143, #63228, #63506, #64343, #64391)
+- Matrix: keep multi-account room scoping consistent, keep packaged crypto migrations warning-only when appropriate, preserve ordered block streaming, add explicit Matrix block-streaming opt-in, and resolve verification/bootstrap from the packaged runtime entry. (#58449, #59249, #59266, #64373) Thanks @gumadeiras.
+- Matrix/migration: keep packaged warning-only crypto migrations from being misclassified as actionable when only helper chunks are present, so startup and doctor stay on the warning-only path instead of creating unnecessary migration snapshots. (#64373) Thanks @gumadeiras.
+- Matrix/ACP thread bindings: preserve canonical room casing and parent conversation routing during ACP session spawn so mixed-case room ids bind correctly from top-level rooms and existing Matrix threads. (#64343) Thanks @gumadeiras.
+
+## 2026.4.9
+
+### Fixes
+
+- Matrix/gateway: wait for Matrix sync readiness before marking startup successful, keep Matrix background handler failures contained, and route fatal Matrix sync stops through channel-level restart handling instead of crashing the whole gateway. (#62779) Thanks @gumadeiras.
+- Matrix/doctor: migrate legacy `channels.matrix.dm.policy: "trusted"` configs back to compatible DM policies during `autobot doctor --fix`, preserving explicit `allowFrom` boundaries as `allowlist` and defaulting empty legacy configs to `pairing`. (#62942) Thanks @lukeboyett.
+
+## 2026.4.8
+
+### Fixes
+
+- Bundled channels/setup: load shared secret contracts through packaged top-level sidecars across Feishu, Google Chat, IRC, Matrix, Mattermost, Microsoft Teams, Nextcloud Talk, Slack, and Zalo so installed npm builds no longer rely on missing `dist/extensions/*/src/*` files during gateway startup.
+
+## 2026.4.7
+
+### Fixes
+
+- Matrix/onboarding: add an invite auto-join setup step with explicit off warnings and strict stable-target validation so new Matrix accounts stop silently ignoring invited rooms and fresh DM-style invites unless operators opt in. (#62168) Thanks @gumadeiras.
+- Matrix/formatting: preserve multi-paragraph and loose-list rendering in Element so numbered and bulleted Markdown keeps their content attached to the correct list item. (#60997) Thanks @gucasbrg.
+- Matrix/agents: hide owner-only `set-profile` from embedded agent channel-action discovery so non-owner runs stop advertising profile updates they cannot execute. (#62662) Thanks @eleqtrizit.
+
+## 2026.4.5
+
+### Changes
+
+- Matrix/exec approvals: add Matrix-native exec approval prompts with account-scoped approvers, channel-or-DM delivery, and room-thread aware resolution handling. (#58635) Thanks @gumadeiras.
+- Matrix/exec approvals: clarify unavailable-approval replies so Matrix no longer claims chat approvals are unsupported when native exec approvals are merely unconfigured. (#61424) Thanks @gumadeiras.
+
+### Fixes
+
+- Matrix/exec approvals: anchor seeded approval reactions to the primary Matrix prompt event, resolve them from event metadata instead of prompt text, and clean up chunked approval prompts correctly. (#60931) Thanks @gumadeiras.
+- Matrix: recover more reliably when secret storage or recovery keys are missing by recreating secret storage during repair and backup reset, hold crypto snapshot locks during persistence, and surface explicit too-large attachment markers. (#59846, #59851, #60599, #60289) Thanks @al3mart, @emonty, and @efe-arv.
+- Matrix/DM sessions: add `channels.matrix.dm.sessionScope`, shared-session collision notices, and aligned outbound session reuse so separate Matrix DM rooms can keep distinct context when configured. (#61373) Thanks @gumadeiras.
+- Matrix: move legacy top-level `avatarUrl` into the default account during multi-account promotion and keep env-backed account setup avatar config persisted. (#61437) Thanks @gumadeiras.
+- Matrix/streaming: add a quiet preview mode for streamed Matrix replies, keep legacy `partial` preview-first behavior, and finalize quiet media captions correctly so previews stop notifying early without dropping final text semantics. (#61450) Thanks @gumadeiras.
+- Matrix: keep direct transport requests on the pinned dispatcher by routing them through undici runtime fetch, so Matrix clients resume syncing on newer runtimes without dropping the validated address binding. (#61595) Thanks @gumadeiras.
+- Matrix: avoid failing startup when token auth already knows the user ID but still needs optional device metadata, retry transient auth bootstrap requests, and backfill missing device IDs after startup while keeping unknown-device storage reuse conservative until metadata is repaired. (#61383) Thanks @gumadeiras.
+- Matrix: pass configured `deviceId` through health probes and keep probe-only client setup out of durable Matrix storage, so health checks preserve the correct device identity without rewriting `storage-meta.json` or related probe state on disk. (#61581) Thanks @MoerAI.
+- Matrix/plugin loading: ship and source-load the crypto bootstrap runtime sidecar correctly so current `main` stops warning about failed Matrix bootstrap loads and `matrix/index` plugin-id mismatches on every invocation. (#53298) thanks @keithce.
+- Plugins/Matrix: mirror the Matrix crypto WASM runtime dependency into the root packaged install and enforce root/plugin dependency parity so bundled Matrix E2EE crypto resolves correctly in shipped builds. (#57163) Thanks @gumadeiras.
+- Plugins/CLI: add descriptor-backed lazy plugin CLI registration so Matrix can keep its CLI module lazy-loaded without dropping `autobot matrix ...` from parse-time command registration. (#57165) Thanks @gumadeiras.
+- Matrix/delivery recovery: treat Synapse `User not in room` replay failures as permanent during startup recovery so poisoned queued messages move to `failed/` instead of crash-looping Matrix after restart. (#57426) thanks @dlardo.
+- Doctor/plugins: skip false Matrix legacy-helper warnings when no migration plans exist, and keep bundled `enabledByDefault` plugins in the gateway startup set. (#57931) Thanks @dinakars777.
+- Matrix/CLI send: start one-off Matrix send clients before outbound delivery so `autobot message send --channel matrix` restores E2EE in encrypted rooms instead of sending plain events. (#57936) Thanks @gumadeiras.
+- Matrix/direct rooms: stop trusting remote `is_direct`, honor explicit local `is_direct: false` for discovered DM candidates, and avoid extra member-state lookups for shared rooms so DM routing and repair stay aligned. (#57124) Thanks @w-sss.
+- Matrix/direct rooms: recover fresh auto-joined 1:1 DMs without eagerly persisting invite-only `m.direct` mappings, while keeping named, aliased, and explicitly configured rooms on the room path. (#58024) Thanks @gumadeiras.
+
+## 2026.4.2
+
+### Changes
+
+- Matrix/plugin: emit spec-compliant `m.mentions` metadata across text sends, media captions, edits, poll fallback text, and action-driven edits so Matrix mentions notify reliably in clients like Element. (#59323) Thanks @gumadeiras.
+
+## 2026.4.1-beta.1
+
+### Notes
+
+- Matrix/onboarding: restore guided setup in `autobot channels add` and `autobot configure --section channels`, while keeping custom plugin wizards on the shared `setupWizard` seam. (#59462) Thanks @gumadeiras.
+- Matrix/streaming: keep live partial previews for the current assistant block while preserving completed block updates as separate messages when `channels.matrix.blockStreaming` is enabled. (#59384) Thanks @gumadeiras.
+
+## 2026.3.31
+
+### Changes
+
+- Matrix/history: add optional room history context for Matrix group triggers via `channels.matrix.historyLimit`, with per-agent watermarks and retry-safe snapshots so failed trigger retries do not drift into newer room messages. (#57022) thanks @chain710.
+- Matrix/network: add explicit `channels.matrix.proxy` config for routing Matrix traffic through an HTTP(S) proxy, including account-level overrides and matching probe/runtime behavior. (#56931) thanks @patrick-yingxi-pan.
+- Matrix/streaming: add draft streaming so partial Matrix replies update the same message in place instead of sending a new message for each chunk. (#56387) Thanks @jrusz.
+- Matrix/threads: add per-DM `threadReplies` overrides and keep thread session isolation aligned with the effective room or DM thread policy from the triggering message onward. (#57995) thanks @teconomix.
+
+### Fixes
+
+- Doctor/plugins: skip false Matrix legacy-helper warnings when no migration plans exist, and keep bundled `enabledByDefault` plugins in the gateway startup set. (#57931) Thanks @dinakars777.
+
+## 2026.3.31-beta.1
+
+### Fixes
+
+- Matrix/CLI send: start one-off Matrix send clients before outbound delivery so `autobot message send --channel matrix` restores E2EE in encrypted rooms instead of sending plain events. (#57936) Thanks @gumadeiras.
+- Matrix/context: filter fetched room context by sender allowlists so reply and thread context lookup no longer pulls non-allowlisted messages into agent context. (#58376) Thanks @jacobtomlinson.
+- Matrix/delivery recovery: treat Synapse `User not in room` replay failures as permanent during startup recovery so poisoned queued messages move to `failed/` instead of crash-looping Matrix after restart. (#57426) thanks @dlardo.
+- Matrix/direct rooms: recover fresh auto-joined 1:1 DMs without eagerly persisting invite-only `m.direct` mappings, while keeping named, aliased, and explicitly configured rooms on the room path. (#58024) Thanks @gumadeiras.
+- Matrix/direct rooms: stop trusting remote `is_direct`, honor explicit local `is_direct: false` for discovered DM candidates, and avoid extra member-state lookups for shared rooms so DM routing and repair stay aligned. (#57124) Thanks @w-sss.
+- Matrix/DM threads: keep strict unnamed fresh-invite rooms promotable even when Matrix omits the optional direct hint, preserve repair-failed local DM promotions while still revalidating later room metadata, and keep both bound and thread-isolated Matrix sessions reporting the correct route policy. (#58099) Thanks @gumadeiras.
+- Matrix/plugin loading: ship and source-load the crypto bootstrap runtime sidecar correctly so current `main` stops warning about failed Matrix bootstrap loads and `matrix/index` plugin-id mismatches on every invocation. (#53298) thanks @keithce.
+- Plugins/CLI: add descriptor-backed lazy plugin CLI registration so Matrix can keep its CLI module lazy-loaded without dropping `autobot matrix ...` from parse-time command registration. (#57165) Thanks @gumadeiras.
+- Plugins/Matrix: mirror the Matrix crypto WASM runtime dependency into the root packaged install and enforce root/plugin dependency parity so bundled Matrix E2EE crypto resolves correctly in shipped builds. (#57163) Thanks @gumadeiras.
+
+## 2026.3.28
+
+### Changes
+
+- Plugins/Matrix TTS: send auto-TTS replies as native Matrix voice bubbles instead of generic audio attachments. (#37080) thanks @Matthew19990919.
+
+### Fixes
+
+- Matrix/replies: include quoted poll question/options in inbound reply context so the agent sees the original poll content when users reply to Matrix poll messages. (#55056) Thanks @alberthild.
+- Matrix/plugins: keep plugin bootstrap from crashing when built runtime mixes bare and deep `matrix-js-sdk` entrypoints, so unrelated channels do not get taken down during plugin load. (#56273) Thanks @aquaright1.
+- Matrix: keep separate 2-person rooms out of DM routing after `m.direct` seeds successfully, while still honoring explicit `is_direct` state and startup fallback recovery. (#54890) thanks @private-peter
+- Plugins/Matrix: preserve sender filenames for inbound media by forwarding `originalFilename` to `saveMediaBuffer`. (#55692) thanks @esrehmki.
+- Matrix/mentions: recognize `matrix.to` mentions whose visible label uses the bot's room display name, so `requireMention: true` rooms respond correctly in modern Matrix clients. (#55393) thanks @nickludlam.
+- Plugins/Matrix: prefer explicit DM signals when choosing outbound direct rooms and routing unmapped verification summaries, so strict 2-person fallback rooms do not outrank the real DM. (#56076) thanks @gumadeiras
+- Plugins/Matrix: resolve env-backed `accessToken` and `password` SecretRefs against the active Matrix config env path during startup, and officially accept SecretRef `accessToken` config values. (#54980) thanks @kakahu2015.
+- Plugins/Matrix: load bundled `@matrix-org/matrix-sdk-crypto-nodejs` through `createRequire(...)` so E2EE media send and receive keep the package-local native binding lookup working in packaged ESM builds. (#54566) thanks @joelnishanth.
+- Plugins/Matrix: encrypt E2EE image thumbnails with `thumbnail_file` while keeping unencrypted-room previews on `thumbnail_url`, so encrypted Matrix image events keep thumbnail metadata without leaking plaintext previews. (#54711) thanks @frischeDaten.
+
+## 2026.3.23
+
+### Fixes
+
+- Plugins/bundled runtimes: ship bundled plugin runtime sidecars like WhatsApp `light-runtime-api.js`, Matrix `runtime-api.js`, and other plugin runtime entry files in the npm package again, so global installs stop failing on missing bundled plugin runtime surfaces.
+- Plugins/Matrix: avoid duplicate `resolveMatrixAccountStringValues` runtime-api exports under source loaders so bundled Matrix installs no longer crash at startup with `Cannot redefine property: resolveMatrixAccountStringValues`. Fixes #52909 and #52891. Thanks @vincentkoc.
+
+## 2026.3.22
+
+### Breaking
+
+- Plugins/Matrix: add a new Matrix plugin backed by the official `matrix-js-sdk`. If you are upgrading from the previous public Matrix plugin, follow the migration guide: https://docs.openclaw.ai/install/migrating-matrix Thanks @gumadeiras.
+- Plugins/Matrix: stop mention-gated or otherwise dropped room chatter from refreshing focused thread bindings before the message is actually routed, so idle ACP and session bindings can still expire normally in mention-required rooms. Thanks @vincentkoc, @dinakars777 and @mvanhorn.
+- Plugins/Matrix: durably dedupe inbound room events across gateway restarts so previously handled Matrix messages are not replayed as new, while preserving clean-restart backlog delivery for unseen events. (#50922) thanks @gumadeiras
+
+### Changes
+
+- Plugins/Matrix: add `allowBots` room policy so configured Matrix bot accounts can talk to each other, with optional mention-only gating. Thanks @gumadeiras.
+- Plugins/Matrix: add per-account `allowPrivateNetwork` opt-in for private/internal homeservers, while keeping public cleartext homeservers blocked. Thanks @gumadeiras.
+
+### Fixes
+
+- Plugins/Matrix: move bundled plugin `KeyedAsyncQueue` imports onto the stable `plugin-sdk/core` surface so Matrix Docker/runtime builds do not depend on the brittle keyed-async-queue subpath. Thanks @ecohash-co and @vincentkoc.
+- Doctor/extensions: keep Matrix DM `allowFrom` repairs on the canonical `dm.allowFrom` path and stop treating Zalouser group sender gating as if it fell back to `allowFrom`, so doctor warnings and `--fix` stay aligned with runtime access control. Thanks @vincentkoc.
+- Matrix: make onboarding status runtime-safe (#49995) Thanks @joshavant.
+- Plugins/Matrix: accept shared send-tool media aliases (`mediaUrl`, `filePath`, `path`) and preserve `asVoice` / `audioAsVoice` through Matrix action dispatch so media-only sends and voice-message intents reach the plugin send layer correctly. Thanks @psacc and @vincentkoc.

package/SPEC-SUPPORT.md

@@ -0,0 +1,116 @@
+# Matrix Spec Support
+
+Current Matrix spec/event support tracked for the bundled Matrix plugin.
+
+Scope:
+
+- code-backed today-state only
+- plugin behavior only; not a claim of full Matrix spec coverage
+- update this file when adding or removing Matrix event/spec support
+
+Legend:
+
+- `in`: inbound handling
+- `out`: outbound send/edit/emit
+- `tools`: CLI/action/runtime tooling built on that surface
+
+## Support Matrix
+
+| Surface                  | Spec / event ids                                                                                   | Support      | Notes                                                                    | Evidence                                                                                                                   |
+| ------------------------ | -------------------------------------------------------------------------------------------------- | ------------ | ------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------- |
+| Core messages            | `m.room.message`                                                                                   | in/out/tools | base text/media message surface                                          | `src/matrix/send/types.ts`, `src/matrix/actions/messages.ts`                                                               |
+| Rich text                | `org.matrix.custom.html`                                                                           | out          | Markdown rendered to Matrix HTML                                         | `src/matrix/send/formatting.ts`                                                                                            |
+| Replies                  | `m.in_reply_to`                                                                                    | in/out       | reply relation support                                                   | `src/matrix/send/formatting.ts`                                                                                            |
+| Edits                    | `m.replace`                                                                                        | in/out/tools | Matrix edit flow; edit body uses `* <text>` fallback format              | `src/matrix/send/types.ts`, `src/matrix/draft-stream.test.ts`                                                              |
+| Threads                  | `m.thread`                                                                                         | in/out/tools | thread send, routing, session/thread policy                              | `src/matrix/send/types.ts`, `src/matrix/monitor/types.ts`, `src/matrix/monitor/threads.test.ts`                            |
+| Direct rooms             | `m.direct`                                                                                         | in/out/tools | DM routing, cache, repair, outbound target selection                     | `src/matrix/send/types.ts`, `src/matrix/sdk.ts`, `src/matrix/send/targets.test.ts`, `src/matrix/direct-management.test.ts` |
+| Reactions                | `m.reaction`, `m.annotation`                                                                       | in/out/tools | send, summarize, inbound reaction routing                                | `src/matrix/reaction-common.ts`, `src/matrix/monitor/reaction-events.test.ts`                                              |
+| Read receipts            | `m.read`                                                                                           | out          | sent on inbound message receipt                                          | `src/matrix/sdk.ts`, `src/matrix/monitor/handler.ts`                                                                       |
+| Typing                   | typing API                                                                                         | out          | typing keepalive while reply runs                                        | `src/matrix/sdk.ts`, `src/matrix/send.ts`, `src/matrix/monitor/handler.ts`                                                 |
+| Mentions                 | `m.mentions`                                                                                       | in/out/tools | stable mention metadata on sends/edits/media captions/poll fallback text | `src/matrix/send/formatting.ts`, `src/matrix/monitor/mentions.ts`, `src/matrix/send.test.ts`                               |
+| Mention link compat      | `https://matrix.to/#/...`                                                                          | in/out       | emit + validate visible-label mentions in formatted HTML                 | `src/matrix/format.ts`, `src/matrix/monitor/mentions.ts`                                                                   |
+| Polls                    | `m.poll.start`, `m.poll.response`, `m.poll.end`                                                    | in/out/tools | stable poll create/read/vote/summary flow                                | `src/matrix/poll-types.ts`, `src/matrix/actions/polls.ts`, `src/matrix/poll-summary.ts`                                    |
+| Poll compat              | `org.matrix.msc3381.poll.start`, `org.matrix.msc3381.poll.response`, `org.matrix.msc3381.poll.end` | in/out       | unstable poll compat still emitted/parsed where needed                   | `src/matrix/poll-types.ts`, `src/matrix/send.test.ts`                                                                      |
+| Poll relations           | `m.reference`                                                                                      | in/out/tools | poll votes/results linked to root poll event                             | `src/matrix/poll-types.ts`, `src/matrix/actions/polls.ts`, `src/matrix/poll-summary.ts`                                    |
+| Extensible text fallback | `org.matrix.msc1767.text`                                                                          | in/out       | poll text fallback/compat                                                | `src/matrix/poll-types.ts`                                                                                                 |
+| Voice messages           | `org.matrix.msc3245.voice`                                                                         | out          | voice-bubble marker on compatible audio sends                            | `src/matrix/send/media.ts`, `src/matrix/send/types.ts`                                                                     |
+| Voice audio metadata     | `org.matrix.msc1767.audio`                                                                         | out          | duration metadata for voice sends                                        | `src/matrix/send/media.ts`, `src/matrix/send/types.ts`                                                                     |
+| Location                 | `m.location`, `geo:`                                                                               | in           | inbound parse to text/context; no outbound location send tracked here    | `src/matrix/monitor/types.ts`, `src/matrix/monitor/location.ts`, `src/matrix/monitor/handler.ts`                           |
+| E2EE room events         | `m.room.encrypted`                                                                                 | in/out/tools | encrypted event hydration, decrypt, encrypted media send                 | `src/matrix/monitor/types.ts`, `src/matrix/sdk.ts`, `docs/channels/matrix.md`                                              |
+| Encrypted media previews | `file`, `thumbnail_file`                                                                           | out          | encrypted thumbnails for encrypted image events                          | `src/matrix/send/media.ts`, `docs/channels/matrix.md`                                                                      |
+| Device verification      | `m.key.verification.*`, `m.key.verification.request`                                               | in/tools     | request/ready/start/SAS/done/cancel notices and CLI flows                | `src/matrix/monitor/verification-utils.ts`, `src/matrix/monitor/events.test.ts`, `docs/channels/matrix.md`                 |
+| Streaming/live markers   | `org.matrix.msc4357.live`                                                                          | out          | live draft/edit markers for partial streaming                            | `src/matrix/send/types.ts`, `src/matrix/send.ts`, `src/matrix/draft-stream.ts`                                             |
+
+## Explicit MSCs In Use
+
+These MSCs are explicitly referenced in the plugin today:
+
+- `MSC3381`: polls
+- `MSC1767`: extensible-events fallback fields used for polls and voice metadata
+- `MSC3245`: voice message marker
+- `MSC4357`: live streaming marker
+
+Evidence:
+
+- `src/matrix/poll-types.ts`
+- `src/matrix/send/media.ts`
+- `src/matrix/send/types.ts`
+- `src/matrix/draft-stream.ts`
+
+## Non-goals
+
+This file does not claim:
+
+- full client-server API coverage
+- full room-state/event coverage inherited from `matrix-js-sdk`
+- outbound support for any surface not listed above
+
+If a new Matrix feature lands, add a row with:
+
+1. exact event/spec id
+2. support shape (`in`, `out`, `tools`)
+3. at least one code path proving it
+
+## Missing / Candidate Specs
+
+Recommended next additions, prioritized by user-visible value and closeness to current code:
+
+| Priority | Surface                       | Spec / event ids                              | Why add it                                                                                         | Current gap                                                                      |
+| -------- | ----------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------- |
+| high     | Sticker messages              | `m.sticker`                                   | stable spec; common client surface; we already classify sticker attachments on read paths          | no explicit inbound `m.sticker` event handling and no outbound sticker send path |
+| high     | Outbound location messages    | `m.location`, `geo_uri`                       | stable spec; docs already say Matrix supports location, but current implementation is inbound-only | no outbound location send/action API                                             |
+| medium   | Private + richer read markers | `m.read.private`, `m.fully_read`              | stable spec; better privacy and cleaner read-state behavior than public-only `m.read`              | current code only sends public `m.read` receipts                                 |
+| medium   | Thread-aware receipts         | `m.read` with `thread_id`                     | stable spec; better alignment with Matrix thread UX                                                | current receipt send path has no `thread_id` support                             |
+| medium   | Unread markers                | `m.marked_unread`                             | stable spec; useful for operator workflows and room triage tooling                                 | no room account-data support for unread markers                                  |
+| low      | Emote messages                | `m.emote`                                     | stable spec; easy parity win for bots/action tools                                                 | no explicit send/action support                                                  |
+| low      | Poll close parity             | `m.poll.end`, `org.matrix.msc3381.poll.end`   | completes the poll lifecycle on a surface we already parse                                         | plugin parses poll-end events but does not expose an outbound close flow         |
+| low      | Animated media metadata       | `info.is_animated` on `m.image` / `m.sticker` | newer stable metadata; helps clients decide whether to fetch/render animated originals             | media info builders do not populate animation metadata                           |
+
+### Why these are listed
+
+- `m.sticker` is a stable spec surface in the latest Matrix Client-Server API, and the plugin already has partial sticker awareness in message summarization.
+- `m.location` is a stable spec surface in the latest Matrix Client-Server API. The plugin currently parses inbound location events from `geo_uri`, but does not send them.
+- `m.read.private`, `m.fully_read`, and threaded receipts are stable read-marker/read-receipt surfaces in the latest Matrix Client-Server API. The plugin currently posts plain `m.read` receipts only.
+- `m.marked_unread` is a stable room account-data surface in the latest Matrix Client-Server API and would be useful if Matrix actions grow more operator/client-like room triage controls.
+- `m.emote` is a stable message type and a relatively small addition compared with the items above.
+- `m.poll.end` is already represented in local poll types, so exposing a close-poll send/tool flow is a contained follow-up.
+- `info.is_animated` is a smaller metadata-parity item, but easy to miss once sticker support exists.
+
+### Probably not worth prioritizing here
+
+- VoIP / `m.call.*`: valid Matrix spec area and a plausible future direction here, just not a near-term priority relative to messaging, receipt, and room-state gaps.
+
+### Gap Evidence
+
+- sticker partial only: `src/matrix/media-text.ts`
+- location inbound only: `src/matrix/monitor/location.ts`, `src/matrix/monitor/handler.ts`
+- public receipt only: `src/matrix/sdk.ts`, `src/matrix/send.ts`, `src/matrix/monitor/handler.ts`
+- poll-end constants only: `src/matrix/poll-types.ts`
+- no animation metadata emit: `src/matrix/send/media.ts`
+
+### External Spec References
+
+- latest Matrix Client-Server API: <https://spec.matrix.org/latest/client-server-api/index.html>
+- `m.sticker`: <https://spec.matrix.org/latest/client-server-api/#msticker>
+- `m.location`: <https://spec.matrix.org/latest/client-server-api/#mlocation>
+- receipts and read markers (`m.read.private`, `m.fully_read`, `m.marked_unread`): <https://spec.matrix.org/latest/client-server-api/#receipts>

package/api.ts

@@ -0,0 +1,38 @@
+export { matrixPlugin } from "./src/channel.js";
+export { createMatrixSetupWizardProxy, matrixSetupAdapter } from "./src/setup-core.js";
+export { matrixOnboardingAdapter } from "./src/setup-surface.js";
+export {
+  findMatrixAccountEntry,
+  requiresExplicitMatrixDefaultAccount,
+  resolveConfiguredMatrixAccountIds,
+  resolveMatrixChannelConfig,
+  resolveMatrixDefaultOrOnlyAccountId,
+} from "./src/account-selection.js";
+export {
+  getMatrixScopedEnvVarNames,
+  listMatrixEnvAccountIds,
+  resolveMatrixEnvAccountToken,
+} from "./src/env-vars.js";
+export {
+  hashMatrixAccessToken,
+  resolveMatrixAccountStorageRoot,
+  resolveMatrixCredentialsDir,
+  resolveMatrixCredentialsFilename,
+  resolveMatrixCredentialsPath,
+  resolveMatrixHomeserverKey,
+  resolveMatrixLegacyFlatStoragePaths,
+  resolveMatrixLegacyFlatStoreRoot,
+  sanitizeMatrixPathSegment,
+} from "./src/storage-paths.js";
+export {
+  createMatrixThreadBindingManager,
+  getMatrixThreadBindingManager,
+  resetMatrixThreadBindingsForTests,
+} from "./src/matrix/thread-bindings.js";
+export {
+  setMatrixThreadBindingIdleTimeoutBySessionKey,
+  setMatrixThreadBindingMaxAgeBySessionKey,
+} from "./src/matrix/thread-bindings-shared.js";
+export { matrixOnboardingAdapter as matrixSetupWizard } from "./src/onboarding.js";
+
+export const matrixSessionBindingAdapterChannels = ["matrix"] as const;

package/auth-presence.ts

@@ -0,0 +1,56 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import type { AutoBotConfig } from "autobot/plugin-sdk/config-contracts";
+import { resolveStateDir } from "autobot/plugin-sdk/state-paths";
+import {
+  resolveMatrixCredentialsDir,
+  resolveMatrixCredentialsFilename,
+} from "./src/storage-paths.js";
+
+type MatrixAuthPresenceParams =
+  | {
+      cfg: AutoBotConfig;
+      env?: NodeJS.ProcessEnv;
+    }
+  | AutoBotConfig;
+
+function listMatrixCredentialPaths(
+  _cfg: AutoBotConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): readonly string[] {
+  const credentialsDir = resolveMatrixCredentialsDir(resolveStateDir(env, os.homedir));
+  const paths = new Set<string>([
+    resolveMatrixCredentialsFilename(),
+    resolveMatrixCredentialsFilename("default"),
+  ]);
+
+  try {
+    const entries = fs.readdirSync(credentialsDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.isFile() && /^credentials(?:-[a-z0-9._-]+)?\.json$/i.test(entry.name)) {
+        paths.add(entry.name);
+      }
+    }
+  } catch {
+    // Missing credentials directories mean no persisted Matrix auth state.
+  }
+
+  return [...paths].map((filename) => path.join(credentialsDir, filename));
+}
+
+export function hasAnyMatrixAuth(
+  params: MatrixAuthPresenceParams,
+  env: NodeJS.ProcessEnv = process.env,
+): boolean {
+  const cfg = params && typeof params === "object" && "cfg" in params ? params.cfg : params;
+  const resolvedEnv =
+    params && typeof params === "object" && "cfg" in params ? (params.env ?? env) : env;
+  return listMatrixCredentialPaths(cfg, resolvedEnv).some((filePath) => {
+    try {
+      return fs.existsSync(filePath);
+    } catch {
+      return false;
+    }
+  });
+}

package/autobot.plugin.json

@@ -0,0 +1,28 @@
+{
+  "id": "matrix",
+  "commandAliases": [{ "name": "matrix" }],
+  "activation": {
+    "onStartup": false,
+    "onCommands": ["matrix"]
+  },
+  "channels": ["matrix"],
+  "channelEnvVars": {
+    "matrix": [
+      "MATRIX_HOMESERVER",
+      "MATRIX_USER_ID",
+      "MATRIX_ACCESS_TOKEN",
+      "MATRIX_PASSWORD",
+      "MATRIX_DEVICE_ID",
+      "MATRIX_DEVICE_NAME",
+      "MATRIX_OPS_HOMESERVER",
+      "MATRIX_OPS_ACCESS_TOKEN",
+      "MATRIX_OPS_DEVICE_ID",
+      "MATRIX_OPS_DEVICE_NAME"
+    ]
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}

package/channel-plugin-api.ts

@@ -0,0 +1,3 @@
+// Keep bundled channel entry imports narrow so bootstrap/discovery paths do
+// not pull the broad Matrix API barrel into lightweight plugin loads.
+export { matrixPlugin } from "./src/channel.js";

package/cli-metadata.ts

@@ -0,0 +1,11 @@
+import { definePluginEntry } from "autobot/plugin-sdk/plugin-entry";
+import { registerMatrixCliMetadata } from "./src/cli-metadata.js";
+
+export { registerMatrixCliMetadata } from "./src/cli-metadata.js";
+
+export default definePluginEntry({
+  id: "matrix",
+  name: "Matrix",
+  description: "Matrix channel plugin (matrix-js-sdk)",
+  register: registerMatrixCliMetadata,
+});

package/contract-api.ts

@@ -0,0 +1,17 @@
+export {
+  createMatrixThreadBindingManager,
+  resetMatrixThreadBindingsForTests,
+} from "./src/matrix/thread-bindings.js";
+export { setMatrixRuntime } from "./src/runtime.js";
+export { normalizeCompatibilityConfig, legacyConfigRules } from "./src/doctor-contract.js";
+export {
+  namedAccountPromotionKeys,
+  resolveSingleAccountPromotionTarget,
+  singleAccountKeysToMove,
+} from "./src/setup-contract.js";
+export {
+  collectRuntimeConfigAssignments,
+  secretTargetRegistryEntries,
+} from "./src/secret-contract.js";
+export { matrixSetupAdapter } from "./src/setup-core.js";
+export { matrixSetupWizard } from "./src/setup-surface.js";

package/doctor-contract-api.ts

@@ -0,0 +1 @@
+export { normalizeCompatibilityConfig, legacyConfigRules } from "./src/doctor-contract.js";

package/helper-api.ts

@@ -0,0 +1,3 @@
+export * from "./src/account-selection.js";
+export * from "./src/env-vars.js";
+export * from "./src/storage-paths.js";

package/index.ts

@@ -0,0 +1,55 @@
+import {
+  defineBundledChannelEntry,
+  type AutoBotPluginApi,
+} from "autobot/plugin-sdk/channel-entry-contract";
+import { registerMatrixCliMetadata } from "./cli-metadata.js";
+import { registerMatrixSubagentHooks } from "./subagent-hooks-api.js";
+
+type MatrixHandlersRuntimeModule = typeof import("./plugin-entry.handlers.runtime.js");
+
+let matrixHandlersRuntimePromise: Promise<MatrixHandlersRuntimeModule> | null = null;
+
+function loadMatrixHandlersRuntimeModule() {
+  matrixHandlersRuntimePromise ??= import("./plugin-entry.handlers.runtime.js");
+  return matrixHandlersRuntimePromise;
+}
+
+export function registerMatrixFullRuntime(api: AutoBotPluginApi): void {
+  api.registerGatewayMethod("matrix.verify.recoveryKey", async (ctx) => {
+    const { handleVerifyRecoveryKey } = await loadMatrixHandlersRuntimeModule();
+    await handleVerifyRecoveryKey(ctx);
+  });
+
+  api.registerGatewayMethod("matrix.verify.bootstrap", async (ctx) => {
+    const { handleVerificationBootstrap } = await loadMatrixHandlersRuntimeModule();
+    await handleVerificationBootstrap(ctx);
+  });
+
+  api.registerGatewayMethod("matrix.verify.status", async (ctx) => {
+    const { handleVerificationStatus } = await loadMatrixHandlersRuntimeModule();
+    await handleVerificationStatus(ctx);
+  });
+
+  registerMatrixSubagentHooks(api);
+}
+
+export default defineBundledChannelEntry({
+  id: "matrix",
+  name: "Matrix",
+  description: "Matrix channel plugin (matrix-js-sdk)",
+  importMetaUrl: import.meta.url,
+  plugin: {
+    specifier: "./channel-plugin-api.js",
+    exportName: "matrixPlugin",
+  },
+  secrets: {
+    specifier: "./secret-contract-api.js",
+    exportName: "channelSecrets",
+  },
+  runtime: {
+    specifier: "./runtime-setter-api.js",
+    exportName: "setMatrixRuntime",
+  },
+  registerCliMetadata: registerMatrixCliMetadata,
+  registerFull: registerMatrixFullRuntime,
+});