fix: preserve command argument casing (#1308) (thanks @dougvk)

Co-authored-by: Richard Poelderl <18185649+p6l-richard@users.noreply.github.com>

.gitignore

@@ -66,3 +66,6 @@ apps/ios/*.mobileprovision
 IDENTITY.md
 USER.md
 .tgz
+
+# local tooling
+.serena/

.serena/.gitignore

@@ -1 +0,0 @@
-/cache

.serena/project.yml

@@ -1,87 +0,0 @@
-# list of languages for which language servers are started; choose from:
-#   al               bash             clojure          cpp              csharp           csharp_omnisharp
-#   dart             elixir           elm              erlang           fortran          fsharp
-#   go               groovy           haskell          java             julia            kotlin
-#   lua              markdown         nix              pascal           perl             php
-#   powershell       python           python_jedi      r                rego             ruby
-#   ruby_solargraph  rust             scala            swift            terraform        toml
-#   typescript       typescript_vts   yaml             zig
-# Note:
-#   - For C, use cpp
-#   - For JavaScript, use typescript
-#   - For Free Pascal / Lazarus, use pascal
-# Special requirements:
-#   - csharp: Requires the presence of a .sln file in the project folder.
-#   - pascal: Requires Free Pascal Compiler (fpc) and optionally Lazarus.
-# When using multiple languages, the first language server that supports a given file will be used for that file.
-# The first language is the default language and the respective language server will be used as a fallback.
-# Note that when using the JetBrains backend, language servers are not used and this list is correspondingly ignored.
-languages:
-- typescript
-
-# the encoding used by text files in the project
-# For a list of possible encodings, see https://docs.python.org/3.11/library/codecs.html#standard-encodings
-encoding: "utf-8"
-
-# whether to use the project's gitignore file to ignore files
-# Added on 2025-04-07
-ignore_all_files_in_gitignore: true
-
-# list of additional paths to ignore
-# same syntax as gitignore, so you can use * and **
-# Was previously called `ignored_dirs`, please update your config if you are using that.
-# Added (renamed) on 2025-04-07
-ignored_paths: []
-
-# whether the project is in read-only mode
-# If set to true, all editing tools will be disabled and attempts to use them will result in an error
-# Added on 2025-04-18
-read_only: false
-
-# list of tool names to exclude. We recommend not excluding any tools, see the readme for more details.
-# Below is the complete list of tools for convenience.
-# To make sure you have the latest list of tools, and to view their descriptions, 
-# execute `uv run scripts/print_tool_overview.py`.
-#
-#  * `activate_project`: Activates a project by name.
-#  * `check_onboarding_performed`: Checks whether project onboarding was already performed.
-#  * `create_text_file`: Creates/overwrites a file in the project directory.
-#  * `delete_lines`: Deletes a range of lines within a file.
-#  * `delete_memory`: Deletes a memory from Serena's project-specific memory store.
-#  * `execute_shell_command`: Executes a shell command.
-#  * `find_referencing_code_snippets`: Finds code snippets in which the symbol at the given location is referenced.
-#  * `find_referencing_symbols`: Finds symbols that reference the symbol at the given location (optionally filtered by type).
-#  * `find_symbol`: Performs a global (or local) search for symbols with/containing a given name/substring (optionally filtered by type).
-#  * `get_current_config`: Prints the current configuration of the agent, including the active and available projects, tools, contexts, and modes.
-#  * `get_symbols_overview`: Gets an overview of the top-level symbols defined in a given file.
-#  * `initial_instructions`: Gets the initial instructions for the current project.
-#     Should only be used in settings where the system prompt cannot be set,
-#     e.g. in clients you have no control over, like Claude Desktop.
-#  * `insert_after_symbol`: Inserts content after the end of the definition of a given symbol.
-#  * `insert_at_line`: Inserts content at a given line in a file.
-#  * `insert_before_symbol`: Inserts content before the beginning of the definition of a given symbol.
-#  * `list_dir`: Lists files and directories in the given directory (optionally with recursion).
-#  * `list_memories`: Lists memories in Serena's project-specific memory store.
-#  * `onboarding`: Performs onboarding (identifying the project structure and essential tasks, e.g. for testing or building).
-#  * `prepare_for_new_conversation`: Provides instructions for preparing for a new conversation (in order to continue with the necessary context).
-#  * `read_file`: Reads a file within the project directory.
-#  * `read_memory`: Reads the memory with the given name from Serena's project-specific memory store.
-#  * `remove_project`: Removes a project from the Serena configuration.
-#  * `replace_lines`: Replaces a range of lines within a file with new content.
-#  * `replace_symbol_body`: Replaces the full definition of a symbol.
-#  * `restart_language_server`: Restarts the language server, may be necessary when edits not through Serena happen.
-#  * `search_for_pattern`: Performs a search for a pattern in the project.
-#  * `summarize_changes`: Provides instructions for summarizing the changes made to the codebase.
-#  * `switch_modes`: Activates modes by providing a list of their names
-#  * `think_about_collected_information`: Thinking tool for pondering the completeness of collected information.
-#  * `think_about_task_adherence`: Thinking tool for determining whether the agent is still on track with the current task.
-#  * `think_about_whether_you_are_done`: Thinking tool for determining whether the task is truly completed.
-#  * `write_memory`: Writes a named memory (for future reference) to Serena's project-specific memory store.
-excluded_tools: []
-
-# initial prompt for the project. It will always be given to the LLM upon activating the project
-# (contrary to the memories, which are loaded on demand).
-initial_prompt: ""
-
-project_name: "clawdbot"
-included_optional_tools: []

AGENTS.md

@@ -41,6 +41,11 @@
 - Aim to keep files under ~700 LOC; guideline only (not a hard guardrail). Split/refactor when it improves clarity or testability.
 - Naming: use **Clawdbot** for product/app/docs headings; use `clawdbot` for CLI command, package/binary, paths, and config keys.
 
+## Release Channels (Naming)
+- stable: tagged releases only (e.g. `vYYYY.M.D`), npm dist-tag `latest`.
+- beta: prerelease tags `vYYYY.M.D-beta.N`, npm dist-tag `beta` (may ship without macOS app).
+- dev: moving head on `main` (no tag; git checkout main).
+
 ## Testing Guidelines
 - Framework: Vitest with V8 coverage thresholds (70% lines/branches/functions/statements).
 - Naming: match source names with `*.test.ts`; e2e in `*.e2e.test.ts`.

CHANGELOG.md

@@ -5,18 +5,23 @@ Docs: https://docs.clawd.bot
 ## 2026.1.20-1
 
 ### Changes
+- Deps: update workspace + memory-lancedb dependencies.
 - Repo: remove the Peekaboo git submodule now that the SPM release is used.
 - Plugins: require manifest-embedded config schemas, validate configs without loading plugin code, and surface plugin config warnings. (#1272) — thanks @thewilloftheshadow.
 - Plugins: move channel catalog metadata into plugin manifests; align Nextcloud Talk policy helpers with core patterns. (#1290) — thanks @NicholaiVogel.
+- Discord: fall back to /skill when native command limits are exceeded; expose /skill globally. (#1287) — thanks @thewilloftheshadow.
 - Docs: refresh bird skill install metadata and usage notes. (#1302) — thanks @odysseus0.
 - Matrix: migrate to matrix-bot-sdk with E2EE support, location handling, and group allowlist upgrades. (#1298) — thanks @sibbl.
 - Plugins/UI: let channel plugin metadata drive UI labels/icons and cron channel options. (#1306) — thanks @steipete.
+- Zalouser: add channel dock metadata, config schema, setup wiring, probe, and status issues. (#1219) — thanks @suminhthanh.
 ### Fixes
 - Web search: infer Perplexity base URL from API key source (direct vs OpenRouter).
-- Config: allow Perplexity as a web_search provider in config validation. (#1230, #1247) — thanks @sebslight.
+- Session: preserve command argument casing while matching reset triggers. (#1308) — thanks @dougvk.
 - TUI: keep thinking blocks ordered before content during streaming and isolate per-run assembly. (#1202) — thanks @aaronveklabs.
+- TUI: align custom editor initialization with the latest pi-tui API. (#1298) — thanks @sibbl.
 - CLI: avoid duplicating --profile/--dev flags when formatting commands.
 - Exec: prefer bash when fish is default shell, falling back to sh if bash is missing. (#1297) — thanks @ysqander.
+- Exec: merge login-shell PATH for host=gateway exec while keeping daemon PATH minimal. (#1304)
 - Plugins: add Nextcloud Talk manifest for plugin config validation. (#1297) — thanks @ysqander.
 
 ## 2026.1.19-3
@@ -30,6 +35,8 @@ Docs: https://docs.clawd.bot
 ### Fixes
 - Gateway: strip inbound envelope headers from chat history messages to keep clients clean.
 - UI: prevent double-scroll in Control UI chat by locking chat layout to the viewport. (#1283) — thanks @bradleypriest.
+- Config: allow Perplexity as a web_search provider in config validation. (#1230)
+- Browser: register AI snapshot refs for act commands. (#1282) — thanks @John-Rood.
 
 ## 2026.1.19-2
 

README.md

@@ -71,6 +71,15 @@ clawdbot agent --message "Ship checklist" --thinking high
 
 Upgrading? [Updating guide](https://docs.clawd.bot/install/updating) (and run `clawdbot doctor`).
 
+## Development channels
+
+- **stable**: tagged releases (`vYYYY.M.D` or `vYYYY.M.D-<patch>`), npm dist-tag `latest`.
+- **beta**: prerelease tags (`vYYYY.M.D-beta.N`), npm dist-tag `beta` (macOS app may be missing).
+- **dev**: moving head of `main`, npm dist-tag `dev` (when published).
+
+Switch channels (git + npm): `clawdbot update --channel stable|beta|dev`.
+Details: [Development channels](https://docs.clawd.bot/install/development-channels).
+
 ## From source (development)
 
 Prefer `pnpm` for builds from source. Bun is optional for running TypeScript directly.
@@ -492,5 +501,5 @@ Thanks to all clawtributors:
   <a href="https://github.com/prathamdby"><img src="https://avatars.githubusercontent.com/u/134331217?v=4&s=48" width="48" height="48" alt="prathamdby" title="prathamdby"/></a> <a href="https://github.com/reeltimeapps"><img src="https://avatars.githubusercontent.com/u/637338?v=4&s=48" width="48" height="48" alt="reeltimeapps" title="reeltimeapps"/></a> <a href="https://github.com/RLTCmpe"><img src="https://avatars.githubusercontent.com/u/10762242?v=4&s=48" width="48" height="48" alt="RLTCmpe" title="RLTCmpe"/></a> <a href="https://github.com/rodrigouroz"><img src="https://avatars.githubusercontent.com/u/384037?v=4&s=48" width="48" height="48" alt="rodrigouroz" title="rodrigouroz"/></a> <a href="https://github.com/search?q=Rolf%20Fredheim"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rolf Fredheim" title="Rolf Fredheim"/></a> <a href="https://github.com/search?q=Rony%20Kelner"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Rony Kelner" title="Rony Kelner"/></a> <a href="https://github.com/search?q=Samrat%20Jha"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Samrat Jha" title="Samrat Jha"/></a> <a href="https://github.com/siraht"><img src="https://avatars.githubusercontent.com/u/73152895?v=4&s=48" width="48" height="48" alt="siraht" title="siraht"/></a> <a href="https://github.com/snopoke"><img src="https://avatars.githubusercontent.com/u/249606?v=4&s=48" width="48" height="48" alt="snopoke" title="snopoke"/></a> <a href="https://github.com/suminhthanh"><img src="https://avatars.githubusercontent.com/u/2907636?v=4&s=48" width="48" height="48" alt="suminhthanh" title="suminhthanh"/></a>
   <a href="https://github.com/search?q=The%20Admiral"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="The Admiral" title="The Admiral"/></a> <a href="https://github.com/thesash"><img src="https://avatars.githubusercontent.com/u/1166151?v=4&s=48" width="48" height="48" alt="thesash" title="thesash"/></a> <a href="https://github.com/search?q=Ubuntu"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Ubuntu" title="Ubuntu"/></a> <a href="https://github.com/voidserf"><img src="https://avatars.githubusercontent.com/u/477673?v=4&s=48" width="48" height="48" alt="voidserf" title="voidserf"/></a> <a href="https://github.com/wstock"><img src="https://avatars.githubusercontent.com/u/1394687?v=4&s=48" width="48" height="48" alt="wstock" title="wstock"/></a> <a href="https://github.com/search?q=Zach%20Knickerbocker"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Zach Knickerbocker" title="Zach Knickerbocker"/></a> <a href="https://github.com/Alphonse-arianee"><img src="https://avatars.githubusercontent.com/u/254457365?v=4&s=48" width="48" height="48" alt="Alphonse-arianee" title="Alphonse-arianee"/></a> <a href="https://github.com/search?q=Azade"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Azade" title="Azade"/></a> <a href="https://github.com/carlulsoe"><img src="https://avatars.githubusercontent.com/u/34673973?v=4&s=48" width="48" height="48" alt="carlulsoe" title="carlulsoe"/></a> <a href="https://github.com/search?q=ddyo"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="ddyo" title="ddyo"/></a>
   <a href="https://github.com/search?q=Erik"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Erik" title="Erik"/></a> <a href="https://github.com/latitudeki5223"><img src="https://avatars.githubusercontent.com/u/119656367?v=4&s=48" width="48" height="48" alt="latitudeki5223" title="latitudeki5223"/></a> <a href="https://github.com/search?q=Manuel%20Maly"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Manuel Maly" title="Manuel Maly"/></a> <a href="https://github.com/search?q=Mourad%20Boustani"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Mourad Boustani" title="Mourad Boustani"/></a> <a href="https://github.com/odrobnik"><img src="https://avatars.githubusercontent.com/u/333270?v=4&s=48" width="48" height="48" alt="odrobnik" title="odrobnik"/></a> <a href="https://github.com/pcty-nextgen-ios-builder"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="pcty-nextgen-ios-builder" title="pcty-nextgen-ios-builder"/></a> <a href="https://github.com/search?q=Quentin"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Quentin" title="Quentin"/></a> <a href="https://github.com/search?q=Randy%20Torres"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="Randy Torres" title="Randy Torres"/></a> <a href="https://github.com/rhjoh"><img src="https://avatars.githubusercontent.com/u/105699450?v=4&s=48" width="48" height="48" alt="rhjoh" title="rhjoh"/></a> <a href="https://github.com/ronak-guliani"><img src="https://avatars.githubusercontent.com/u/23518228?v=4&s=48" width="48" height="48" alt="ronak-guliani" title="ronak-guliani"/></a>
-  <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a>
+  <a href="https://github.com/search?q=William%20Stock"><img src="assets/avatar-placeholder.svg" width="48" height="48" alt="William Stock" title="William Stock"/></a> <a href="https://github.com/p6l-richard"><img src="https://avatars.githubusercontent.com/u/18185649?v=4&s=48" width="48" height="48" alt="p6l-richard" title="p6l-richard"/></a>
 </p>

Swabble/Package.resolved

@@ -1,15 +1,33 @@
 {
-  "originHash" : "5d29ee82825e0764775562242cfa1ff4dc79584797dd638f76c9876545454748",
+  "originHash" : "2e6f580ad7d1e839d513aa883350369bf2e4193fad872030fdaea7827f34d8ef",
   "pins" : [
+    {
+      "identity" : "commander",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/steipete/Commander.git",
+      "state" : {
+        "revision" : "9e349575c8e3c6745e81fe19e5bb5efa01b078ce",
+        "version" : "0.2.1"
+      }
+    },
     {
       "identity" : "elevenlabskit",
       "kind" : "remoteSourceControl",
       "location" : "https://github.com/steipete/ElevenLabsKit",
       "state" : {
-        "revision" : "7e3c948d8340abe3977014f3de020edf221e9269",
+        "revision" : "c8679fbd37416a8780fe43be88a497ff16209e2d",
         "version" : "0.1.0"
       }
     },
+    {
+      "identity" : "swift-concurrency-extras",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/pointfreeco/swift-concurrency-extras",
+      "state" : {
+        "revision" : "5a3825302b1a0d744183200915a47b508c828e6f",
+        "version" : "1.3.2"
+      }
+    },
     {
       "identity" : "swift-syntax",
       "kind" : "remoteSourceControl",
@@ -27,6 +45,24 @@
         "revision" : "399f76dcd91e4c688ca2301fa24a8cc6d9927211",
         "version" : "0.99.0"
       }
+    },
+    {
+      "identity" : "swiftui-math",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/gonzalezreal/swiftui-math",
+      "state" : {
+        "revision" : "0b5c2cfaaec8d6193db206f675048eeb5ce95f71",
+        "version" : "0.1.0"
+      }
+    },
+    {
+      "identity" : "textual",
+      "kind" : "remoteSourceControl",
+      "location" : "https://github.com/gonzalezreal/textual",
+      "state" : {
+        "revision" : "a03c1e103d88de4ea0dd8320ea1611ec0d4b29b3",
+        "version" : "0.2.0"
+      }
     }
   ],
   "version" : 3

apps/android/app/src/main/java/com/clawdbot/android/NodeRuntime.kt

@@ -12,6 +12,7 @@ import com.clawdbot.android.chat.ChatMessage
 import com.clawdbot.android.chat.ChatPendingToolCall
 import com.clawdbot.android.chat.ChatSessionEntry
 import com.clawdbot.android.chat.OutgoingAttachment
+import com.clawdbot.android.gateway.DeviceAuthStore
 import com.clawdbot.android.gateway.DeviceIdentityStore
 import com.clawdbot.android.gateway.GatewayClientInfo
 import com.clawdbot.android.gateway.GatewayConnectOptions
@@ -62,6 +63,7 @@ class NodeRuntime(context: Context) {
   private val scope = CoroutineScope(SupervisorJob() + Dispatchers.IO)
 
   val prefs = SecurePrefs(appContext)
+  private val deviceAuthStore = DeviceAuthStore(prefs)
   val canvas = CanvasController()
   val camera = CameraCaptureManager(appContext)
   val location = LocationCaptureManager(appContext)
@@ -153,6 +155,7 @@ class NodeRuntime(context: Context) {
     GatewaySession(
       scope = scope,
       identityStore = identityStore,
+      deviceAuthStore = deviceAuthStore,
       onConnected = { name, remote, mainSessionKey ->
         operatorConnected = true
         operatorStatusText = "Connected"
@@ -188,6 +191,7 @@ class NodeRuntime(context: Context) {
     GatewaySession(
       scope = scope,
       identityStore = identityStore,
+      deviceAuthStore = deviceAuthStore,
       onConnected = { _, _, _ ->
         nodeConnected = true
         nodeStatusText = "Connected"

apps/android/app/src/main/java/com/clawdbot/android/SecurePrefs.kt

@@ -189,6 +189,18 @@ class SecurePrefs(context: Context) {
     prefs.edit { putString(key, fingerprint.trim()) }
   }
 
+  fun getString(key: String): String? {
+    return prefs.getString(key, null)
+  }
+
+  fun putString(key: String, value: String) {
+    prefs.edit { putString(key, value) }
+  }
+
+  fun remove(key: String) {
+    prefs.edit { remove(key) }
+  }
+
   private fun loadOrCreateInstanceId(): String {
     val existing = prefs.getString("node.instanceId", null)?.trim()
     if (!existing.isNullOrBlank()) return existing

apps/android/app/src/main/java/com/clawdbot/android/gateway/DeviceAuthStore.kt

@@ -0,0 +1,26 @@
+package com.clawdbot.android.gateway
+
+import com.clawdbot.android.SecurePrefs
+
+class DeviceAuthStore(private val prefs: SecurePrefs) {
+  fun loadToken(deviceId: String, role: String): String? {
+    val key = tokenKey(deviceId, role)
+    return prefs.getString(key)?.trim()?.takeIf { it.isNotEmpty() }
+  }
+
+  fun saveToken(deviceId: String, role: String, token: String) {
+    val key = tokenKey(deviceId, role)
+    prefs.putString(key, token.trim())
+  }
+
+  fun clearToken(deviceId: String, role: String) {
+    val key = tokenKey(deviceId, role)
+    prefs.remove(key)
+  }
+
+  private fun tokenKey(deviceId: String, role: String): String {
+    val normalizedDevice = deviceId.trim().lowercase()
+    val normalizedRole = role.trim().lowercase()
+    return "gateway.deviceToken.$normalizedDevice.$normalizedRole"
+  }
+}

apps/android/app/src/main/java/com/clawdbot/android/gateway/GatewaySession.kt

@@ -55,6 +55,7 @@ data class GatewayConnectOptions(
 class GatewaySession(
   private val scope: CoroutineScope,
   private val identityStore: DeviceIdentityStore,
+  private val deviceAuthStore: DeviceAuthStore,
   private val onConnected: (serverName: String?, remoteAddress: String?, mainSessionKey: String?) -> Unit,
   private val onDisconnected: (message: String) -> Unit,
   private val onEvent: (event: String, payloadJson: String?) -> Unit,
@@ -177,6 +178,7 @@ class GatewaySession(
     private val connectDeferred = CompletableDeferred<Unit>()
     private val closedDeferred = CompletableDeferred<Unit>()
     private val isClosed = AtomicBoolean(false)
+    private val connectNonceDeferred = CompletableDeferred<String?>()
     private val client: OkHttpClient = buildClient()
     private var socket: WebSocket? = null
     private val loggerTag = "ClawdbotGateway"
@@ -253,7 +255,8 @@ class GatewaySession(
       override fun onOpen(webSocket: WebSocket, response: Response) {
         scope.launch {
           try {
-            sendConnect()
+            val nonce = awaitConnectNonce()
+            sendConnect(nonce)
           } catch (err: Throwable) {
             connectDeferred.completeExceptionally(err)
             closeQuietly()
@@ -288,16 +291,30 @@ class GatewaySession(
       }
     }
 
-    private suspend fun sendConnect() {
-      val payload = buildConnectParams()
+    private suspend fun sendConnect(connectNonce: String?) {
+      val identity = identityStore.loadOrCreate()
+      val storedToken = deviceAuthStore.loadToken(identity.deviceId, options.role)
+      val trimmedToken = token?.trim().orEmpty()
+      val authToken = if (storedToken.isNullOrBlank()) trimmedToken else storedToken
+      val canFallbackToShared = !storedToken.isNullOrBlank() && trimmedToken.isNotBlank()
+      val payload = buildConnectParams(identity, connectNonce, authToken, password?.trim())
       val res = request("connect", payload, timeoutMs = 8_000)
       if (!res.ok) {
         val msg = res.error?.message ?: "connect failed"
+        if (canFallbackToShared) {
+          deviceAuthStore.clearToken(identity.deviceId, options.role)
+        }
         throw IllegalStateException(msg)
       }
       val payloadJson = res.payloadJson ?: throw IllegalStateException("connect failed: missing payload")
       val obj = json.parseToJsonElement(payloadJson).asObjectOrNull() ?: throw IllegalStateException("connect failed")
       val serverName = obj["server"].asObjectOrNull()?.get("host").asStringOrNull()
+      val authObj = obj["auth"].asObjectOrNull()
+      val deviceToken = authObj?.get("deviceToken").asStringOrNull()
+      val authRole = authObj?.get("role").asStringOrNull() ?: options.role
+      if (!deviceToken.isNullOrBlank()) {
+        deviceAuthStore.saveToken(identity.deviceId, authRole, deviceToken)
+      }
       val rawCanvas = obj["canvasHostUrl"].asStringOrNull()
       canvasHostUrl = normalizeCanvasHostUrl(rawCanvas, endpoint)
       val sessionDefaults =
@@ -308,7 +325,12 @@ class GatewaySession(
       connectDeferred.complete(Unit)
     }
 
-    private fun buildConnectParams(): JsonObject {
+    private fun buildConnectParams(
+      identity: DeviceIdentity,
+      connectNonce: String?,
+      authToken: String,
+      authPassword: String?,
+    ): JsonObject {
       val client = options.client
       val locale = Locale.getDefault().toLanguageTag()
       val clientObj =
@@ -323,22 +345,20 @@ class GatewaySession(
           client.modelIdentifier?.let { put("modelIdentifier", JsonPrimitive(it)) }
         }
 
-      val authToken = token?.trim().orEmpty()
-      val authPassword = password?.trim().orEmpty()
+      val password = authPassword?.trim().orEmpty()
       val authJson =
         when {
           authToken.isNotEmpty() ->
             buildJsonObject {
               put("token", JsonPrimitive(authToken))
             }
-          authPassword.isNotEmpty() ->
+          password.isNotEmpty() ->
             buildJsonObject {
-              put("password", JsonPrimitive(authPassword))
+              put("password", JsonPrimitive(password))
             }
           else -> null
         }
 
-      val identity = identityStore.loadOrCreate()
       val signedAtMs = System.currentTimeMillis()
       val payload =
         buildDeviceAuthPayload(
@@ -349,6 +369,7 @@ class GatewaySession(
           scopes = options.scopes,
           signedAtMs = signedAtMs,
           token = if (authToken.isNotEmpty()) authToken else null,
+          nonce = connectNonce,
         )
       val signature = identityStore.signPayload(payload, identity)
       val publicKey = identityStore.publicKeyBase64Url(identity)
@@ -359,6 +380,9 @@ class GatewaySession(
             put("publicKey", JsonPrimitive(publicKey))
             put("signature", JsonPrimitive(signature))
             put("signedAt", JsonPrimitive(signedAtMs))
+            if (!connectNonce.isNullOrBlank()) {
+              put("nonce", JsonPrimitive(connectNonce))
+            }
           }
         } else {
           null
@@ -416,6 +440,13 @@ class GatewaySession(
       val event = frame["event"].asStringOrNull() ?: return
       val payloadJson =
         frame["payload"]?.let { it.toString() } ?: frame["payloadJSON"].asStringOrNull()
+      if (event == "connect.challenge") {
+        val nonce = extractConnectNonce(payloadJson)
+        if (!connectNonceDeferred.isCompleted) {
+          connectNonceDeferred.complete(nonce)
+        }
+        return
+      }
       if (event == "node.invoke.request" && payloadJson != null && onInvoke != null) {
         handleInvokeEvent(payloadJson)
         return
@@ -423,6 +454,21 @@ class GatewaySession(
       onEvent(event, payloadJson)
     }
 
+    private suspend fun awaitConnectNonce(): String? {
+      if (isLoopbackHost(endpoint.host)) return null
+      return try {
+        withTimeout(2_000) { connectNonceDeferred.await() }
+      } catch (_: Throwable) {
+        null
+      }
+    }
+
+    private fun extractConnectNonce(payloadJson: String?): String? {
+      if (payloadJson.isNullOrBlank()) return null
+      val obj = parseJsonOrNull(payloadJson)?.asObjectOrNull() ?: return null
+      return obj["nonce"].asStringOrNull()
+    }
+
     private fun handleInvokeEvent(payloadJson: String) {
       val payload =
         try {
@@ -544,19 +590,26 @@ class GatewaySession(
     scopes: List<String>,
     signedAtMs: Long,
     token: String?,
+    nonce: String?,
   ): String {
     val scopeString = scopes.joinToString(",")
     val authToken = token.orEmpty()
-    return listOf(
-      "v1",
-      deviceId,
-      clientId,
-      clientMode,
-      role,
-      scopeString,
-      signedAtMs.toString(),
-      authToken,
-    ).joinToString("|")
+    val version = if (nonce.isNullOrBlank()) "v1" else "v2"
+    val parts =
+      mutableListOf(
+        version,
+        deviceId,
+        clientId,
+        clientMode,
+        role,
+        scopeString,
+        signedAtMs.toString(),
+        authToken,
+      )
+    if (!nonce.isNullOrBlank()) {
+      parts.add(nonce)
+    }
+    return parts.joinToString("|")
   }
 
   private fun normalizeCanvasHostUrl(raw: String?, endpoint: GatewayEndpoint): String? {

apps/android/app/src/main/java/com/clawdbot/android/gateway/GatewayTls.kt

@@ -84,5 +84,7 @@ private fun sha256Hex(data: ByteArray): String {
 }
 
 private fun normalizeFingerprint(raw: String): String {
-  return raw.lowercase().filter { it in '0'..'9' || it in 'a'..'f' }
+  val stripped = raw.trim()
+    .replace(Regex("^sha-?256\\s*:?\\s*", RegexOption.IGNORE_CASE), "")
+  return stripped.lowercase().filter { it in '0'..'9' || it in 'a'..'f' }
 }

apps/ios/Sources/Info.plist

@@ -19,9 +19,9 @@
 	<key>CFBundlePackageType</key>
 	<string>APPL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.1.11-4</string>
+	<string>2026.1.9</string>
 	<key>CFBundleVersion</key>
-	<string>202601113</string>
+	<string>20260109</string>
 	<key>NSAppTransportSecurity</key>
 	<dict>
 		<key>NSAllowsArbitraryLoadsInWebContent</key>

apps/ios/SwiftSources.input.xcfilelist

@@ -1,15 +1,13 @@
-Sources/Bridge/BridgeClient.swift
-Sources/Bridge/BridgeConnectionController.swift
-Sources/Bridge/BridgeDiscoveryDebugLogView.swift
-Sources/Bridge/BridgeDiscoveryModel.swift
-Sources/Bridge/BridgeEndpointID.swift
-Sources/Bridge/BridgeSession.swift
-Sources/Bridge/BridgeSettingsStore.swift
-Sources/Bridge/KeychainStore.swift
+Sources/Gateway/GatewayConnectionController.swift
+Sources/Gateway/GatewayDiscoveryDebugLogView.swift
+Sources/Gateway/GatewayDiscoveryModel.swift
+Sources/Gateway/GatewaySettingsStore.swift
+Sources/Gateway/KeychainStore.swift
 Sources/Camera/CameraController.swift
 Sources/Chat/ChatSheet.swift
-Sources/Chat/IOSBridgeChatTransport.swift
+Sources/Chat/IOSGatewayChatTransport.swift
 Sources/ClawdbotApp.swift
+Sources/Location/LocationService.swift
 Sources/Model/NodeAppModel.swift
 Sources/RootCanvas.swift
 Sources/RootTabs.swift
@@ -17,6 +15,7 @@ Sources/Screen/ScreenController.swift
 Sources/Screen/ScreenRecordService.swift
 Sources/Screen/ScreenTab.swift
 Sources/Screen/ScreenWebView.swift
+Sources/SessionKey.swift
 Sources/Settings/SettingsNetworkingHelpers.swift
 Sources/Settings/SettingsTab.swift
 Sources/Settings/VoiceWakeWordsSettingsView.swift

apps/ios/Tests/Info.plist

@@ -17,8 +17,8 @@
 	<key>CFBundlePackageType</key>
 	<string>BNDL</string>
 	<key>CFBundleShortVersionString</key>
-	<string>2026.1.11-4</string>
+	<string>2026.1.9</string>
 	<key>CFBundleVersion</key>
-	<string>202601113</string>
+	<string>20260109</string>
 </dict>
 </plist>

apps/macos/Sources/Clawdbot/ChannelsSettings+ChannelState.swift

@@ -426,24 +426,17 @@ extension ChannelsSettings {
     }
 
     private func resolveChannelTitle(_ id: String) -> String {
-        if let label = self.store.snapshot?.channelLabels[id], !label.isEmpty {
-            return label
-        }
+        let label = self.store.resolveChannelLabel(id)
+        if label != id { return label }
         return id.prefix(1).uppercased() + id.dropFirst()
     }
 
     private func resolveChannelDetailTitle(_ id: String) -> String {
-        if let detail = self.store.snapshot?.channelDetailLabels?[id], !detail.isEmpty {
-            return detail
-        }
-        return self.resolveChannelTitle(id)
+        return self.store.resolveChannelDetailLabel(id)
     }
 
     private func resolveChannelSystemImage(_ id: String) -> String {
-        if let symbol = self.store.snapshot?.channelSystemImages?[id], !symbol.isEmpty {
-            return symbol
-        }
-        return "message"
+        return self.store.resolveChannelSystemImage(id)
     }
 
     private func channelStatusDictionary(_ id: String) -> [String: AnyCodable]? {

apps/macos/Sources/Clawdbot/ChannelsStore.swift

@@ -153,11 +153,19 @@ struct ChannelsStatusSnapshot: Codable {
         let application: AnyCodable?
     }
 
+    struct ChannelUiMetaEntry: Codable {
+        let id: String
+        let label: String
+        let detailLabel: String
+        let systemImage: String?
+    }
+
     let ts: Double
     let channelOrder: [String]
     let channelLabels: [String: String]
     let channelDetailLabels: [String: String]? = nil
     let channelSystemImages: [String: String]? = nil
+    let channelMeta: [ChannelUiMetaEntry]? = nil
     let channels: [String: AnyCodable]
     let channelAccounts: [String: [ChannelAccountSnapshot]]
     let channelDefaultAccountId: [String: String]
@@ -219,6 +227,47 @@ final class ChannelsStore {
     var configRoot: [String: Any] = [:]
     var configLoaded = false
 
+    func channelMetaEntry(_ id: String) -> ChannelsStatusSnapshot.ChannelUiMetaEntry? {
+        self.snapshot?.channelMeta?.first(where: { $0.id == id })
+    }
+
+    func resolveChannelLabel(_ id: String) -> String {
+        if let meta = self.channelMetaEntry(id), !meta.label.isEmpty {
+            return meta.label
+        }
+        if let label = self.snapshot?.channelLabels[id], !label.isEmpty {
+            return label
+        }
+        return id
+    }
+
+    func resolveChannelDetailLabel(_ id: String) -> String {
+        if let meta = self.channelMetaEntry(id), !meta.detailLabel.isEmpty {
+            return meta.detailLabel
+        }
+        if let detail = self.snapshot?.channelDetailLabels?[id], !detail.isEmpty {
+            return detail
+        }
+        return self.resolveChannelLabel(id)
+    }
+
+    func resolveChannelSystemImage(_ id: String) -> String {
+        if let meta = self.channelMetaEntry(id), let symbol = meta.systemImage, !symbol.isEmpty {
+            return symbol
+        }
+        if let symbol = self.snapshot?.channelSystemImages?[id], !symbol.isEmpty {
+            return symbol
+        }
+        return "message"
+    }
+
+    func orderedChannelIds() -> [String] {
+        if let meta = self.snapshot?.channelMeta, !meta.isEmpty {
+            return meta.map { $0.id }
+        }
+        return self.snapshot?.channelOrder ?? []
+    }
+
     init(isPreview: Bool = ProcessInfo.processInfo.isPreview) {
         self.isPreview = isPreview
     }

apps/macos/Sources/Clawdbot/CronJobEditor.swift

@@ -55,8 +55,7 @@ struct CronJobEditor: View {
     @State var postPrefix: String = "Cron"
 
     var channelOptions: [String] {
-        let snapshot = self.channelsStore.snapshot
-        let ordered = snapshot?.channelOrder ?? []
+        let ordered = self.channelsStore.orderedChannelIds()
         var options = ["last"] + ordered
         let trimmed = self.channel.trimmingCharacters(in: .whitespacesAndNewlines)
         if !trimmed.isEmpty, !options.contains(trimmed) {
@@ -68,7 +67,7 @@ struct CronJobEditor: View {
 
     func channelLabel(for id: String) -> String {
         if id == "last" { return "last" }
-        return self.channelsStore.snapshot?.channelLabels[id] ?? id
+        return self.channelsStore.resolveChannelLabel(id)
     }
 
     var body: some View {

apps/macos/Sources/ClawdbotProtocol/GatewayModels.swift

@@ -1326,6 +1326,7 @@ public struct ChannelsStatusResult: Codable, Sendable {
     public let channellabels: [String: AnyCodable]
     public let channeldetaillabels: [String: AnyCodable]?
     public let channelsystemimages: [String: AnyCodable]?
+    public let channelmeta: [[String: AnyCodable]]?
     public let channels: [String: AnyCodable]
     public let channelaccounts: [String: AnyCodable]
     public let channeldefaultaccountid: [String: AnyCodable]
@@ -1336,6 +1337,7 @@ public struct ChannelsStatusResult: Codable, Sendable {
         channellabels: [String: AnyCodable],
         channeldetaillabels: [String: AnyCodable]?,
         channelsystemimages: [String: AnyCodable]?,
+        channelmeta: [[String: AnyCodable]]?,
         channels: [String: AnyCodable],
         channelaccounts: [String: AnyCodable],
         channeldefaultaccountid: [String: AnyCodable]
@@ -1345,6 +1347,7 @@ public struct ChannelsStatusResult: Codable, Sendable {
         self.channellabels = channellabels
         self.channeldetaillabels = channeldetaillabels
         self.channelsystemimages = channelsystemimages
+        self.channelmeta = channelmeta
         self.channels = channels
         self.channelaccounts = channelaccounts
         self.channeldefaultaccountid = channeldefaultaccountid
@@ -1355,6 +1358,7 @@ public struct ChannelsStatusResult: Codable, Sendable {
         case channellabels = "channelLabels"
         case channeldetaillabels = "channelDetailLabels"
         case channelsystemimages = "channelSystemImages"
+        case channelmeta = "channelMeta"
         case channels
         case channelaccounts = "channelAccounts"
         case channeldefaultaccountid = "channelDefaultAccountId"

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayChannel.swift

@@ -498,7 +498,7 @@ public actor GatewayChannelActor {
         }
     }
 
-    private func decodeMessageData(_ msg: URLSessionWebSocketTask.Message) -> Data? {
+    private nonisolated func decodeMessageData(_ msg: URLSessionWebSocketTask.Message) -> Data? {
         let data: Data? = switch msg {
         case let .data(data): data
         case let .string(text): text.data(using: .utf8)

apps/shared/ClawdbotKit/Sources/ClawdbotKit/GatewayTLSPinning.swift

@@ -108,5 +108,9 @@ private func sha256Hex(_ data: Data) -> String {
 }
 
 private func normalizeFingerprint(_ raw: String) -> String {
-    raw.lowercased().filter(\.isHexDigit)
+    let stripped = raw.replacingOccurrences(
+        of: #"(?i)^sha-?256\s*:?\s*"#,
+        with: "",
+        options: .regularExpression)
+    return stripped.lowercased().filter(\.isHexDigit)
 }

docs/cli/status.md

@@ -20,4 +20,5 @@ Notes:
 - `--deep` runs live probes (WhatsApp Web + Telegram + Discord + Slack + Signal).
 - Output includes per-agent session stores when multiple agents are configured.
 - Overview includes Gateway + Node service install/runtime status when available.
+- Overview includes update channel + git SHA (for source checkouts).
 - Update info surfaces in the Overview; if an update is available, status prints a hint to run `clawdbot update` (see [Updating](/install/updating)).

docs/cli/update.md

@@ -15,7 +15,9 @@ If you installed via **npm/pnpm** (global install, no git metadata), use the pac
 
 ```bash
 clawdbot update
+clawdbot update status
 clawdbot update --channel beta
+clawdbot update --channel dev
 clawdbot update --tag beta
 clawdbot update --restart
 clawdbot update --json
@@ -25,22 +27,43 @@ clawdbot --update
 ## Options
 
 - `--restart`: restart the Gateway daemon after a successful update.
-- `--channel <stable|beta>`: set the update channel for npm installs (persisted in config).
+- `--channel <stable|beta|dev>`: set the update channel (git + npm; persisted in config).
 - `--tag <dist-tag|version>`: override the npm dist-tag or version for this update only.
 - `--json`: print machine-readable `UpdateRunResult` JSON.
 - `--timeout <seconds>`: per-step timeout (default is 1200s).
 
 Note: downgrades require confirmation because older versions can break configuration.
 
+## `update status`
+
+Show the active update channel + git tag/branch/SHA (for source checkouts), plus update availability.
+
+```bash
+clawdbot update status
+clawdbot update status --json
+clawdbot update status --timeout 10
+```
+
+Options:
+- `--json`: print machine-readable status JSON.
+- `--timeout <seconds>`: timeout for checks (default is 3s).
+
 ## What it does (git checkout)
 
+Channels:
+
+- `stable`: checkout the latest non-beta tag, then build + doctor.
+- `beta`: checkout the latest `-beta` tag, then build + doctor.
+- `dev`: checkout `main`, then fetch + rebase.
+
 High-level:
 
 1. Requires a clean worktree (no uncommitted changes).
-2. Fetches and rebases against `@{upstream}`.
-3. Installs deps (pnpm preferred; npm fallback).
-4. Builds + builds the Control UI.
-5. Runs `clawdbot doctor` as the final “safe update” check.
+2. Switches to the selected channel (tag or branch).
+3. Fetches and rebases against `@{upstream}` (dev only).
+4. Installs deps (pnpm preferred; npm fallback).
+5. Builds + builds the Control UI.
+6. Runs `clawdbot doctor` as the final “safe update” check.
 
 ## `--update` shorthand
 
@@ -49,5 +72,6 @@ High-level:
 ## See also
 
 - `clawdbot doctor` (offers to run update first on git checkouts)
+- [Development channels](/install/development-channels)
 - [Updating](/install/updating)
 - [CLI reference](/cli)

docs/concepts/session.md

@@ -60,7 +60,7 @@ the workspace is writable. See [Memory](/concepts/memory) and
 - Idle reset (optional): `idleMinutes` adds a sliding idle window. When both daily and idle resets are configured, **whichever expires first** forces a new session.
 - Legacy idle-only: if you set `session.idleMinutes` without any `session.reset`/`resetByType` config, Clawdbot stays in idle-only mode for backward compatibility.
 - Per-type overrides (optional): `resetByType` lets you override the policy for `dm`, `group`, and `thread` sessions (thread = Slack/Discord threads, Telegram topics, Matrix threads when provided by the connector).
-- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. If `/new` or `/reset` is sent alone, Clawdbot runs a short “hello” greeting turn to confirm the reset.
+- Reset triggers: exact `/new` or `/reset` (plus any extras in `resetTriggers`) start a fresh session id and pass the remainder of the message through. `/new <model>` accepts a model alias, `provider/model`, or provider name (fuzzy match) to set the new session model. If `/new` or `/reset` is sent alone, Clawdbot runs a short “hello” greeting turn to confirm the reset.
 - Manual reset: delete specific keys from the store or remove the JSONL transcript; the next message recreates them.
 - Isolated cron jobs always mint a fresh `sessionId` per run (no idle reuse).
 

docs/docs.json

@@ -793,6 +793,7 @@
           "install/index",
           "install/installer",
           "install/updating",
+          "install/development-channels",
           "install/uninstall",
           "install/ansible",
           "install/nix",

docs/gateway/troubleshooting.md

@@ -79,6 +79,9 @@ This intentionally excludes version managers (nvm/fnm/volta/asdf) and package
 managers (pnpm/npm) because the daemon does not load your shell init. Runtime
 variables like `DISPLAY` should live in `~/.clawdbot/.env` (loaded early by the
 gateway).
+Exec runs on `host=gateway` merge your login-shell `PATH` into the exec environment,
+so missing tools usually mean your shell init isn’t exporting them (or set
+`tools.exec.pathPrepend`). See [/tools/exec](/tools/exec).
 
 WhatsApp + Telegram channels require **Node**; Bun is unsupported. If your
 service was installed with Bun or a version-managed Node path, run `clawdbot doctor`

docs/install/development-channels.md

@@ -0,0 +1,56 @@
+---
+summary: "Stable, beta, and dev channels: semantics, switching, and tagging"
+read_when:
+  - You want to switch between stable/beta/dev
+  - You are tagging or publishing prereleases
+---
+
+# Development channels
+
+Clawdbot ships three update channels:
+
+- **stable**: tagged releases (`vYYYY.M.D` or `vYYYY.M.D-<patch>`). npm dist-tag: `latest`.
+- **beta**: prerelease tags (`vYYYY.M.D-beta.N`). npm dist-tag: `beta`.
+- **dev**: moving head of `main` (git). npm dist-tag: `dev` (when published).
+
+## Switching channels
+
+Git checkout:
+
+```bash
+clawdbot update --channel stable
+clawdbot update --channel beta
+clawdbot update --channel dev
+```
+
+- `stable`/`beta` check out the latest matching tag.
+- `dev` switches to `main` and rebases on the upstream.
+
+npm/pnpm global install:
+
+```bash
+clawdbot update --channel stable
+clawdbot update --channel beta
+clawdbot update --channel dev
+```
+
+This updates via the corresponding npm dist-tag (`latest`, `beta`, `dev`).
+
+Tip: if you want stable + dev in parallel, keep two clones and point your gateway at the stable one.
+
+## Tagging best practices
+
+- Stable: tag each release (`vYYYY.M.D` or `vYYYY.M.D-<patch>`).
+- Beta: use `vYYYY.M.D-beta.N` (increment `N`).
+- Keep tags immutable: never move or reuse a tag.
+- Publish dist-tags alongside git tags:
+  - `latest` → stable
+  - `beta` → prerelease
+  - `dev` → main snapshot (optional)
+
+## macOS app availability
+
+Beta and dev builds may **not** include a macOS app release. That’s OK:
+
+- The git tag and npm dist-tag can still be published.
+- Call out “no macOS build for this beta” in release notes or changelog.

docs/install/updating.md

@@ -50,20 +50,18 @@ pnpm add -g clawdbot@latest
 ```
 We do **not** recommend Bun for the Gateway runtime (WhatsApp/Telegram bugs).
 
-To stay on the beta channel for CLI updates:
+To switch update channels (git + npm installs):
 
 ```bash
 clawdbot update --channel beta
-```
-
-Switch back to stable later:
-
-```bash
+clawdbot update --channel dev
 clawdbot update --channel stable
 ```
 
 Use `--tag <dist-tag|version>` for a one-off install tag/version.
 
+See [Development channels](/install/development-channels) for channel semantics and release notes.
+
 Note: on npm installs, the gateway logs an update hint on startup (checks the current channel tag). Disable via `update.checkOnStart: false`.
 
 Then:
@@ -88,7 +86,8 @@ clawdbot update --restart
 
 It runs a safe-ish update flow:
 - Requires a clean worktree.
-- Fetches + rebases against the configured upstream.
+- Switches to the selected channel (tag or branch).
+- Fetches + rebases against the configured upstream (dev channel).
 - Installs deps, builds, builds the Control UI, and runs `clawdbot doctor`.
 
 If you installed via **npm/pnpm** (no git metadata), `clawdbot update` will try to update via your package manager. If it can’t detect the install, use “Update (global install)” instead.

docs/tools/exec.md

@@ -57,7 +57,8 @@ Example:
 
 ### PATH handling
 
-- `host=gateway`: uses the Gateway process `PATH`. Daemons install a minimal `PATH`:
+- `host=gateway`: merges your login-shell `PATH` into the exec environment (unless the exec call
+  already sets `env.PATH`). The daemon itself still runs with a minimal `PATH`:
   - macOS: `/opt/homebrew/bin`, `/usr/local/bin`, `/usr/bin`, `/bin`
   - Linux: `/usr/local/bin`, `/usr/bin`, `/bin`
 - `host=sandbox`: runs `sh -lc` (login shell) inside the container, so `/etc/profile` may reset `PATH`.

docs/tools/slash-commands.md

@@ -58,6 +58,7 @@ They run immediately, are stripped before the model sees the message, and the re
 Text + native (when enabled):
 - `/help`
 - `/commands`
+- `/skill <name> [input]` (run a skill by name)
 - `/status` (show current status; includes provider usage/quota for the current model provider when available)
 - `/context [list|detail|json]` (explain “context”; `detail` shows per-file + per-tool + per-skill + system prompt size)
 - `/whoami` (show your sender id; alias: `/id`)
@@ -72,7 +73,7 @@ Text + native (when enabled):
 - `/dock-slack` (alias: `/dock_slack`) (switch replies to Slack)
 - `/activation mention|always` (groups only)
 - `/send on|off|inherit` (owner-only)
-- `/reset` or `/new`
+- `/reset` or `/new [model]` (optional model hint; remainder is passed through)
 - `/think <off|minimal|low|medium|high|xhigh>` (dynamic choices by model/provider; aliases: `/thinking`, `/t`)
 - `/verbose on|full|off` (alias: `/v`)
 - `/reasoning on|off|stream` (alias: `/reason`; when on, sends a separate message prefixed `Reasoning:`; `stream` = Telegram draft only)
@@ -90,6 +91,7 @@ Text-only:
 
 Notes:
 - Commands accept an optional `:` between the command and args (e.g. `/think: high`, `/send: on`, `/help:`).
+- `/new <model>` accepts a model alias, `provider/model`, or a provider name (fuzzy match); if no match, the text is treated as the message body.
 - For full provider usage breakdown, use `clawdbot status --usage`.
 - `/usage` controls the per-response usage footer; `/usage cost` prints a local cost summary from Clawdbot session logs.
 - `/restart` is disabled by default; set `commands.restart: true` to enable it.
@@ -102,6 +104,7 @@ Notes:
 - Currently: `/help`, `/commands`, `/status`, `/whoami` (`/id`).
 - Unauthorized command-only messages are silently ignored, and inline `/...` tokens are treated as plain text.
 - **Skill commands:** `user-invocable` skills are exposed as slash commands. Names are sanitized to `a-z0-9_` (max 32 chars); collisions get numeric suffixes (e.g. `_2`).
+  - `/skill <name> [input]` runs a skill by name (useful when native command limits prevent per-skill commands).
   - By default, skill commands are forwarded to the model as a normal request.
   - Skills may optionally declare `command-dispatch: tool` to route the command directly to a tool (deterministic, no model).
 - **Native command arguments:** Discord uses autocomplete for dynamic options (and button menus when you omit required args). Telegram and Slack show a button menu when a command supports choices and you omit the arg.

extensions/bluebubbles/src/actions.ts

@@ -1,4 +1,6 @@
 import {
+  BLUEBUBBLES_ACTION_NAMES,
+  BLUEBUBBLES_ACTIONS,
   createActionGate,
   jsonResult,
   readBooleanParam,
@@ -49,19 +51,7 @@ function readMessageText(params: Record<string, unknown>): string | undefined {
 }
 
 /** Supported action names for BlueBubbles */
-const SUPPORTED_ACTIONS = new Set<ChannelMessageActionName>([
-  "react",
-  "edit",
-  "unsend",
-  "reply",
-  "sendWithEffect",
-  "renameGroup",
-  "setGroupIcon",
-  "addParticipant",
-  "removeParticipant",
-  "leaveGroup",
-  "sendAttachment",
-]);
+const SUPPORTED_ACTIONS = new Set<ChannelMessageActionName>(BLUEBUBBLES_ACTION_NAMES);
 
 export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
   listActions: ({ cfg }) => {
@@ -69,19 +59,13 @@ export const bluebubblesMessageActions: ChannelMessageActionAdapter = {
     if (!account.enabled || !account.configured) return [];
     const gate = createActionGate((cfg as ClawdbotConfig).channels?.bluebubbles?.actions);
     const actions = new Set<ChannelMessageActionName>();
-    // Check if running on macOS 26+ (edit not supported)
     const macOS26 = isMacOS26OrHigher(account.accountId);
-    if (gate("reactions")) actions.add("react");
-    if (gate("edit") && !macOS26) actions.add("edit");
-    if (gate("unsend")) actions.add("unsend");
-    if (gate("reply")) actions.add("reply");
-    if (gate("sendWithEffect")) actions.add("sendWithEffect");
-    if (gate("renameGroup")) actions.add("renameGroup");
-    if (gate("setGroupIcon")) actions.add("setGroupIcon");
-    if (gate("addParticipant")) actions.add("addParticipant");
-    if (gate("removeParticipant")) actions.add("removeParticipant");
-    if (gate("leaveGroup")) actions.add("leaveGroup");
-    if (gate("sendAttachment")) actions.add("sendAttachment");
+    for (const action of BLUEBUBBLES_ACTION_NAMES) {
+      const spec = BLUEBUBBLES_ACTIONS[action];
+      if (!spec?.gate) continue;
+      if (spec.unsupportedOnMacOS26 && macOS26) continue;
+      if (gate(spec.gate)) actions.add(action);
+    }
     return Array.from(actions);
   },
   supportsAction: ({ action }) => SUPPORTED_ACTIONS.has(action),

extensions/matrix/src/matrix/actions.ts

@@ -1,518 +1,15 @@
-import type { MatrixClient } from "matrix-bot-sdk";
-
-import { getMatrixRuntime } from "../runtime.js";
-import type { CoreConfig } from "../types.js";
-import { getActiveMatrixClient } from "./active-client.js";
-import {
-  createMatrixClient,
-  isBunRuntime,
-  resolveMatrixAuth,
-  resolveSharedMatrixClient,
-} from "./client.js";
-import {
-  reactMatrixMessage,
-  resolveMatrixRoomId,
-  sendMessageMatrix,
-} from "./send.js";
-
-// Constants that were previously from matrix-js-sdk
-const MsgType = {
-  Text: "m.text",
-} as const;
-
-const RelationType = {
-  Replace: "m.replace",
-  Annotation: "m.annotation",
-} as const;
-
-const EventType = {
-  RoomMessage: "m.room.message",
-  RoomPinnedEvents: "m.room.pinned_events",
-  RoomTopic: "m.room.topic",
-  Reaction: "m.reaction",
-} as const;
-
-// Type definitions for matrix-bot-sdk event content
-type RoomMessageEventContent = {
-  msgtype: string;
-  body: string;
-  "m.new_content"?: RoomMessageEventContent;
-  "m.relates_to"?: {
-    rel_type?: string;
-    event_id?: string;
-    "m.in_reply_to"?: { event_id?: string };
-  };
-};
-
-type ReactionEventContent = {
-  "m.relates_to": {
-    rel_type: string;
-    event_id: string;
-    key: string;
-  };
-};
-
-type RoomPinnedEventsEventContent = {
-  pinned: string[];
-};
-
-type RoomTopicEventContent = {
-  topic?: string;
-};
-
-type MatrixRawEvent = {
-  event_id: string;
-  sender: string;
-  type: string;
-  origin_server_ts: number;
-  content: Record<string, unknown>;
-  unsigned?: {
-    redacted_because?: unknown;
-  };
-};
-
-export type MatrixActionClientOpts = {
-  client?: MatrixClient;
-  timeoutMs?: number;
-};
-
-export type MatrixMessageSummary = {
-  eventId?: string;
-  sender?: string;
-  body?: string;
-  msgtype?: string;
-  timestamp?: number;
-  relatesTo?: {
-    relType?: string;
-    eventId?: string;
-    key?: string;
-  };
-};
-
-export type MatrixReactionSummary = {
-  key: string;
-  count: number;
-  users: string[];
-};
-
-type MatrixActionClient = {
-  client: MatrixClient;
-  stopOnDone: boolean;
-};
-
-function ensureNodeRuntime() {
-  if (isBunRuntime()) {
-    throw new Error("Matrix support requires Node (bun runtime not supported)");
-  }
-}
-
-async function resolveActionClient(opts: MatrixActionClientOpts = {}): Promise<MatrixActionClient> {
-  ensureNodeRuntime();
-  if (opts.client) return { client: opts.client, stopOnDone: false };
-  const active = getActiveMatrixClient();
-  if (active) return { client: active, stopOnDone: false };
-  const shouldShareClient = Boolean(process.env.CLAWDBOT_GATEWAY_PORT);
-  if (shouldShareClient) {
-    const client = await resolveSharedMatrixClient({
-      cfg: getMatrixRuntime().config.loadConfig() as CoreConfig,
-      timeoutMs: opts.timeoutMs,
-    });
-    return { client, stopOnDone: false };
-  }
-  const auth = await resolveMatrixAuth({
-    cfg: getMatrixRuntime().config.loadConfig() as CoreConfig,
-  });
-  const client = await createMatrixClient({
-    homeserver: auth.homeserver,
-    userId: auth.userId,
-    accessToken: auth.accessToken,
-    encryption: auth.encryption,
-    localTimeoutMs: opts.timeoutMs,
-  });
-  if (auth.encryption && client.crypto) {
-    try {
-      const joinedRooms = await client.getJoinedRooms();
-      await client.crypto.prepare(joinedRooms);
-    } catch {
-      // Ignore crypto prep failures for one-off actions.
-    }
-  }
-  await client.start();
-  return { client, stopOnDone: true };
-}
-
-function summarizeMatrixRawEvent(event: MatrixRawEvent): MatrixMessageSummary {
-  const content = event.content as RoomMessageEventContent;
-  const relates = content["m.relates_to"];
-  let relType: string | undefined;
-  let eventId: string | undefined;
-  if (relates) {
-    if ("rel_type" in relates) {
-      relType = relates.rel_type;
-      eventId = relates.event_id;
-    } else if ("m.in_reply_to" in relates) {
-      eventId = relates["m.in_reply_to"]?.event_id;
-    }
-  }
-  const relatesTo =
-    relType || eventId
-      ? {
-          relType,
-          eventId,
-        }
-      : undefined;
-  return {
-    eventId: event.event_id,
-    sender: event.sender,
-    body: content.body,
-    msgtype: content.msgtype,
-    timestamp: event.origin_server_ts,
-    relatesTo,
-  };
-}
-
-async function readPinnedEvents(client: MatrixClient, roomId: string): Promise<string[]> {
-  try {
-    const content = (await client.getRoomStateEvent(
-      roomId,
-      EventType.RoomPinnedEvents,
-      "",
-    )) as RoomPinnedEventsEventContent;
-    const pinned = content.pinned;
-    return pinned.filter((id) => id.trim().length > 0);
-  } catch (err: unknown) {
-    const errObj = err as { statusCode?: number; body?: { errcode?: string } };
-    const httpStatus = errObj.statusCode;
-    const errcode = errObj.body?.errcode;
-    if (httpStatus === 404 || errcode === "M_NOT_FOUND") {
-      return [];
-    }
-    throw err;
-  }
-}
-
-async function fetchEventSummary(
-  client: MatrixClient,
-  roomId: string,
-  eventId: string,
-): Promise<MatrixMessageSummary | null> {
-  try {
-    const raw = await client.getEvent(roomId, eventId) as MatrixRawEvent;
-    if (raw.unsigned?.redacted_because) return null;
-    return summarizeMatrixRawEvent(raw);
-  } catch (err) {
-    // Event not found, redacted, or inaccessible - return null
-    return null;
-  }
-}
-
-export async function sendMatrixMessage(
-  to: string,
-  content: string,
-  opts: MatrixActionClientOpts & {
-    mediaUrl?: string;
-    replyToId?: string;
-    threadId?: string;
-  } = {},
-) {
-  return await sendMessageMatrix(to, content, {
-    mediaUrl: opts.mediaUrl,
-    replyToId: opts.replyToId,
-    threadId: opts.threadId,
-    client: opts.client,
-    timeoutMs: opts.timeoutMs,
-  });
-}
-
-export async function editMatrixMessage(
-  roomId: string,
-  messageId: string,
-  content: string,
-  opts: MatrixActionClientOpts = {},
-) {
-  const trimmed = content.trim();
-  if (!trimmed) throw new Error("Matrix edit requires content");
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const newContent = {
-      msgtype: MsgType.Text,
-      body: trimmed,
-    } satisfies RoomMessageEventContent;
-    const payload: RoomMessageEventContent = {
-      msgtype: MsgType.Text,
-      body: `* ${trimmed}`,
-      "m.new_content": newContent,
-      "m.relates_to": {
-        rel_type: RelationType.Replace,
-        event_id: messageId,
-      },
-    };
-    const eventId = await client.sendMessage(resolvedRoom, payload);
-    return { eventId: eventId ?? null };
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export async function deleteMatrixMessage(
-  roomId: string,
-  messageId: string,
-  opts: MatrixActionClientOpts & { reason?: string } = {},
-) {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    await client.redactEvent(resolvedRoom, messageId, opts.reason);
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export async function readMatrixMessages(
-  roomId: string,
-  opts: MatrixActionClientOpts & {
-    limit?: number;
-    before?: string;
-    after?: string;
-  } = {},
-): Promise<{
-  messages: MatrixMessageSummary[];
-  nextBatch?: string | null;
-  prevBatch?: string | null;
-}> {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const limit =
-      typeof opts.limit === "number" && Number.isFinite(opts.limit)
-        ? Math.max(1, Math.floor(opts.limit))
-        : 20;
-    const token = opts.before?.trim() || opts.after?.trim() || undefined;
-    const dir = opts.after ? "f" : "b";
-    // matrix-bot-sdk uses doRequest for room messages
-    const res = await client.doRequest("GET", `/_matrix/client/v3/rooms/${encodeURIComponent(resolvedRoom)}/messages`, {
-      dir,
-      limit,
-      from: token,
-    }) as { chunk: MatrixRawEvent[]; start?: string; end?: string };
-    const messages = res.chunk
-      .filter((event) => event.type === EventType.RoomMessage)
-      .filter((event) => !event.unsigned?.redacted_because)
-      .map(summarizeMatrixRawEvent);
-    return {
-      messages,
-      nextBatch: res.end ?? null,
-      prevBatch: res.start ?? null,
-    };
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export async function listMatrixReactions(
-  roomId: string,
-  messageId: string,
-  opts: MatrixActionClientOpts & { limit?: number } = {},
-): Promise<MatrixReactionSummary[]> {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const limit =
-      typeof opts.limit === "number" && Number.isFinite(opts.limit)
-        ? Math.max(1, Math.floor(opts.limit))
-        : 100;
-    // matrix-bot-sdk uses doRequest for relations
-    const res = await client.doRequest(
-      "GET",
-      `/_matrix/client/v1/rooms/${encodeURIComponent(resolvedRoom)}/relations/${encodeURIComponent(messageId)}/${RelationType.Annotation}/${EventType.Reaction}`,
-      { dir: "b", limit },
-    ) as { chunk: MatrixRawEvent[] };
-    const summaries = new Map<string, MatrixReactionSummary>();
-    for (const event of res.chunk) {
-      const content = event.content as ReactionEventContent;
-      const key = content["m.relates_to"]?.key;
-      if (!key) continue;
-      const sender = event.sender ?? "";
-      const entry: MatrixReactionSummary = summaries.get(key) ?? {
-        key,
-        count: 0,
-        users: [],
-      };
-      entry.count += 1;
-      if (sender && !entry.users.includes(sender)) {
-        entry.users.push(sender);
-      }
-      summaries.set(key, entry);
-    }
-    return Array.from(summaries.values());
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export async function removeMatrixReactions(
-  roomId: string,
-  messageId: string,
-  opts: MatrixActionClientOpts & { emoji?: string } = {},
-): Promise<{ removed: number }> {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const res = await client.doRequest(
-      "GET",
-      `/_matrix/client/v1/rooms/${encodeURIComponent(resolvedRoom)}/relations/${encodeURIComponent(messageId)}/${RelationType.Annotation}/${EventType.Reaction}`,
-      { dir: "b", limit: 200 },
-    ) as { chunk: MatrixRawEvent[] };
-    const userId = await client.getUserId();
-    if (!userId) return { removed: 0 };
-    const targetEmoji = opts.emoji?.trim();
-    const toRemove = res.chunk
-      .filter((event) => event.sender === userId)
-      .filter((event) => {
-        if (!targetEmoji) return true;
-        const content = event.content as ReactionEventContent;
-        return content["m.relates_to"]?.key === targetEmoji;
-      })
-      .map((event) => event.event_id)
-      .filter((id): id is string => Boolean(id));
-    if (toRemove.length === 0) return { removed: 0 };
-    await Promise.all(toRemove.map((id) => client.redactEvent(resolvedRoom, id)));
-    return { removed: toRemove.length };
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export async function pinMatrixMessage(
-  roomId: string,
-  messageId: string,
-  opts: MatrixActionClientOpts = {},
-): Promise<{ pinned: string[] }> {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const current = await readPinnedEvents(client, resolvedRoom);
-    const next = current.includes(messageId) ? current : [...current, messageId];
-    const payload: RoomPinnedEventsEventContent = { pinned: next };
-    await client.sendStateEvent(resolvedRoom, EventType.RoomPinnedEvents, "", payload);
-    return { pinned: next };
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export async function unpinMatrixMessage(
-  roomId: string,
-  messageId: string,
-  opts: MatrixActionClientOpts = {},
-): Promise<{ pinned: string[] }> {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const current = await readPinnedEvents(client, resolvedRoom);
-    const next = current.filter((id) => id !== messageId);
-    const payload: RoomPinnedEventsEventContent = { pinned: next };
-    await client.sendStateEvent(resolvedRoom, EventType.RoomPinnedEvents, "", payload);
-    return { pinned: next };
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export async function listMatrixPins(
-  roomId: string,
-  opts: MatrixActionClientOpts = {},
-): Promise<{ pinned: string[]; events: MatrixMessageSummary[] }> {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    const pinned = await readPinnedEvents(client, resolvedRoom);
-    const events = (
-      await Promise.all(
-        pinned.map(async (eventId) => {
-          try {
-            return await fetchEventSummary(client, resolvedRoom, eventId);
-          } catch {
-            return null;
-          }
-        }),
-      )
-    ).filter((event): event is MatrixMessageSummary => Boolean(event));
-    return { pinned, events };
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export async function getMatrixMemberInfo(
-  userId: string,
-  opts: MatrixActionClientOpts & { roomId?: string } = {},
-) {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const roomId = opts.roomId ? await resolveMatrixRoomId(client, opts.roomId) : undefined;
-    // matrix-bot-sdk uses getUserProfile
-    const profile = await client.getUserProfile(userId);
-    // Note: matrix-bot-sdk doesn't have getRoom().getMember() like matrix-js-sdk
-    // We'd need to fetch room state separately if needed
-    return {
-      userId,
-      profile: {
-        displayName: profile?.displayname ?? null,
-        avatarUrl: profile?.avatar_url ?? null,
-      },
-      membership: null, // Would need separate room state query
-      powerLevel: null, // Would need separate power levels state query
-      displayName: profile?.displayname ?? null,
-      roomId: roomId ?? null,
-    };
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export async function getMatrixRoomInfo(roomId: string, opts: MatrixActionClientOpts = {}) {
-  const { client, stopOnDone } = await resolveActionClient(opts);
-  try {
-    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
-    // matrix-bot-sdk uses getRoomState for state events
-    let name: string | null = null;
-    let topic: string | null = null;
-    let canonicalAlias: string | null = null;
-    let memberCount: number | null = null;
-    
-    try {
-      const nameState = await client.getRoomStateEvent(resolvedRoom, "m.room.name", "");
-      name = nameState?.name ?? null;
-    } catch { /* ignore */ }
-    
-    try {
-      const topicState = await client.getRoomStateEvent(resolvedRoom, EventType.RoomTopic, "");
-      topic = topicState?.topic ?? null;
-    } catch { /* ignore */ }
-    
-    try {
-      const aliasState = await client.getRoomStateEvent(resolvedRoom, "m.room.canonical_alias", "");
-      canonicalAlias = aliasState?.alias ?? null;
-    } catch { /* ignore */ }
-    
-    try {
-      const members = await client.getJoinedRoomMembers(resolvedRoom);
-      memberCount = members.length;
-    } catch { /* ignore */ }
-    
-    return {
-      roomId: resolvedRoom,
-      name,
-      topic,
-      canonicalAlias,
-      altAliases: [], // Would need separate query
-      memberCount,
-    };
-  } finally {
-    if (stopOnDone) client.stop();
-  }
-}
-
-export { reactMatrixMessage };
+export type {
+  MatrixActionClientOpts,
+  MatrixMessageSummary,
+  MatrixReactionSummary,
+} from "./actions/types.js";
+export {
+  sendMatrixMessage,
+  editMatrixMessage,
+  deleteMatrixMessage,
+  readMatrixMessages,
+} from "./actions/messages.js";
+export { listMatrixReactions, removeMatrixReactions } from "./actions/reactions.js";
+export { pinMatrixMessage, unpinMatrixMessage, listMatrixPins } from "./actions/pins.js";
+export { getMatrixMemberInfo, getMatrixRoomInfo } from "./actions/room.js";
+export { reactMatrixMessage } from "./send.js";

extensions/matrix/src/matrix/actions/client.ts

@@ -0,0 +1,53 @@
+import { getMatrixRuntime } from "../../runtime.js";
+import type { CoreConfig } from "../types.js";
+import { getActiveMatrixClient } from "../active-client.js";
+import {
+  createMatrixClient,
+  isBunRuntime,
+  resolveMatrixAuth,
+  resolveSharedMatrixClient,
+} from "../client.js";
+import type { MatrixActionClient, MatrixActionClientOpts } from "./types.js";
+
+export function ensureNodeRuntime() {
+  if (isBunRuntime()) {
+    throw new Error("Matrix support requires Node (bun runtime not supported)");
+  }
+}
+
+export async function resolveActionClient(
+  opts: MatrixActionClientOpts = {},
+): Promise<MatrixActionClient> {
+  ensureNodeRuntime();
+  if (opts.client) return { client: opts.client, stopOnDone: false };
+  const active = getActiveMatrixClient();
+  if (active) return { client: active, stopOnDone: false };
+  const shouldShareClient = Boolean(process.env.CLAWDBOT_GATEWAY_PORT);
+  if (shouldShareClient) {
+    const client = await resolveSharedMatrixClient({
+      cfg: getMatrixRuntime().config.loadConfig() as CoreConfig,
+      timeoutMs: opts.timeoutMs,
+    });
+    return { client, stopOnDone: false };
+  }
+  const auth = await resolveMatrixAuth({
+    cfg: getMatrixRuntime().config.loadConfig() as CoreConfig,
+  });
+  const client = await createMatrixClient({
+    homeserver: auth.homeserver,
+    userId: auth.userId,
+    accessToken: auth.accessToken,
+    encryption: auth.encryption,
+    localTimeoutMs: opts.timeoutMs,
+  });
+  if (auth.encryption && client.crypto) {
+    try {
+      const joinedRooms = await client.getJoinedRooms();
+      await client.crypto.prepare(joinedRooms);
+    } catch {
+      // Ignore crypto prep failures for one-off actions.
+    }
+  }
+  await client.start();
+  return { client, stopOnDone: true };
+}

extensions/matrix/src/matrix/actions/messages.ts

@@ -0,0 +1,120 @@
+import {
+  EventType,
+  MsgType,
+  RelationType,
+  type MatrixActionClientOpts,
+  type MatrixMessageSummary,
+  type MatrixRawEvent,
+  type RoomMessageEventContent,
+} from "./types.js";
+import { resolveActionClient } from "./client.js";
+import { summarizeMatrixRawEvent } from "./summary.js";
+import { resolveMatrixRoomId, sendMessageMatrix } from "../send.js";
+
+export async function sendMatrixMessage(
+  to: string,
+  content: string,
+  opts: MatrixActionClientOpts & {
+    mediaUrl?: string;
+    replyToId?: string;
+    threadId?: string;
+  } = {},
+) {
+  return await sendMessageMatrix(to, content, {
+    mediaUrl: opts.mediaUrl,
+    replyToId: opts.replyToId,
+    threadId: opts.threadId,
+    client: opts.client,
+    timeoutMs: opts.timeoutMs,
+  });
+}
+
+export async function editMatrixMessage(
+  roomId: string,
+  messageId: string,
+  content: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  const trimmed = content.trim();
+  if (!trimmed) throw new Error("Matrix edit requires content");
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    const newContent = {
+      msgtype: MsgType.Text,
+      body: trimmed,
+    } satisfies RoomMessageEventContent;
+    const payload: RoomMessageEventContent = {
+      msgtype: MsgType.Text,
+      body: `* ${trimmed}`,
+      "m.new_content": newContent,
+      "m.relates_to": {
+        rel_type: RelationType.Replace,
+        event_id: messageId,
+      },
+    };
+    const eventId = await client.sendMessage(resolvedRoom, payload);
+    return { eventId: eventId ?? null };
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}
+
+export async function deleteMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts & { reason?: string } = {},
+) {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    await client.redactEvent(resolvedRoom, messageId, opts.reason);
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}
+
+export async function readMatrixMessages(
+  roomId: string,
+  opts: MatrixActionClientOpts & {
+    limit?: number;
+    before?: string;
+    after?: string;
+  } = {},
+): Promise<{
+  messages: MatrixMessageSummary[];
+  nextBatch?: string | null;
+  prevBatch?: string | null;
+}> {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    const limit =
+      typeof opts.limit === "number" && Number.isFinite(opts.limit)
+        ? Math.max(1, Math.floor(opts.limit))
+        : 20;
+    const token = opts.before?.trim() || opts.after?.trim() || undefined;
+    const dir = opts.after ? "f" : "b";
+    // matrix-bot-sdk uses doRequest for room messages
+    const res = await client.doRequest(
+      "GET",
+      `/_matrix/client/v3/rooms/${encodeURIComponent(resolvedRoom)}/messages`,
+      {
+        dir,
+        limit,
+        from: token,
+      },
+    ) as { chunk: MatrixRawEvent[]; start?: string; end?: string };
+    const messages = res.chunk
+      .filter((event) => event.type === EventType.RoomMessage)
+      .filter((event) => !event.unsigned?.redacted_because)
+      .map(summarizeMatrixRawEvent);
+    return {
+      messages,
+      nextBatch: res.end ?? null,
+      prevBatch: res.start ?? null,
+    };
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}

extensions/matrix/src/matrix/actions/pins.ts

@@ -0,0 +1,70 @@
+import {
+  EventType,
+  type MatrixActionClientOpts,
+  type MatrixMessageSummary,
+  type RoomPinnedEventsEventContent,
+} from "./types.js";
+import { resolveActionClient } from "./client.js";
+import { fetchEventSummary, readPinnedEvents } from "./summary.js";
+import { resolveMatrixRoomId } from "../send.js";
+
+export async function pinMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[] }> {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    const current = await readPinnedEvents(client, resolvedRoom);
+    const next = current.includes(messageId) ? current : [...current, messageId];
+    const payload: RoomPinnedEventsEventContent = { pinned: next };
+    await client.sendStateEvent(resolvedRoom, EventType.RoomPinnedEvents, "", payload);
+    return { pinned: next };
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}
+
+export async function unpinMatrixMessage(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[] }> {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    const current = await readPinnedEvents(client, resolvedRoom);
+    const next = current.filter((id) => id !== messageId);
+    const payload: RoomPinnedEventsEventContent = { pinned: next };
+    await client.sendStateEvent(resolvedRoom, EventType.RoomPinnedEvents, "", payload);
+    return { pinned: next };
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}
+
+export async function listMatrixPins(
+  roomId: string,
+  opts: MatrixActionClientOpts = {},
+): Promise<{ pinned: string[]; events: MatrixMessageSummary[] }> {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    const pinned = await readPinnedEvents(client, resolvedRoom);
+    const events = (
+      await Promise.all(
+        pinned.map(async (eventId) => {
+          try {
+            return await fetchEventSummary(client, resolvedRoom, eventId);
+          } catch {
+            return null;
+          }
+        }),
+      )
+    ).filter((event): event is MatrixMessageSummary => Boolean(event));
+    return { pinned, events };
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}

extensions/matrix/src/matrix/actions/reactions.ts

@@ -0,0 +1,84 @@
+import {
+  EventType,
+  RelationType,
+  type MatrixActionClientOpts,
+  type MatrixRawEvent,
+  type MatrixReactionSummary,
+  type ReactionEventContent,
+} from "./types.js";
+import { resolveActionClient } from "./client.js";
+import { resolveMatrixRoomId } from "../send.js";
+
+export async function listMatrixReactions(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts & { limit?: number } = {},
+): Promise<MatrixReactionSummary[]> {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    const limit =
+      typeof opts.limit === "number" && Number.isFinite(opts.limit)
+        ? Math.max(1, Math.floor(opts.limit))
+        : 100;
+    // matrix-bot-sdk uses doRequest for relations
+    const res = await client.doRequest(
+      "GET",
+      `/_matrix/client/v1/rooms/${encodeURIComponent(resolvedRoom)}/relations/${encodeURIComponent(messageId)}/${RelationType.Annotation}/${EventType.Reaction}`,
+      { dir: "b", limit },
+    ) as { chunk: MatrixRawEvent[] };
+    const summaries = new Map<string, MatrixReactionSummary>();
+    for (const event of res.chunk) {
+      const content = event.content as ReactionEventContent;
+      const key = content["m.relates_to"]?.key;
+      if (!key) continue;
+      const sender = event.sender ?? "";
+      const entry: MatrixReactionSummary = summaries.get(key) ?? {
+        key,
+        count: 0,
+        users: [],
+      };
+      entry.count += 1;
+      if (sender && !entry.users.includes(sender)) {
+        entry.users.push(sender);
+      }
+      summaries.set(key, entry);
+    }
+    return Array.from(summaries.values());
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}
+
+export async function removeMatrixReactions(
+  roomId: string,
+  messageId: string,
+  opts: MatrixActionClientOpts & { emoji?: string } = {},
+): Promise<{ removed: number }> {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    const res = await client.doRequest(
+      "GET",
+      `/_matrix/client/v1/rooms/${encodeURIComponent(resolvedRoom)}/relations/${encodeURIComponent(messageId)}/${RelationType.Annotation}/${EventType.Reaction}`,
+      { dir: "b", limit: 200 },
+    ) as { chunk: MatrixRawEvent[] };
+    const userId = await client.getUserId();
+    if (!userId) return { removed: 0 };
+    const targetEmoji = opts.emoji?.trim();
+    const toRemove = res.chunk
+      .filter((event) => event.sender === userId)
+      .filter((event) => {
+        if (!targetEmoji) return true;
+        const content = event.content as ReactionEventContent;
+        return content["m.relates_to"]?.key === targetEmoji;
+      })
+      .map((event) => event.event_id)
+      .filter((id): id is string => Boolean(id));
+    if (toRemove.length === 0) return { removed: 0 };
+    await Promise.all(toRemove.map((id) => client.redactEvent(resolvedRoom, id)));
+    return { removed: toRemove.length };
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}

extensions/matrix/src/matrix/actions/room.ts

@@ -0,0 +1,88 @@
+import { EventType, type MatrixActionClientOpts } from "./types.js";
+import { resolveActionClient } from "./client.js";
+import { resolveMatrixRoomId } from "../send.js";
+
+export async function getMatrixMemberInfo(
+  userId: string,
+  opts: MatrixActionClientOpts & { roomId?: string } = {},
+) {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const roomId = opts.roomId ? await resolveMatrixRoomId(client, opts.roomId) : undefined;
+    // matrix-bot-sdk uses getUserProfile
+    const profile = await client.getUserProfile(userId);
+    // Note: matrix-bot-sdk doesn't have getRoom().getMember() like matrix-js-sdk
+    // We'd need to fetch room state separately if needed
+    return {
+      userId,
+      profile: {
+        displayName: profile?.displayname ?? null,
+        avatarUrl: profile?.avatar_url ?? null,
+      },
+      membership: null, // Would need separate room state query
+      powerLevel: null, // Would need separate power levels state query
+      displayName: profile?.displayname ?? null,
+      roomId: roomId ?? null,
+    };
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}
+
+export async function getMatrixRoomInfo(
+  roomId: string,
+  opts: MatrixActionClientOpts = {},
+) {
+  const { client, stopOnDone } = await resolveActionClient(opts);
+  try {
+    const resolvedRoom = await resolveMatrixRoomId(client, roomId);
+    // matrix-bot-sdk uses getRoomState for state events
+    let name: string | null = null;
+    let topic: string | null = null;
+    let canonicalAlias: string | null = null;
+    let memberCount: number | null = null;
+
+    try {
+      const nameState = await client.getRoomStateEvent(resolvedRoom, "m.room.name", "");
+      name = nameState?.name ?? null;
+    } catch {
+      // ignore
+    }
+
+    try {
+      const topicState = await client.getRoomStateEvent(resolvedRoom, EventType.RoomTopic, "");
+      topic = topicState?.topic ?? null;
+    } catch {
+      // ignore
+    }
+
+    try {
+      const aliasState = await client.getRoomStateEvent(
+        resolvedRoom,
+        "m.room.canonical_alias",
+        "",
+      );
+      canonicalAlias = aliasState?.alias ?? null;
+    } catch {
+      // ignore
+    }
+
+    try {
+      const members = await client.getJoinedRoomMembers(resolvedRoom);
+      memberCount = members.length;
+    } catch {
+      // ignore
+    }
+
+    return {
+      roomId: resolvedRoom,
+      name,
+      topic,
+      canonicalAlias,
+      altAliases: [], // Would need separate query
+      memberCount,
+    };
+  } finally {
+    if (stopOnDone) client.stop();
+  }
+}

extensions/matrix/src/matrix/actions/summary.ts

@@ -0,0 +1,77 @@
+import type { MatrixClient } from "matrix-bot-sdk";
+
+import {
+  EventType,
+  type MatrixMessageSummary,
+  type MatrixRawEvent,
+  type RoomMessageEventContent,
+  type RoomPinnedEventsEventContent,
+} from "./types.js";
+
+export function summarizeMatrixRawEvent(event: MatrixRawEvent): MatrixMessageSummary {
+  const content = event.content as RoomMessageEventContent;
+  const relates = content["m.relates_to"];
+  let relType: string | undefined;
+  let eventId: string | undefined;
+  if (relates) {
+    if ("rel_type" in relates) {
+      relType = relates.rel_type;
+      eventId = relates.event_id;
+    } else if ("m.in_reply_to" in relates) {
+      eventId = relates["m.in_reply_to"]?.event_id;
+    }
+  }
+  const relatesTo =
+    relType || eventId
+      ? {
+          relType,
+          eventId,
+        }
+      : undefined;
+  return {
+    eventId: event.event_id,
+    sender: event.sender,
+    body: content.body,
+    msgtype: content.msgtype,
+    timestamp: event.origin_server_ts,
+    relatesTo,
+  };
+}
+
+export async function readPinnedEvents(
+  client: MatrixClient,
+  roomId: string,
+): Promise<string[]> {
+  try {
+    const content = (await client.getRoomStateEvent(
+      roomId,
+      EventType.RoomPinnedEvents,
+      "",
+    )) as RoomPinnedEventsEventContent;
+    const pinned = content.pinned;
+    return pinned.filter((id) => id.trim().length > 0);
+  } catch (err: unknown) {
+    const errObj = err as { statusCode?: number; body?: { errcode?: string } };
+    const httpStatus = errObj.statusCode;
+    const errcode = errObj.body?.errcode;
+    if (httpStatus === 404 || errcode === "M_NOT_FOUND") {
+      return [];
+    }
+    throw err;
+  }
+}
+
+export async function fetchEventSummary(
+  client: MatrixClient,
+  roomId: string,
+  eventId: string,
+): Promise<MatrixMessageSummary | null> {
+  try {
+    const raw = (await client.getEvent(roomId, eventId)) as MatrixRawEvent;
+    if (raw.unsigned?.redacted_because) return null;
+    return summarizeMatrixRawEvent(raw);
+  } catch {
+    // Event not found, redacted, or inaccessible - return null
+    return null;
+  }
+}

extensions/matrix/src/matrix/actions/types.ts

@@ -0,0 +1,84 @@
+import type { MatrixClient } from "matrix-bot-sdk";
+
+export const MsgType = {
+  Text: "m.text",
+} as const;
+
+export const RelationType = {
+  Replace: "m.replace",
+  Annotation: "m.annotation",
+} as const;
+
+export const EventType = {
+  RoomMessage: "m.room.message",
+  RoomPinnedEvents: "m.room.pinned_events",
+  RoomTopic: "m.room.topic",
+  Reaction: "m.reaction",
+} as const;
+
+export type RoomMessageEventContent = {
+  msgtype: string;
+  body: string;
+  "m.new_content"?: RoomMessageEventContent;
+  "m.relates_to"?: {
+    rel_type?: string;
+    event_id?: string;
+    "m.in_reply_to"?: { event_id?: string };
+  };
+};
+
+export type ReactionEventContent = {
+  "m.relates_to": {
+    rel_type: string;
+    event_id: string;
+    key: string;
+  };
+};
+
+export type RoomPinnedEventsEventContent = {
+  pinned: string[];
+};
+
+export type RoomTopicEventContent = {
+  topic?: string;
+};
+
+export type MatrixRawEvent = {
+  event_id: string;
+  sender: string;
+  type: string;
+  origin_server_ts: number;
+  content: Record<string, unknown>;
+  unsigned?: {
+    redacted_because?: unknown;
+  };
+};
+
+export type MatrixActionClientOpts = {
+  client?: MatrixClient;
+  timeoutMs?: number;
+};
+
+export type MatrixMessageSummary = {
+  eventId?: string;
+  sender?: string;
+  body?: string;
+  msgtype?: string;
+  timestamp?: number;
+  relatesTo?: {
+    relType?: string;
+    eventId?: string;
+    key?: string;
+  };
+};
+
+export type MatrixReactionSummary = {
+  key: string;
+  count: number;
+  users: string[];
+};
+
+export type MatrixActionClient = {
+  client: MatrixClient;
+  stopOnDone: boolean;
+};

extensions/matrix/src/matrix/client.ts

@@ -1,645 +1,9 @@
-import crypto from "node:crypto";
-import fs from "node:fs";
-import os from "node:os";
-import path from "node:path";
-
-import {
-  ConsoleLogger,
-  LogService,
-  MatrixClient,
-  SimpleFsStorageProvider,
-  RustSdkCryptoStorageProvider,
-} from "matrix-bot-sdk";
-import type { IStorageProvider, ICryptoStorageProvider } from "matrix-bot-sdk";
-
-import type { CoreConfig } from "../types.js";
-import { getMatrixRuntime } from "../runtime.js";
-
-export type MatrixResolvedConfig = {
-  homeserver: string;
-  userId: string;
-  accessToken?: string;
-  password?: string;
-  deviceName?: string;
-  initialSyncLimit?: number;
-  encryption?: boolean;
-};
-
-/**
- * Authenticated Matrix configuration.
- * Note: deviceId is NOT included here because it's implicit in the accessToken.
- * The crypto storage assumes the device ID (and thus access token) does not change
- * between restarts. If the access token becomes invalid or crypto storage is lost,
- * both will need to be recreated together.
- */
-export type MatrixAuth = {
-  homeserver: string;
-  userId: string;
-  accessToken: string;
-  deviceName?: string;
-  initialSyncLimit?: number;
-  encryption?: boolean;
-};
-
-type SharedMatrixClientState = {
-  client: MatrixClient;
-  key: string;
-  started: boolean;
-  cryptoReady: boolean;
-};
-
-let sharedClientState: SharedMatrixClientState | null = null;
-let sharedClientPromise: Promise<SharedMatrixClientState> | null = null;
-let sharedClientStartPromise: Promise<void> | null = null;
-
-export function isBunRuntime(): boolean {
-  const versions = process.versions as { bun?: string };
-  return typeof versions.bun === "string";
-}
-
-let matrixSdkLoggingConfigured = false;
-const matrixSdkBaseLogger = new ConsoleLogger();
-
-function shouldSuppressMatrixHttpNotFound(
-  module: string,
-  messageOrObject: unknown[],
-): boolean {
-  if (module !== "MatrixHttpClient") return false;
-  return messageOrObject.some((entry) => {
-    if (!entry || typeof entry !== "object") return false;
-    return (entry as { errcode?: string }).errcode === "M_NOT_FOUND";
-  });
-}
-
-function ensureMatrixSdkLoggingConfigured(): void {
-  if (matrixSdkLoggingConfigured) return;
-  matrixSdkLoggingConfigured = true;
-
-  LogService.setLogger({
-    trace: (module, ...messageOrObject) =>
-      matrixSdkBaseLogger.trace(module, ...messageOrObject),
-    debug: (module, ...messageOrObject) =>
-      matrixSdkBaseLogger.debug(module, ...messageOrObject),
-    info: (module, ...messageOrObject) =>
-      matrixSdkBaseLogger.info(module, ...messageOrObject),
-    warn: (module, ...messageOrObject) =>
-      matrixSdkBaseLogger.warn(module, ...messageOrObject),
-    error: (module, ...messageOrObject) => {
-      if (shouldSuppressMatrixHttpNotFound(module, messageOrObject)) return;
-      matrixSdkBaseLogger.error(module, ...messageOrObject);
-    },
-  });
-}
-
-function clean(value?: string): string {
-  return value?.trim() ?? "";
-}
-
-const DEFAULT_ACCOUNT_KEY = "default";
-const STORAGE_META_FILENAME = "storage-meta.json";
-
-type MatrixStoragePaths = {
-  rootDir: string;
-  storagePath: string;
-  cryptoPath: string;
-  metaPath: string;
-  accountKey: string;
-  tokenHash: string;
-};
-
-function sanitizePathSegment(value: string): string {
-  const cleaned = value
-    .trim()
-    .toLowerCase()
-    .replace(/[^a-z0-9._-]+/g, "_")
-    .replace(/^_+|_+$/g, "");
-  return cleaned || "unknown";
-}
-
-function resolveHomeserverKey(homeserver: string): string {
-  try {
-    const url = new URL(homeserver);
-    if (url.host) return sanitizePathSegment(url.host);
-  } catch {
-    // fall through
-  }
-  return sanitizePathSegment(homeserver);
-}
-
-function hashAccessToken(accessToken: string): string {
-  return crypto.createHash("sha256").update(accessToken).digest("hex").slice(0, 16);
-}
-
-function resolveLegacyStoragePaths(env: NodeJS.ProcessEnv = process.env): {
-  storagePath: string;
-  cryptoPath: string;
-} {
-  const stateDir = getMatrixRuntime().state.resolveStateDir(env, os.homedir);
-  return {
-    storagePath: path.join(stateDir, "matrix", "bot-storage.json"),
-    cryptoPath: path.join(stateDir, "matrix", "crypto"),
-  };
-}
-
-function resolveMatrixStoragePaths(params: {
-  homeserver: string;
-  userId: string;
-  accessToken: string;
-  accountId?: string | null;
-  env?: NodeJS.ProcessEnv;
-}): MatrixStoragePaths {
-  const env = params.env ?? process.env;
-  const stateDir = getMatrixRuntime().state.resolveStateDir(env, os.homedir);
-  const accountKey = sanitizePathSegment(params.accountId ?? DEFAULT_ACCOUNT_KEY);
-  const userKey = sanitizePathSegment(params.userId);
-  const serverKey = resolveHomeserverKey(params.homeserver);
-  const tokenHash = hashAccessToken(params.accessToken);
-  const rootDir = path.join(
-    stateDir,
-    "matrix",
-    "accounts",
-    accountKey,
-    `${serverKey}__${userKey}`,
-    tokenHash,
-  );
-  return {
-    rootDir,
-    storagePath: path.join(rootDir, "bot-storage.json"),
-    cryptoPath: path.join(rootDir, "crypto"),
-    metaPath: path.join(rootDir, STORAGE_META_FILENAME),
-    accountKey,
-    tokenHash,
-  };
-}
-
-function maybeMigrateLegacyStorage(params: {
-  storagePaths: MatrixStoragePaths;
-  env?: NodeJS.ProcessEnv;
-}): void {
-  const legacy = resolveLegacyStoragePaths(params.env);
-  const hasLegacyStorage = fs.existsSync(legacy.storagePath);
-  const hasLegacyCrypto = fs.existsSync(legacy.cryptoPath);
-  const hasNewStorage =
-    fs.existsSync(params.storagePaths.storagePath) ||
-    fs.existsSync(params.storagePaths.cryptoPath);
-
-  if (!hasLegacyStorage && !hasLegacyCrypto) return;
-  if (hasNewStorage) return;
-
-  fs.mkdirSync(params.storagePaths.rootDir, { recursive: true });
-  if (hasLegacyStorage) {
-    try {
-      fs.renameSync(legacy.storagePath, params.storagePaths.storagePath);
-    } catch {
-      // Ignore migration failures; new store will be created.
-    }
-  }
-  if (hasLegacyCrypto) {
-    try {
-      fs.renameSync(legacy.cryptoPath, params.storagePaths.cryptoPath);
-    } catch {
-      // Ignore migration failures; new store will be created.
-    }
-  }
-}
-
-function writeStorageMeta(params: {
-  storagePaths: MatrixStoragePaths;
-  homeserver: string;
-  userId: string;
-  accountId?: string | null;
-}): void {
-  try {
-    const payload = {
-      homeserver: params.homeserver,
-      userId: params.userId,
-      accountId: params.accountId ?? DEFAULT_ACCOUNT_KEY,
-      accessTokenHash: params.storagePaths.tokenHash,
-      createdAt: new Date().toISOString(),
-    };
-    fs.mkdirSync(params.storagePaths.rootDir, { recursive: true });
-    fs.writeFileSync(
-      params.storagePaths.metaPath,
-      JSON.stringify(payload, null, 2),
-      "utf-8",
-    );
-  } catch {
-    // ignore meta write failures
-  }
-}
-
-function sanitizeUserIdList(input: unknown, label: string): string[] {
-  if (input == null) return [];
-  if (!Array.isArray(input)) {
-    LogService.warn(
-      "MatrixClientLite",
-      `Expected ${label} list to be an array, got ${typeof input}`,
-    );
-    return [];
-  }
-  const filtered = input.filter(
-    (entry): entry is string => typeof entry === "string" && entry.trim().length > 0,
-  );
-  if (filtered.length !== input.length) {
-    LogService.warn(
-      "MatrixClientLite",
-      `Dropping ${input.length - filtered.length} invalid ${label} entries from sync payload`,
-    );
-  }
-  return filtered;
-}
-
-export function resolveMatrixConfig(
-  cfg: CoreConfig = getMatrixRuntime().config.loadConfig() as CoreConfig,
-  env: NodeJS.ProcessEnv = process.env,
-): MatrixResolvedConfig {
-  const matrix = cfg.channels?.matrix ?? {};
-  const homeserver = clean(matrix.homeserver) || clean(env.MATRIX_HOMESERVER);
-  const userId = clean(matrix.userId) || clean(env.MATRIX_USER_ID);
-  const accessToken =
-    clean(matrix.accessToken) || clean(env.MATRIX_ACCESS_TOKEN) || undefined;
-  const password = clean(matrix.password) || clean(env.MATRIX_PASSWORD) || undefined;
-  const deviceName =
-    clean(matrix.deviceName) || clean(env.MATRIX_DEVICE_NAME) || undefined;
-  const initialSyncLimit =
-    typeof matrix.initialSyncLimit === "number"
-      ? Math.max(0, Math.floor(matrix.initialSyncLimit))
-      : undefined;
-  const encryption = matrix.encryption ?? false;
-  return {
-    homeserver,
-    userId,
-    accessToken,
-    password,
-    deviceName,
-    initialSyncLimit,
-    encryption,
-  };
-}
-
-export async function resolveMatrixAuth(params?: {
-  cfg?: CoreConfig;
-  env?: NodeJS.ProcessEnv;
-}): Promise<MatrixAuth> {
-  const cfg = params?.cfg ?? (getMatrixRuntime().config.loadConfig() as CoreConfig);
-  const env = params?.env ?? process.env;
-  const resolved = resolveMatrixConfig(cfg, env);
-  if (!resolved.homeserver) {
-    throw new Error("Matrix homeserver is required (matrix.homeserver)");
-  }
-
-  const {
-    loadMatrixCredentials,
-    saveMatrixCredentials,
-    credentialsMatchConfig,
-    touchMatrixCredentials,
-  } = await import("./credentials.js");
-
-  const cached = loadMatrixCredentials(env);
-  const cachedCredentials =
-    cached &&
-    credentialsMatchConfig(cached, {
-      homeserver: resolved.homeserver,
-      userId: resolved.userId || "",
-    })
-      ? cached
-      : null;
-
-  // If we have an access token, we can fetch userId via whoami if not provided
-  if (resolved.accessToken) {
-    let userId = resolved.userId;
-    if (!userId) {
-      // Fetch userId from access token via whoami
-      ensureMatrixSdkLoggingConfigured();
-      const tempClient = new MatrixClient(resolved.homeserver, resolved.accessToken);
-      const whoami = await tempClient.getUserId();
-      userId = whoami;
-      // Save the credentials with the fetched userId
-      saveMatrixCredentials({
-        homeserver: resolved.homeserver,
-        userId,
-        accessToken: resolved.accessToken,
-      });
-    } else if (cachedCredentials && cachedCredentials.accessToken === resolved.accessToken) {
-      touchMatrixCredentials(env);
-    }
-    return {
-      homeserver: resolved.homeserver,
-      userId,
-      accessToken: resolved.accessToken,
-      deviceName: resolved.deviceName,
-      initialSyncLimit: resolved.initialSyncLimit,
-      encryption: resolved.encryption,
-    };
-  }
-
-  if (cachedCredentials) {
-    touchMatrixCredentials(env);
-    return {
-      homeserver: cachedCredentials.homeserver,
-      userId: cachedCredentials.userId,
-      accessToken: cachedCredentials.accessToken,
-      deviceName: resolved.deviceName,
-      initialSyncLimit: resolved.initialSyncLimit,
-      encryption: resolved.encryption,
-    };
-  }
-
-  if (!resolved.userId) {
-    throw new Error(
-      "Matrix userId is required when no access token is configured (matrix.userId)",
-    );
-  }
-
-  if (!resolved.password) {
-    throw new Error(
-      "Matrix password is required when no access token is configured (matrix.password)",
-    );
-  }
-
-  // Login with password using HTTP API
-  const loginResponse = await fetch(`${resolved.homeserver}/_matrix/client/v3/login`, {
-    method: "POST",
-    headers: { "Content-Type": "application/json" },
-    body: JSON.stringify({
-      type: "m.login.password",
-      identifier: { type: "m.id.user", user: resolved.userId },
-      password: resolved.password,
-      initial_device_display_name: resolved.deviceName ?? "Clawdbot Gateway",
-    }),
-  });
-
-  if (!loginResponse.ok) {
-    const errorText = await loginResponse.text();
-    throw new Error(`Matrix login failed: ${errorText}`);
-  }
-
-  const login = (await loginResponse.json()) as {
-    access_token?: string;
-    user_id?: string;
-    device_id?: string;
-  };
-  
-  const accessToken = login.access_token?.trim();
-  if (!accessToken) {
-    throw new Error("Matrix login did not return an access token");
-  }
-
-  const auth: MatrixAuth = {
-    homeserver: resolved.homeserver,
-    userId: login.user_id ?? resolved.userId,
-    accessToken,
-    deviceName: resolved.deviceName,
-    initialSyncLimit: resolved.initialSyncLimit,
-    encryption: resolved.encryption,
-  };
-
-  saveMatrixCredentials({
-    homeserver: auth.homeserver,
-    userId: auth.userId,
-    accessToken: auth.accessToken,
-    deviceId: login.device_id,
-  });
-
-  return auth;
-}
-
-export async function createMatrixClient(params: {
-  homeserver: string;
-  userId: string;
-  accessToken: string;
-  encryption?: boolean;
-  localTimeoutMs?: number;
-  accountId?: string | null;
-}): Promise<MatrixClient> {
-  ensureMatrixSdkLoggingConfigured();
-  const env = process.env;
-
-  // Create storage provider
-  const storagePaths = resolveMatrixStoragePaths({
-    homeserver: params.homeserver,
-    userId: params.userId,
-    accessToken: params.accessToken,
-    accountId: params.accountId,
-    env,
-  });
-  maybeMigrateLegacyStorage({ storagePaths, env });
-  fs.mkdirSync(storagePaths.rootDir, { recursive: true });
-  const storage: IStorageProvider = new SimpleFsStorageProvider(storagePaths.storagePath);
-
-  // Create crypto storage if encryption is enabled
-  let cryptoStorage: ICryptoStorageProvider | undefined;
-  if (params.encryption) {
-    fs.mkdirSync(storagePaths.cryptoPath, { recursive: true });
-
-    try {
-      const { StoreType } = await import("@matrix-org/matrix-sdk-crypto-nodejs");
-      cryptoStorage = new RustSdkCryptoStorageProvider(
-        storagePaths.cryptoPath,
-        StoreType.Sqlite,
-      );
-    } catch (err) {
-      LogService.warn("MatrixClientLite", "Failed to initialize crypto storage, E2EE disabled:", err);
-    }
-  }
-
-  writeStorageMeta({
-    storagePaths,
-    homeserver: params.homeserver,
-    userId: params.userId,
-    accountId: params.accountId,
-  });
-
-  const client = new MatrixClient(
-    params.homeserver,
-    params.accessToken,
-    storage,
-    cryptoStorage,
-  );
-
-  if (client.crypto) {
-    const originalUpdateSyncData = client.crypto.updateSyncData.bind(client.crypto);
-    client.crypto.updateSyncData = async (
-      toDeviceMessages,
-      otkCounts,
-      unusedFallbackKeyAlgs,
-      changedDeviceLists,
-      leftDeviceLists,
-    ) => {
-      const safeChanged = sanitizeUserIdList(changedDeviceLists, "changed device list");
-      const safeLeft = sanitizeUserIdList(leftDeviceLists, "left device list");
-      try {
-        return await originalUpdateSyncData(
-          toDeviceMessages,
-          otkCounts,
-          unusedFallbackKeyAlgs,
-          safeChanged,
-          safeLeft,
-        );
-      } catch (err) {
-        const message = typeof err === "string" ? err : err instanceof Error ? err.message : "";
-        if (message.includes("Expect value to be String")) {
-          LogService.warn(
-            "MatrixClientLite",
-            "Ignoring malformed device list entries during crypto sync",
-            message,
-          );
-          return;
-        }
-        throw err;
-      }
-    };
-  }
-
-  return client;
-}
-
-function buildSharedClientKey(auth: MatrixAuth, accountId?: string | null): string {
-  return [
-    auth.homeserver,
-    auth.userId,
-    auth.accessToken,
-    auth.encryption ? "e2ee" : "plain",
-    accountId ?? DEFAULT_ACCOUNT_KEY,
-  ].join("|");
-}
-
-async function createSharedMatrixClient(params: {
-  auth: MatrixAuth;
-  timeoutMs?: number;
-  accountId?: string | null;
-}): Promise<SharedMatrixClientState> {
-  const client = await createMatrixClient({
-    homeserver: params.auth.homeserver,
-    userId: params.auth.userId,
-    accessToken: params.auth.accessToken,
-    encryption: params.auth.encryption,
-    localTimeoutMs: params.timeoutMs,
-    accountId: params.accountId,
-  });
-  return {
-    client,
-    key: buildSharedClientKey(params.auth, params.accountId),
-    started: false,
-    cryptoReady: false,
-  };
-}
-
-async function ensureSharedClientStarted(params: {
-  state: SharedMatrixClientState;
-  timeoutMs?: number;
-  initialSyncLimit?: number;
-  encryption?: boolean;
-}): Promise<void> {
-  if (params.state.started) return;
-  if (sharedClientStartPromise) {
-    await sharedClientStartPromise;
-    return;
-  }
-  sharedClientStartPromise = (async () => {
-    const client = params.state.client;
-    
-    // Initialize crypto if enabled
-    if (params.encryption && !params.state.cryptoReady) {
-      try {
-        const joinedRooms = await client.getJoinedRooms();
-        if (client.crypto) {
-          await client.crypto.prepare(joinedRooms);
-          params.state.cryptoReady = true;
-        }
-      } catch (err) {
-        LogService.warn("MatrixClientLite", "Failed to prepare crypto:", err);
-      }
-    }
-
-    await client.start();
-    params.state.started = true;
-  })();
-  try {
-    await sharedClientStartPromise;
-  } finally {
-    sharedClientStartPromise = null;
-  }
-}
-
-export async function resolveSharedMatrixClient(
-  params: {
-    cfg?: CoreConfig;
-    env?: NodeJS.ProcessEnv;
-    timeoutMs?: number;
-    auth?: MatrixAuth;
-    startClient?: boolean;
-    accountId?: string | null;
-  } = {},
-): Promise<MatrixClient> {
-  const auth = params.auth ?? (await resolveMatrixAuth({ cfg: params.cfg, env: params.env }));
-  const key = buildSharedClientKey(auth, params.accountId);
-  const shouldStart = params.startClient !== false;
-
-  if (sharedClientState?.key === key) {
-    if (shouldStart) {
-      await ensureSharedClientStarted({
-        state: sharedClientState,
-        timeoutMs: params.timeoutMs,
-        initialSyncLimit: auth.initialSyncLimit,
-        encryption: auth.encryption,
-      });
-    }
-    return sharedClientState.client;
-  }
-
-  if (sharedClientPromise) {
-    const pending = await sharedClientPromise;
-    if (pending.key === key) {
-      if (shouldStart) {
-        await ensureSharedClientStarted({
-          state: pending,
-          timeoutMs: params.timeoutMs,
-          initialSyncLimit: auth.initialSyncLimit,
-          encryption: auth.encryption,
-        });
-      }
-      return pending.client;
-    }
-    pending.client.stop();
-    sharedClientState = null;
-    sharedClientPromise = null;
-  }
-
-  sharedClientPromise = createSharedMatrixClient({
-    auth,
-    timeoutMs: params.timeoutMs,
-    accountId: params.accountId,
-  });
-  try {
-    const created = await sharedClientPromise;
-    sharedClientState = created;
-    if (shouldStart) {
-      await ensureSharedClientStarted({
-        state: created,
-        timeoutMs: params.timeoutMs,
-        initialSyncLimit: auth.initialSyncLimit,
-        encryption: auth.encryption,
-      });
-    }
-    return created.client;
-  } finally {
-    sharedClientPromise = null;
-  }
-}
-
-export async function waitForMatrixSync(_params: {
-  client: MatrixClient;
-  timeoutMs?: number;
-  abortSignal?: AbortSignal;
-}): Promise<void> {
-  // matrix-bot-sdk handles sync internally in start()
-  // This is kept for API compatibility but is essentially a no-op now
-}
-
-export function stopSharedClient(): void {
-  if (sharedClientState) {
-    sharedClientState.client.stop();
-    sharedClientState = null;
-  }
-}
+export type { MatrixAuth, MatrixResolvedConfig } from "./client/types.js";
+export { isBunRuntime } from "./client/runtime.js";
+export { resolveMatrixConfig, resolveMatrixAuth } from "./client/config.js";
+export { createMatrixClient } from "./client/create-client.js";
+export {
+  resolveSharedMatrixClient,
+  waitForMatrixSync,
+  stopSharedClient,
+} from "./client/shared.js";

extensions/matrix/src/matrix/client/config.ts

@@ -0,0 +1,165 @@
+import { MatrixClient } from "matrix-bot-sdk";
+
+import type { CoreConfig } from "../types.js";
+import { getMatrixRuntime } from "../../runtime.js";
+import { ensureMatrixSdkLoggingConfigured } from "./logging.js";
+import type { MatrixAuth, MatrixResolvedConfig } from "./types.js";
+
+function clean(value?: string): string {
+  return value?.trim() ?? "";
+}
+
+export function resolveMatrixConfig(
+  cfg: CoreConfig = getMatrixRuntime().config.loadConfig() as CoreConfig,
+  env: NodeJS.ProcessEnv = process.env,
+): MatrixResolvedConfig {
+  const matrix = cfg.channels?.matrix ?? {};
+  const homeserver = clean(matrix.homeserver) || clean(env.MATRIX_HOMESERVER);
+  const userId = clean(matrix.userId) || clean(env.MATRIX_USER_ID);
+  const accessToken =
+    clean(matrix.accessToken) || clean(env.MATRIX_ACCESS_TOKEN) || undefined;
+  const password = clean(matrix.password) || clean(env.MATRIX_PASSWORD) || undefined;
+  const deviceName =
+    clean(matrix.deviceName) || clean(env.MATRIX_DEVICE_NAME) || undefined;
+  const initialSyncLimit =
+    typeof matrix.initialSyncLimit === "number"
+      ? Math.max(0, Math.floor(matrix.initialSyncLimit))
+      : undefined;
+  const encryption = matrix.encryption ?? false;
+  return {
+    homeserver,
+    userId,
+    accessToken,
+    password,
+    deviceName,
+    initialSyncLimit,
+    encryption,
+  };
+}
+
+export async function resolveMatrixAuth(params?: {
+  cfg?: CoreConfig;
+  env?: NodeJS.ProcessEnv;
+}): Promise<MatrixAuth> {
+  const cfg = params?.cfg ?? (getMatrixRuntime().config.loadConfig() as CoreConfig);
+  const env = params?.env ?? process.env;
+  const resolved = resolveMatrixConfig(cfg, env);
+  if (!resolved.homeserver) {
+    throw new Error("Matrix homeserver is required (matrix.homeserver)");
+  }
+
+  const {
+    loadMatrixCredentials,
+    saveMatrixCredentials,
+    credentialsMatchConfig,
+    touchMatrixCredentials,
+  } = await import("./credentials.js");
+
+  const cached = loadMatrixCredentials(env);
+  const cachedCredentials =
+    cached &&
+    credentialsMatchConfig(cached, {
+      homeserver: resolved.homeserver,
+      userId: resolved.userId || "",
+    })
+      ? cached
+      : null;
+
+  // If we have an access token, we can fetch userId via whoami if not provided
+  if (resolved.accessToken) {
+    let userId = resolved.userId;
+    if (!userId) {
+      // Fetch userId from access token via whoami
+      ensureMatrixSdkLoggingConfigured();
+      const tempClient = new MatrixClient(resolved.homeserver, resolved.accessToken);
+      const whoami = await tempClient.getUserId();
+      userId = whoami;
+      // Save the credentials with the fetched userId
+      saveMatrixCredentials({
+        homeserver: resolved.homeserver,
+        userId,
+        accessToken: resolved.accessToken,
+      });
+    } else if (cachedCredentials && cachedCredentials.accessToken === resolved.accessToken) {
+      touchMatrixCredentials(env);
+    }
+    return {
+      homeserver: resolved.homeserver,
+      userId,
+      accessToken: resolved.accessToken,
+      deviceName: resolved.deviceName,
+      initialSyncLimit: resolved.initialSyncLimit,
+      encryption: resolved.encryption,
+    };
+  }
+
+  if (cachedCredentials) {
+    touchMatrixCredentials(env);
+    return {
+      homeserver: cachedCredentials.homeserver,
+      userId: cachedCredentials.userId,
+      accessToken: cachedCredentials.accessToken,
+      deviceName: resolved.deviceName,
+      initialSyncLimit: resolved.initialSyncLimit,
+      encryption: resolved.encryption,
+    };
+  }
+
+  if (!resolved.userId) {
+    throw new Error(
+      "Matrix userId is required when no access token is configured (matrix.userId)",
+    );
+  }
+
+  if (!resolved.password) {
+    throw new Error(
+      "Matrix password is required when no access token is configured (matrix.password)",
+    );
+  }
+
+  // Login with password using HTTP API
+  const loginResponse = await fetch(`${resolved.homeserver}/_matrix/client/v3/login`, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({
+      type: "m.login.password",
+      identifier: { type: "m.id.user", user: resolved.userId },
+      password: resolved.password,
+      initial_device_display_name: resolved.deviceName ?? "Clawdbot Gateway",
+    }),
+  });
+
+  if (!loginResponse.ok) {
+    const errorText = await loginResponse.text();
+    throw new Error(`Matrix login failed: ${errorText}`);
+  }
+
+  const login = (await loginResponse.json()) as {
+    access_token?: string;
+    user_id?: string;
+    device_id?: string;
+  };
+
+  const accessToken = login.access_token?.trim();
+  if (!accessToken) {
+    throw new Error("Matrix login did not return an access token");
+  }
+
+  const auth: MatrixAuth = {
+    homeserver: resolved.homeserver,
+    userId: login.user_id ?? resolved.userId,
+    accessToken,
+    deviceName: resolved.deviceName,
+    initialSyncLimit: resolved.initialSyncLimit,
+    encryption: resolved.encryption,
+  };
+
+  saveMatrixCredentials({
+    homeserver: auth.homeserver,
+    userId: auth.userId,
+    accessToken: auth.accessToken,
+    deviceId: login.device_id,
+  });
+
+  return auth;
+}

extensions/matrix/src/matrix/client/create-client.ts

@@ -0,0 +1,127 @@
+import fs from "node:fs";
+
+import {
+  LogService,
+  MatrixClient,
+  SimpleFsStorageProvider,
+  RustSdkCryptoStorageProvider,
+} from "matrix-bot-sdk";
+import type { IStorageProvider, ICryptoStorageProvider } from "matrix-bot-sdk";
+
+import { ensureMatrixSdkLoggingConfigured } from "./logging.js";
+import {
+  maybeMigrateLegacyStorage,
+  resolveMatrixStoragePaths,
+  writeStorageMeta,
+} from "./storage.js";
+
+function sanitizeUserIdList(input: unknown, label: string): string[] {
+  if (input == null) return [];
+  if (!Array.isArray(input)) {
+    LogService.warn(
+      "MatrixClientLite",
+      `Expected ${label} list to be an array, got ${typeof input}`,
+    );
+    return [];
+  }
+  const filtered = input.filter(
+    (entry): entry is string => typeof entry === "string" && entry.trim().length > 0,
+  );
+  if (filtered.length !== input.length) {
+    LogService.warn(
+      "MatrixClientLite",
+      `Dropping ${input.length - filtered.length} invalid ${label} entries from sync payload`,
+    );
+  }
+  return filtered;
+}
+
+export async function createMatrixClient(params: {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  encryption?: boolean;
+  localTimeoutMs?: number;
+  accountId?: string | null;
+}): Promise<MatrixClient> {
+  ensureMatrixSdkLoggingConfigured();
+  const env = process.env;
+
+  // Create storage provider
+  const storagePaths = resolveMatrixStoragePaths({
+    homeserver: params.homeserver,
+    userId: params.userId,
+    accessToken: params.accessToken,
+    accountId: params.accountId,
+    env,
+  });
+  maybeMigrateLegacyStorage({ storagePaths, env });
+  fs.mkdirSync(storagePaths.rootDir, { recursive: true });
+  const storage: IStorageProvider = new SimpleFsStorageProvider(storagePaths.storagePath);
+
+  // Create crypto storage if encryption is enabled
+  let cryptoStorage: ICryptoStorageProvider | undefined;
+  if (params.encryption) {
+    fs.mkdirSync(storagePaths.cryptoPath, { recursive: true });
+
+    try {
+      const { StoreType } = await import("@matrix-org/matrix-sdk-crypto-nodejs");
+      cryptoStorage = new RustSdkCryptoStorageProvider(
+        storagePaths.cryptoPath,
+        StoreType.Sqlite,
+      );
+    } catch (err) {
+      LogService.warn("MatrixClientLite", "Failed to initialize crypto storage, E2EE disabled:", err);
+    }
+  }
+
+  writeStorageMeta({
+    storagePaths,
+    homeserver: params.homeserver,
+    userId: params.userId,
+    accountId: params.accountId,
+  });
+
+  const client = new MatrixClient(
+    params.homeserver,
+    params.accessToken,
+    storage,
+    cryptoStorage,
+  );
+
+  if (client.crypto) {
+    const originalUpdateSyncData = client.crypto.updateSyncData.bind(client.crypto);
+    client.crypto.updateSyncData = async (
+      toDeviceMessages,
+      otkCounts,
+      unusedFallbackKeyAlgs,
+      changedDeviceLists,
+      leftDeviceLists,
+    ) => {
+      const safeChanged = sanitizeUserIdList(changedDeviceLists, "changed device list");
+      const safeLeft = sanitizeUserIdList(leftDeviceLists, "left device list");
+      try {
+        return await originalUpdateSyncData(
+          toDeviceMessages,
+          otkCounts,
+          unusedFallbackKeyAlgs,
+          safeChanged,
+          safeLeft,
+        );
+      } catch (err) {
+        const message = typeof err === "string" ? err : err instanceof Error ? err.message : "";
+        if (message.includes("Expect value to be String")) {
+          LogService.warn(
+            "MatrixClientLite",
+            "Ignoring malformed device list entries during crypto sync",
+            message,
+          );
+          return;
+        }
+        throw err;
+      }
+    };
+  }
+
+  return client;
+}

extensions/matrix/src/matrix/client/logging.ts

@@ -0,0 +1,35 @@
+import { ConsoleLogger, LogService } from "matrix-bot-sdk";
+
+let matrixSdkLoggingConfigured = false;
+const matrixSdkBaseLogger = new ConsoleLogger();
+
+function shouldSuppressMatrixHttpNotFound(
+  module: string,
+  messageOrObject: unknown[],
+): boolean {
+  if (module !== "MatrixHttpClient") return false;
+  return messageOrObject.some((entry) => {
+    if (!entry || typeof entry !== "object") return false;
+    return (entry as { errcode?: string }).errcode === "M_NOT_FOUND";
+  });
+}
+
+export function ensureMatrixSdkLoggingConfigured(): void {
+  if (matrixSdkLoggingConfigured) return;
+  matrixSdkLoggingConfigured = true;
+
+  LogService.setLogger({
+    trace: (module, ...messageOrObject) =>
+      matrixSdkBaseLogger.trace(module, ...messageOrObject),
+    debug: (module, ...messageOrObject) =>
+      matrixSdkBaseLogger.debug(module, ...messageOrObject),
+    info: (module, ...messageOrObject) =>
+      matrixSdkBaseLogger.info(module, ...messageOrObject),
+    warn: (module, ...messageOrObject) =>
+      matrixSdkBaseLogger.warn(module, ...messageOrObject),
+    error: (module, ...messageOrObject) => {
+      if (shouldSuppressMatrixHttpNotFound(module, messageOrObject)) return;
+      matrixSdkBaseLogger.error(module, ...messageOrObject);
+    },
+  });
+}

extensions/matrix/src/matrix/client/runtime.ts

@@ -0,0 +1,4 @@
+export function isBunRuntime(): boolean {
+  const versions = process.versions as { bun?: string };
+  return typeof versions.bun === "string";
+}

extensions/matrix/src/matrix/client/shared.ts

@@ -0,0 +1,169 @@
+import { LogService } from "matrix-bot-sdk";
+import type { MatrixClient } from "matrix-bot-sdk";
+
+import type { CoreConfig } from "../types.js";
+import { createMatrixClient } from "./create-client.js";
+import { resolveMatrixAuth } from "./config.js";
+import { DEFAULT_ACCOUNT_KEY } from "./storage.js";
+import type { MatrixAuth } from "./types.js";
+
+type SharedMatrixClientState = {
+  client: MatrixClient;
+  key: string;
+  started: boolean;
+  cryptoReady: boolean;
+};
+
+let sharedClientState: SharedMatrixClientState | null = null;
+let sharedClientPromise: Promise<SharedMatrixClientState> | null = null;
+let sharedClientStartPromise: Promise<void> | null = null;
+
+function buildSharedClientKey(auth: MatrixAuth, accountId?: string | null): string {
+  return [
+    auth.homeserver,
+    auth.userId,
+    auth.accessToken,
+    auth.encryption ? "e2ee" : "plain",
+    accountId ?? DEFAULT_ACCOUNT_KEY,
+  ].join("|");
+}
+
+async function createSharedMatrixClient(params: {
+  auth: MatrixAuth;
+  timeoutMs?: number;
+  accountId?: string | null;
+}): Promise<SharedMatrixClientState> {
+  const client = await createMatrixClient({
+    homeserver: params.auth.homeserver,
+    userId: params.auth.userId,
+    accessToken: params.auth.accessToken,
+    encryption: params.auth.encryption,
+    localTimeoutMs: params.timeoutMs,
+    accountId: params.accountId,
+  });
+  return {
+    client,
+    key: buildSharedClientKey(params.auth, params.accountId),
+    started: false,
+    cryptoReady: false,
+  };
+}
+
+async function ensureSharedClientStarted(params: {
+  state: SharedMatrixClientState;
+  timeoutMs?: number;
+  initialSyncLimit?: number;
+  encryption?: boolean;
+}): Promise<void> {
+  if (params.state.started) return;
+  if (sharedClientStartPromise) {
+    await sharedClientStartPromise;
+    return;
+  }
+  sharedClientStartPromise = (async () => {
+    const client = params.state.client;
+
+    // Initialize crypto if enabled
+    if (params.encryption && !params.state.cryptoReady) {
+      try {
+        const joinedRooms = await client.getJoinedRooms();
+        if (client.crypto) {
+          await client.crypto.prepare(joinedRooms);
+          params.state.cryptoReady = true;
+        }
+      } catch (err) {
+        LogService.warn("MatrixClientLite", "Failed to prepare crypto:", err);
+      }
+    }
+
+    await client.start();
+    params.state.started = true;
+  })();
+  try {
+    await sharedClientStartPromise;
+  } finally {
+    sharedClientStartPromise = null;
+  }
+}
+
+export async function resolveSharedMatrixClient(
+  params: {
+    cfg?: CoreConfig;
+    env?: NodeJS.ProcessEnv;
+    timeoutMs?: number;
+    auth?: MatrixAuth;
+    startClient?: boolean;
+    accountId?: string | null;
+  } = {},
+): Promise<MatrixClient> {
+  const auth = params.auth ?? (await resolveMatrixAuth({ cfg: params.cfg, env: params.env }));
+  const key = buildSharedClientKey(auth, params.accountId);
+  const shouldStart = params.startClient !== false;
+
+  if (sharedClientState?.key === key) {
+    if (shouldStart) {
+      await ensureSharedClientStarted({
+        state: sharedClientState,
+        timeoutMs: params.timeoutMs,
+        initialSyncLimit: auth.initialSyncLimit,
+        encryption: auth.encryption,
+      });
+    }
+    return sharedClientState.client;
+  }
+
+  if (sharedClientPromise) {
+    const pending = await sharedClientPromise;
+    if (pending.key === key) {
+      if (shouldStart) {
+        await ensureSharedClientStarted({
+          state: pending,
+          timeoutMs: params.timeoutMs,
+          initialSyncLimit: auth.initialSyncLimit,
+          encryption: auth.encryption,
+        });
+      }
+      return pending.client;
+    }
+    pending.client.stop();
+    sharedClientState = null;
+    sharedClientPromise = null;
+  }
+
+  sharedClientPromise = createSharedMatrixClient({
+    auth,
+    timeoutMs: params.timeoutMs,
+    accountId: params.accountId,
+  });
+  try {
+    const created = await sharedClientPromise;
+    sharedClientState = created;
+    if (shouldStart) {
+      await ensureSharedClientStarted({
+        state: created,
+        timeoutMs: params.timeoutMs,
+        initialSyncLimit: auth.initialSyncLimit,
+        encryption: auth.encryption,
+      });
+    }
+    return created.client;
+  } finally {
+    sharedClientPromise = null;
+  }
+}
+
+export async function waitForMatrixSync(_params: {
+  client: MatrixClient;
+  timeoutMs?: number;
+  abortSignal?: AbortSignal;
+}): Promise<void> {
+  // matrix-bot-sdk handles sync internally in start()
+  // This is kept for API compatibility but is essentially a no-op now
+}
+
+export function stopSharedClient(): void {
+  if (sharedClientState) {
+    sharedClientState.client.stop();
+    sharedClientState = null;
+  }
+}

extensions/matrix/src/matrix/client/storage.ts

@@ -0,0 +1,131 @@
+import crypto from "node:crypto";
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+import { getMatrixRuntime } from "../../runtime.js";
+import type { MatrixStoragePaths } from "./types.js";
+
+export const DEFAULT_ACCOUNT_KEY = "default";
+const STORAGE_META_FILENAME = "storage-meta.json";
+
+function sanitizePathSegment(value: string): string {
+  const cleaned = value
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9._-]+/g, "_")
+    .replace(/^_+|_+$/g, "");
+  return cleaned || "unknown";
+}
+
+function resolveHomeserverKey(homeserver: string): string {
+  try {
+    const url = new URL(homeserver);
+    if (url.host) return sanitizePathSegment(url.host);
+  } catch {
+    // fall through
+  }
+  return sanitizePathSegment(homeserver);
+}
+
+function hashAccessToken(accessToken: string): string {
+  return crypto.createHash("sha256").update(accessToken).digest("hex").slice(0, 16);
+}
+
+function resolveLegacyStoragePaths(env: NodeJS.ProcessEnv = process.env): {
+  storagePath: string;
+  cryptoPath: string;
+} {
+  const stateDir = getMatrixRuntime().state.resolveStateDir(env, os.homedir);
+  return {
+    storagePath: path.join(stateDir, "matrix", "bot-storage.json"),
+    cryptoPath: path.join(stateDir, "matrix", "crypto"),
+  };
+}
+
+export function resolveMatrixStoragePaths(params: {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  accountId?: string | null;
+  env?: NodeJS.ProcessEnv;
+}): MatrixStoragePaths {
+  const env = params.env ?? process.env;
+  const stateDir = getMatrixRuntime().state.resolveStateDir(env, os.homedir);
+  const accountKey = sanitizePathSegment(params.accountId ?? DEFAULT_ACCOUNT_KEY);
+  const userKey = sanitizePathSegment(params.userId);
+  const serverKey = resolveHomeserverKey(params.homeserver);
+  const tokenHash = hashAccessToken(params.accessToken);
+  const rootDir = path.join(
+    stateDir,
+    "matrix",
+    "accounts",
+    accountKey,
+    `${serverKey}__${userKey}`,
+    tokenHash,
+  );
+  return {
+    rootDir,
+    storagePath: path.join(rootDir, "bot-storage.json"),
+    cryptoPath: path.join(rootDir, "crypto"),
+    metaPath: path.join(rootDir, STORAGE_META_FILENAME),
+    accountKey,
+    tokenHash,
+  };
+}
+
+export function maybeMigrateLegacyStorage(params: {
+  storagePaths: MatrixStoragePaths;
+  env?: NodeJS.ProcessEnv;
+}): void {
+  const legacy = resolveLegacyStoragePaths(params.env);
+  const hasLegacyStorage = fs.existsSync(legacy.storagePath);
+  const hasLegacyCrypto = fs.existsSync(legacy.cryptoPath);
+  const hasNewStorage =
+    fs.existsSync(params.storagePaths.storagePath) ||
+    fs.existsSync(params.storagePaths.cryptoPath);
+
+  if (!hasLegacyStorage && !hasLegacyCrypto) return;
+  if (hasNewStorage) return;
+
+  fs.mkdirSync(params.storagePaths.rootDir, { recursive: true });
+  if (hasLegacyStorage) {
+    try {
+      fs.renameSync(legacy.storagePath, params.storagePaths.storagePath);
+    } catch {
+      // Ignore migration failures; new store will be created.
+    }
+  }
+  if (hasLegacyCrypto) {
+    try {
+      fs.renameSync(legacy.cryptoPath, params.storagePaths.cryptoPath);
+    } catch {
+      // Ignore migration failures; new store will be created.
+    }
+  }
+}
+
+export function writeStorageMeta(params: {
+  storagePaths: MatrixStoragePaths;
+  homeserver: string;
+  userId: string;
+  accountId?: string | null;
+}): void {
+  try {
+    const payload = {
+      homeserver: params.homeserver,
+      userId: params.userId,
+      accountId: params.accountId ?? DEFAULT_ACCOUNT_KEY,
+      accessTokenHash: params.storagePaths.tokenHash,
+      createdAt: new Date().toISOString(),
+    };
+    fs.mkdirSync(params.storagePaths.rootDir, { recursive: true });
+    fs.writeFileSync(
+      params.storagePaths.metaPath,
+      JSON.stringify(payload, null, 2),
+      "utf-8",
+    );
+  } catch {
+    // ignore meta write failures
+  }
+}

extensions/matrix/src/matrix/client/types.ts

@@ -0,0 +1,34 @@
+export type MatrixResolvedConfig = {
+  homeserver: string;
+  userId: string;
+  accessToken?: string;
+  password?: string;
+  deviceName?: string;
+  initialSyncLimit?: number;
+  encryption?: boolean;
+};
+
+/**
+ * Authenticated Matrix configuration.
+ * Note: deviceId is NOT included here because it's implicit in the accessToken.
+ * The crypto storage assumes the device ID (and thus access token) does not change
+ * between restarts. If the access token becomes invalid or crypto storage is lost,
+ * both will need to be recreated together.
+ */
+export type MatrixAuth = {
+  homeserver: string;
+  userId: string;
+  accessToken: string;
+  deviceName?: string;
+  initialSyncLimit?: number;
+  encryption?: boolean;
+};
+
+export type MatrixStoragePaths = {
+  rootDir: string;
+  storagePath: string;
+  cryptoPath: string;
+  metaPath: string;
+  accountKey: string;
+  tokenHash: string;
+};

extensions/matrix/src/matrix/monitor/events.ts

@@ -0,0 +1,103 @@
+import type { MatrixClient } from "matrix-bot-sdk";
+import type { PluginRuntime } from "clawdbot/plugin-sdk";
+
+import type { MatrixAuth } from "../client.js";
+import type { MatrixRawEvent } from "./types.js";
+import { EventType } from "./types.js";
+
+export function registerMatrixMonitorEvents(params: {
+  client: MatrixClient;
+  auth: MatrixAuth;
+  logVerboseMessage: (message: string) => void;
+  warnedEncryptedRooms: Set<string>;
+  warnedCryptoMissingRooms: Set<string>;
+  logger: { warn: (meta: Record<string, unknown>, message: string) => void };
+  formatNativeDependencyHint: PluginRuntime["system"]["formatNativeDependencyHint"];
+  onRoomMessage: (roomId: string, event: MatrixRawEvent) => void | Promise<void>;
+}): void {
+  const {
+    client,
+    auth,
+    logVerboseMessage,
+    warnedEncryptedRooms,
+    warnedCryptoMissingRooms,
+    logger,
+    formatNativeDependencyHint,
+    onRoomMessage,
+  } = params;
+
+  client.on("room.message", onRoomMessage);
+
+  client.on("room.encrypted_event", (roomId: string, event: MatrixRawEvent) => {
+    const eventId = event?.event_id ?? "unknown";
+    const eventType = event?.type ?? "unknown";
+    logVerboseMessage(`matrix: encrypted event room=${roomId} type=${eventType} id=${eventId}`);
+  });
+
+  client.on("room.decrypted_event", (roomId: string, event: MatrixRawEvent) => {
+    const eventId = event?.event_id ?? "unknown";
+    const eventType = event?.type ?? "unknown";
+    logVerboseMessage(`matrix: decrypted event room=${roomId} type=${eventType} id=${eventId}`);
+  });
+
+  client.on(
+    "room.failed_decryption",
+    async (roomId: string, event: MatrixRawEvent, error: Error) => {
+      logger.warn(
+        { roomId, eventId: event.event_id, error: error.message },
+        "Failed to decrypt message",
+      );
+      logVerboseMessage(
+        `matrix: failed decrypt room=${roomId} id=${event.event_id ?? "unknown"} error=${error.message}`,
+      );
+    },
+  );
+
+  client.on("room.invite", (roomId: string, event: MatrixRawEvent) => {
+    const eventId = event?.event_id ?? "unknown";
+    const sender = event?.sender ?? "unknown";
+    const isDirect = (event?.content as { is_direct?: boolean } | undefined)?.is_direct === true;
+    logVerboseMessage(
+      `matrix: invite room=${roomId} sender=${sender} direct=${String(isDirect)} id=${eventId}`,
+    );
+  });
+
+  client.on("room.join", (roomId: string, event: MatrixRawEvent) => {
+    const eventId = event?.event_id ?? "unknown";
+    logVerboseMessage(`matrix: join room=${roomId} id=${eventId}`);
+  });
+
+  client.on("room.event", (roomId: string, event: MatrixRawEvent) => {
+    const eventType = event?.type ?? "unknown";
+    if (eventType === EventType.RoomMessageEncrypted) {
+      logVerboseMessage(
+        `matrix: encrypted raw event room=${roomId} id=${event?.event_id ?? "unknown"}`,
+      );
+      if (auth.encryption !== true && !warnedEncryptedRooms.has(roomId)) {
+        warnedEncryptedRooms.add(roomId);
+        const warning =
+          "matrix: encrypted event received without encryption enabled; set channels.matrix.encryption=true and verify the device to decrypt";
+        logger.warn({ roomId }, warning);
+      }
+      if (auth.encryption === true && !client.crypto && !warnedCryptoMissingRooms.has(roomId)) {
+        warnedCryptoMissingRooms.add(roomId);
+        const hint = formatNativeDependencyHint({
+          packageName: "@matrix-org/matrix-sdk-crypto-nodejs",
+          manager: "pnpm",
+          downloadCommand:
+            "node node_modules/@matrix-org/matrix-sdk-crypto-nodejs/download-lib.js",
+        });
+        const warning = `matrix: encryption enabled but crypto is unavailable; ${hint}`;
+        logger.warn({ roomId }, warning);
+      }
+      return;
+    }
+    if (eventType === EventType.RoomMember) {
+      const membership = (event?.content as { membership?: string } | undefined)?.membership;
+      const stateKey = (event as { state_key?: string }).state_key ?? "";
+      logVerboseMessage(
+        `matrix: member event room=${roomId} stateKey=${stateKey} membership=${membership ?? "unknown"}`,
+      );
+    }
+  });
+}

extensions/matrix/src/matrix/monitor/handler.ts

@@ -0,0 +1,604 @@
+import type { LocationMessageEventContent, MatrixClient } from "matrix-bot-sdk";
+
+import {
+  formatAllowlistMatchMeta,
+  type RuntimeEnv,
+} from "clawdbot/plugin-sdk";
+import type { CoreConfig, ReplyToMode } from "../../types.js";
+import {
+  formatPollAsText,
+  isPollStartType,
+  parsePollStartContent,
+  type PollStartContent,
+} from "../poll-types.js";
+import { reactMatrixMessage, sendMessageMatrix, sendReadReceiptMatrix, sendTypingMatrix } from "../send.js";
+import {
+  resolveMatrixAllowListMatch,
+  resolveMatrixAllowListMatches,
+  normalizeAllowListLower,
+} from "./allowlist.js";
+import { downloadMatrixMedia } from "./media.js";
+import { resolveMentions } from "./mentions.js";
+import { deliverMatrixReplies } from "./replies.js";
+import { resolveMatrixRoomConfig } from "./rooms.js";
+import { resolveMatrixThreadRootId, resolveMatrixThreadTarget } from "./threads.js";
+import { resolveMatrixLocation, type MatrixLocationPayload } from "./location.js";
+import type { MatrixRawEvent, RoomMessageEventContent } from "./types.js";
+import { EventType, RelationType } from "./types.js";
+
+export type MatrixMonitorHandlerParams = {
+  client: MatrixClient;
+  core: {
+    logging: {
+      shouldLogVerbose: () => boolean;
+    };
+    channel: typeof import("clawdbot/plugin-sdk")["channel"];
+    system: {
+      enqueueSystemEvent: (
+        text: string,
+        meta: { sessionKey?: string | null; contextKey?: string | null },
+      ) => void;
+    };
+  };
+  cfg: CoreConfig;
+  runtime: RuntimeEnv;
+  logger: {
+    info: (message: string | Record<string, unknown>, ...meta: unknown[]) => void;
+    warn: (meta: Record<string, unknown>, message: string) => void;
+  };
+  logVerboseMessage: (message: string) => void;
+  allowFrom: string[];
+  roomsConfig: CoreConfig["channels"] extends { matrix?: infer MatrixConfig }
+    ? MatrixConfig extends { groups?: infer Groups }
+      ? Groups
+      : Record<string, unknown> | undefined
+    : Record<string, unknown> | undefined;
+  mentionRegexes: ReturnType<
+    typeof import("clawdbot/plugin-sdk")["channel"]["mentions"]["buildMentionRegexes"]
+  >;
+  groupPolicy: "open" | "allowlist" | "disabled";
+  replyToMode: ReplyToMode;
+  threadReplies: "off" | "inbound" | "always";
+  dmEnabled: boolean;
+  dmPolicy: "open" | "pairing" | "allowlist" | "disabled";
+  textLimit: number;
+  mediaMaxBytes: number;
+  startupMs: number;
+  startupGraceMs: number;
+  directTracker: {
+    isDirectMessage: (params: {
+      roomId: string;
+      senderId: string;
+      selfUserId: string;
+    }) => Promise<boolean>;
+  };
+  getRoomInfo: (roomId: string) => Promise<{ name?: string; canonicalAlias?: string; altAliases: string[] }>;
+  getMemberDisplayName: (roomId: string, userId: string) => Promise<string>;
+};
+
+export function createMatrixRoomMessageHandler(params: MatrixMonitorHandlerParams) {
+  const {
+    client,
+    core,
+    cfg,
+    runtime,
+    logger,
+    logVerboseMessage,
+    allowFrom,
+    roomsConfig,
+    mentionRegexes,
+    groupPolicy,
+    replyToMode,
+    threadReplies,
+    dmEnabled,
+    dmPolicy,
+    textLimit,
+    mediaMaxBytes,
+    startupMs,
+    startupGraceMs,
+    directTracker,
+    getRoomInfo,
+    getMemberDisplayName,
+  } = params;
+
+  return async (roomId: string, event: MatrixRawEvent) => {
+    try {
+      const eventType = event.type;
+      if (eventType === EventType.RoomMessageEncrypted) {
+        // Encrypted messages are decrypted automatically by matrix-bot-sdk with crypto enabled
+        return;
+      }
+
+      const isPollEvent = isPollStartType(eventType);
+      const locationContent = event.content as LocationMessageEventContent;
+      const isLocationEvent =
+        eventType === EventType.Location ||
+        (eventType === EventType.RoomMessage &&
+          locationContent.msgtype === EventType.Location);
+      if (eventType !== EventType.RoomMessage && !isPollEvent && !isLocationEvent) return;
+      logVerboseMessage(
+        `matrix: room.message recv room=${roomId} type=${eventType} id=${event.event_id ?? "unknown"}`,
+      );
+      if (event.unsigned?.redacted_because) return;
+      const senderId = event.sender;
+      if (!senderId) return;
+      const selfUserId = await client.getUserId();
+      if (senderId === selfUserId) return;
+      const eventTs = event.origin_server_ts;
+      const eventAge = event.unsigned?.age;
+      if (typeof eventTs === "number" && eventTs < startupMs - startupGraceMs) {
+        return;
+      }
+      if (
+        typeof eventTs !== "number" &&
+        typeof eventAge === "number" &&
+        eventAge > startupGraceMs
+      ) {
+        return;
+      }
+
+      const roomInfo = await getRoomInfo(roomId);
+      const roomName = roomInfo.name;
+      const roomAliases = [
+        roomInfo.canonicalAlias ?? "",
+        ...roomInfo.altAliases,
+      ].filter(Boolean);
+
+      let content = event.content as RoomMessageEventContent;
+      if (isPollEvent) {
+        const pollStartContent = event.content as PollStartContent;
+        const pollSummary = parsePollStartContent(pollStartContent);
+        if (pollSummary) {
+          pollSummary.eventId = event.event_id ?? "";
+          pollSummary.roomId = roomId;
+          pollSummary.sender = senderId;
+          const senderDisplayName = await getMemberDisplayName(roomId, senderId);
+          pollSummary.senderName = senderDisplayName;
+          const pollText = formatPollAsText(pollSummary);
+          content = {
+            msgtype: "m.text",
+            body: pollText,
+          } as unknown as RoomMessageEventContent;
+        } else {
+          return;
+        }
+      }
+
+      const locationPayload: MatrixLocationPayload | null = resolveMatrixLocation({
+        eventType,
+        content: content as LocationMessageEventContent,
+      });
+
+      const relates = content["m.relates_to"];
+      if (relates && "rel_type" in relates) {
+        if (relates.rel_type === RelationType.Replace) return;
+      }
+
+      const isDirectMessage = await directTracker.isDirectMessage({
+        roomId,
+        senderId,
+        selfUserId,
+      });
+      const isRoom = !isDirectMessage;
+
+      if (isRoom && groupPolicy === "disabled") return;
+
+      const roomConfigInfo = isRoom
+        ? resolveMatrixRoomConfig({
+            rooms: roomsConfig,
+            roomId,
+            aliases: roomAliases,
+            name: roomName,
+          })
+        : undefined;
+      const roomConfig = roomConfigInfo?.config;
+      const roomMatchMeta = roomConfigInfo
+        ? `matchKey=${roomConfigInfo.matchKey ?? "none"} matchSource=${
+            roomConfigInfo.matchSource ?? "none"
+          }`
+        : "matchKey=none matchSource=none";
+
+      if (isRoom && roomConfig && !roomConfigInfo?.allowed) {
+        logVerboseMessage(`matrix: room disabled room=${roomId} (${roomMatchMeta})`);
+        return;
+      }
+      if (isRoom && groupPolicy === "allowlist") {
+        if (!roomConfigInfo?.allowlistConfigured) {
+          logVerboseMessage(`matrix: drop room message (no allowlist, ${roomMatchMeta})`);
+          return;
+        }
+        if (!roomConfig) {
+          logVerboseMessage(`matrix: drop room message (not in allowlist, ${roomMatchMeta})`);
+          return;
+        }
+      }
+
+      const senderName = await getMemberDisplayName(roomId, senderId);
+      const storeAllowFrom = await core.channel.pairing.readAllowFromStore("matrix").catch(() => []);
+      const effectiveAllowFrom = normalizeAllowListLower([...allowFrom, ...storeAllowFrom]);
+      const groupAllowFrom = cfg.channels?.matrix?.groupAllowFrom ?? [];
+      const effectiveGroupAllowFrom = normalizeAllowListLower([
+        ...groupAllowFrom,
+        ...storeAllowFrom,
+      ]);
+      const groupAllowConfigured = effectiveGroupAllowFrom.length > 0;
+
+      if (isDirectMessage) {
+        if (!dmEnabled || dmPolicy === "disabled") return;
+        if (dmPolicy !== "open") {
+          const allowMatch = resolveMatrixAllowListMatch({
+            allowList: effectiveAllowFrom,
+            userId: senderId,
+            userName: senderName,
+          });
+          const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
+          if (!allowMatch.allowed) {
+            if (dmPolicy === "pairing") {
+              const { code, created } = await core.channel.pairing.upsertPairingRequest({
+                channel: "matrix",
+                id: senderId,
+                meta: { name: senderName },
+              });
+              if (created) {
+                logVerboseMessage(
+                  `matrix pairing request sender=${senderId} name=${senderName ?? "unknown"} (${allowMatchMeta})`,
+                );
+                try {
+                  await sendMessageMatrix(
+                    `room:${roomId}`,
+                    [
+                      "Clawdbot: access not configured.",
+                      "",
+                      `Pairing code: ${code}`,
+                      "",
+                      "Ask the bot owner to approve with:",
+                      "clawdbot pairing approve matrix <code>",
+                    ].join("\n"),
+                    { client },
+                  );
+                } catch (err) {
+                  logVerboseMessage(`matrix pairing reply failed for ${senderId}: ${String(err)}`);
+                }
+              }
+            }
+            if (dmPolicy !== "pairing") {
+              logVerboseMessage(
+                `matrix: blocked dm sender ${senderId} (dmPolicy=${dmPolicy}, ${allowMatchMeta})`,
+              );
+            }
+            return;
+          }
+        }
+      }
+
+      const roomUsers = roomConfig?.users ?? [];
+      if (isRoom && roomUsers.length > 0) {
+        const userMatch = resolveMatrixAllowListMatch({
+          allowList: normalizeAllowListLower(roomUsers),
+          userId: senderId,
+          userName: senderName,
+        });
+        if (!userMatch.allowed) {
+          logVerboseMessage(
+            `matrix: blocked sender ${senderId} (room users allowlist, ${roomMatchMeta}, ${formatAllowlistMatchMeta(
+              userMatch,
+            )})`,
+          );
+          return;
+        }
+      }
+      if (isRoom && groupPolicy === "allowlist" && roomUsers.length === 0 && groupAllowConfigured) {
+        const groupAllowMatch = resolveMatrixAllowListMatch({
+          allowList: effectiveGroupAllowFrom,
+          userId: senderId,
+          userName: senderName,
+        });
+        if (!groupAllowMatch.allowed) {
+          logVerboseMessage(
+            `matrix: blocked sender ${senderId} (groupAllowFrom, ${roomMatchMeta}, ${formatAllowlistMatchMeta(
+              groupAllowMatch,
+            )})`,
+          );
+          return;
+        }
+      }
+      if (isRoom) {
+        logVerboseMessage(`matrix: allow room ${roomId} (${roomMatchMeta})`);
+      }
+
+      const rawBody = locationPayload?.text
+        ?? (typeof content.body === "string" ? content.body.trim() : "");
+      let media: {
+        path: string;
+        contentType?: string;
+        placeholder: string;
+      } | null = null;
+      const contentUrl =
+        "url" in content && typeof content.url === "string" ? content.url : undefined;
+      const contentFile =
+        "file" in content && content.file && typeof content.file === "object"
+          ? content.file
+          : undefined;
+      const mediaUrl = contentUrl ?? contentFile?.url;
+      if (!rawBody && !mediaUrl) {
+        return;
+      }
+
+      const contentType =
+        "info" in content && content.info && "mimetype" in content.info
+          ? (content.info as { mimetype?: string }).mimetype
+          : undefined;
+      if (mediaUrl?.startsWith("mxc://")) {
+        try {
+          media = await downloadMatrixMedia({
+            client,
+            mxcUrl: mediaUrl,
+            contentType,
+            maxBytes: mediaMaxBytes,
+            file: contentFile,
+          });
+        } catch (err) {
+          logVerboseMessage(`matrix: media download failed: ${String(err)}`);
+        }
+      }
+
+      const bodyText = rawBody || media?.placeholder || "";
+      if (!bodyText) return;
+
+      const { wasMentioned, hasExplicitMention } = resolveMentions({
+        content,
+        userId: selfUserId,
+        text: bodyText,
+        mentionRegexes,
+      });
+      const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
+        cfg,
+        surface: "matrix",
+      });
+      const useAccessGroups = cfg.commands?.useAccessGroups !== false;
+      const senderAllowedForCommands = resolveMatrixAllowListMatches({
+        allowList: effectiveAllowFrom,
+        userId: senderId,
+        userName: senderName,
+      });
+      const senderAllowedForGroup = groupAllowConfigured
+        ? resolveMatrixAllowListMatches({
+            allowList: effectiveGroupAllowFrom,
+            userId: senderId,
+            userName: senderName,
+          })
+        : false;
+      const senderAllowedForRoomUsers =
+        isRoom && roomUsers.length > 0
+          ? resolveMatrixAllowListMatches({
+              allowList: normalizeAllowListLower(roomUsers),
+              userId: senderId,
+              userName: senderName,
+            })
+          : false;
+      const commandAuthorized = core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
+        useAccessGroups,
+        authorizers: [
+          { configured: effectiveAllowFrom.length > 0, allowed: senderAllowedForCommands },
+          { configured: roomUsers.length > 0, allowed: senderAllowedForRoomUsers },
+          { configured: groupAllowConfigured, allowed: senderAllowedForGroup },
+        ],
+      });
+      if (
+        isRoom &&
+        allowTextCommands &&
+        core.channel.text.hasControlCommand(bodyText, cfg) &&
+        !commandAuthorized
+      ) {
+        logVerboseMessage(`matrix: drop control command from unauthorized sender ${senderId}`);
+        return;
+      }
+      const shouldRequireMention = isRoom
+        ? roomConfig?.autoReply === true
+          ? false
+          : roomConfig?.autoReply === false
+            ? true
+            : typeof roomConfig?.requireMention === "boolean"
+              ? roomConfig?.requireMention
+              : true
+        : false;
+      const shouldBypassMention =
+        allowTextCommands &&
+        isRoom &&
+        shouldRequireMention &&
+        !wasMentioned &&
+        !hasExplicitMention &&
+        commandAuthorized &&
+        core.channel.text.hasControlCommand(bodyText);
+      if (isRoom && shouldRequireMention && !wasMentioned && !shouldBypassMention) {
+        logger.info({ roomId, reason: "no-mention" }, "skipping room message");
+        return;
+      }
+
+      const messageId = event.event_id ?? "";
+      const replyToEventId = content["m.relates_to"]?.["m.in_reply_to"]?.event_id;
+      const threadRootId = resolveMatrixThreadRootId({ event, content });
+      const threadTarget = resolveMatrixThreadTarget({
+        threadReplies,
+        messageId,
+        threadRootId,
+        isThreadRoot: false, // matrix-bot-sdk doesn't have this info readily available
+      });
+
+      const route = core.channel.routing.resolveAgentRoute({
+        cfg,
+        channel: "matrix",
+        peer: {
+          kind: isDirectMessage ? "dm" : "channel",
+          id: isDirectMessage ? senderId : roomId,
+        },
+      });
+      const envelopeFrom = isDirectMessage ? senderName : (roomName ?? roomId);
+      const textWithId = `${bodyText}\n[matrix event id: ${messageId} room: ${roomId}]`;
+      const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
+        agentId: route.agentId,
+      });
+      const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
+      const previousTimestamp = core.channel.session.readSessionUpdatedAt({
+        storePath,
+        sessionKey: route.sessionKey,
+      });
+      const body = core.channel.reply.formatAgentEnvelope({
+        channel: "Matrix",
+        from: envelopeFrom,
+        timestamp: eventTs ?? undefined,
+        previousTimestamp,
+        envelope: envelopeOptions,
+        body: textWithId,
+      });
+
+      const groupSystemPrompt = roomConfig?.systemPrompt?.trim() || undefined;
+      const ctxPayload = core.channel.reply.finalizeInboundContext({
+        Body: body,
+        RawBody: bodyText,
+        CommandBody: bodyText,
+        From: isDirectMessage ? `matrix:${senderId}` : `matrix:channel:${roomId}`,
+        To: `room:${roomId}`,
+        SessionKey: route.sessionKey,
+        AccountId: route.accountId,
+        ChatType: isDirectMessage ? "direct" : "channel",
+        ConversationLabel: envelopeFrom,
+        SenderName: senderName,
+        SenderId: senderId,
+        SenderUsername: senderId.split(":")[0]?.replace(/^@/, ""),
+        GroupSubject: isRoom ? (roomName ?? roomId) : undefined,
+        GroupChannel: isRoom ? (roomInfo.canonicalAlias ?? roomId) : undefined,
+        GroupSystemPrompt: isRoom ? groupSystemPrompt : undefined,
+        Provider: "matrix" as const,
+        Surface: "matrix" as const,
+        WasMentioned: isRoom ? wasMentioned : undefined,
+        MessageSid: messageId,
+        ReplyToId: threadTarget ? undefined : (replyToEventId ?? undefined),
+        MessageThreadId: threadTarget,
+        Timestamp: eventTs ?? undefined,
+        MediaPath: media?.path,
+        MediaType: media?.contentType,
+        MediaUrl: media?.path,
+        ...(locationPayload?.context ?? {}),
+        CommandAuthorized: commandAuthorized,
+        CommandSource: "text" as const,
+        OriginatingChannel: "matrix" as const,
+        OriginatingTo: `room:${roomId}`,
+      });
+
+      void core.channel.session
+        .recordSessionMetaFromInbound({
+          storePath,
+          sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
+          ctx: ctxPayload,
+        })
+        .catch((err) => {
+          logger.warn(
+            { error: String(err), storePath, sessionKey: ctxPayload.SessionKey ?? route.sessionKey },
+            "failed updating session meta",
+          );
+        });
+
+      if (isDirectMessage) {
+        await core.channel.session.updateLastRoute({
+          storePath,
+          sessionKey: route.mainSessionKey,
+          channel: "matrix",
+          to: `room:${roomId}`,
+          accountId: route.accountId,
+          ctx: ctxPayload,
+        });
+      }
+
+      const preview = bodyText.slice(0, 200).replace(/\n/g, "\\n");
+      logVerboseMessage(`matrix inbound: room=${roomId} from=${senderId} preview="${preview}"`);
+
+      const ackReaction = (cfg.messages?.ackReaction ?? "").trim();
+      const ackScope = cfg.messages?.ackReactionScope ?? "group-mentions";
+      const shouldAckReaction = () => {
+        if (!ackReaction) return false;
+        if (ackScope === "all") return true;
+        if (ackScope === "direct") return isDirectMessage;
+        if (ackScope === "group-all") return isRoom;
+        if (ackScope === "group-mentions") {
+          if (!isRoom) return false;
+          if (!shouldRequireMention) return false;
+          return wasMentioned || shouldBypassMention;
+        }
+        return false;
+      };
+      if (shouldAckReaction() && messageId) {
+        reactMatrixMessage(roomId, messageId, ackReaction, client).catch((err) => {
+          logVerboseMessage(`matrix react failed for room ${roomId}: ${String(err)}`);
+        });
+      }
+
+      const replyTarget = ctxPayload.To;
+      if (!replyTarget) {
+        runtime.error?.("matrix: missing reply target");
+        return;
+      }
+
+      if (messageId) {
+        sendReadReceiptMatrix(roomId, messageId, client).catch((err) => {
+          logVerboseMessage(
+            `matrix: read receipt failed room=${roomId} id=${messageId}: ${String(err)}`,
+          );
+        });
+      }
+
+      let didSendReply = false;
+      const { dispatcher, replyOptions, markDispatchIdle } =
+        core.channel.reply.createReplyDispatcherWithTyping({
+          responsePrefix: core.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId)
+            .responsePrefix,
+          humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
+          deliver: async (payload) => {
+            await deliverMatrixReplies({
+              replies: [payload],
+              roomId,
+              client,
+              runtime,
+              textLimit,
+              replyToMode,
+              threadId: threadTarget,
+            });
+            didSendReply = true;
+          },
+          onError: (err, info) => {
+            runtime.error?.(`matrix ${info.kind} reply failed: ${String(err)}`);
+          },
+          onReplyStart: () =>
+            sendTypingMatrix(roomId, true, undefined, client).catch(() => {}),
+          onIdle: () =>
+            sendTypingMatrix(roomId, false, undefined, client).catch(() => {}),
+        });
+
+      const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
+        ctx: ctxPayload,
+        cfg,
+        dispatcher,
+        replyOptions: {
+          ...replyOptions,
+          skillFilter: roomConfig?.skills,
+        },
+      });
+      markDispatchIdle();
+      if (!queuedFinal) return;
+      didSendReply = true;
+      const finalCount = counts.final;
+      logVerboseMessage(
+        `matrix: delivered ${finalCount} reply${finalCount === 1 ? "" : "ies"} to ${replyTarget}`,
+      );
+      if (didSendReply) {
+        const previewText = bodyText.replace(/\s+/g, " ").slice(0, 160);
+        core.system.enqueueSystemEvent(`Matrix message from ${senderName}: ${previewText}`, {
+          sessionKey: route.sessionKey,
+          contextKey: `matrix:message:${roomId}:${messageId || "unknown"}`,
+        });
+      }
+    } catch (err) {
+      runtime.error?.(`matrix handler failed: ${String(err)}`);
+    }
+  };
+}

extensions/matrix/src/matrix/monitor/index.ts

@@ -1,19 +1,8 @@
-import type {
-  EncryptedFile,
-  LocationMessageEventContent,
-  MatrixClient,
-  MessageEventContent,
-} from "matrix-bot-sdk";
 import { format } from "node:util";
 
 import {
-  formatAllowlistMatchMeta,
-  formatLocationText,
   mergeAllowlist,
   summarizeMapping,
-  toLocationContext,
-  type NormalizedLocation,
-  type ReplyPayload,
   type RuntimeEnv,
 } from "clawdbot/plugin-sdk";
 import type { CoreConfig, ReplyToMode } from "../../types.js";
@@ -24,146 +13,14 @@ import {
   resolveSharedMatrixClient,
   stopSharedClient,
 } from "../client.js";
-import {
-  formatPollAsText,
-  isPollStartType,
-  type PollStartContent,
-  parsePollStartContent,
-} from "../poll-types.js";
-import {
-  reactMatrixMessage,
-  sendMessageMatrix,
-  sendReadReceiptMatrix,
-  sendTypingMatrix,
-} from "../send.js";
-import {
-  resolveMatrixAllowListMatch,
-  resolveMatrixAllowListMatches,
-  normalizeAllowListLower,
-} from "./allowlist.js";
 import { registerMatrixAutoJoin } from "./auto-join.js";
 import { createDirectRoomTracker } from "./direct.js";
-import { downloadMatrixMedia } from "./media.js";
-import { resolveMentions } from "./mentions.js";
-import { deliverMatrixReplies } from "./replies.js";
-import { resolveMatrixRoomConfig } from "./rooms.js";
-import { resolveMatrixThreadRootId, resolveMatrixThreadTarget } from "./threads.js";
+import { registerMatrixMonitorEvents } from "./events.js";
+import { createMatrixRoomMessageHandler } from "./handler.js";
+import { createMatrixRoomInfoResolver } from "./room-info.js";
 import { resolveMatrixTargets } from "../../resolve-targets.js";
 import { getMatrixRuntime } from "../../runtime.js";
 
-// Constants that were previously from matrix-js-sdk
-const EventType = {
-  RoomMessage: "m.room.message",
-  RoomMessageEncrypted: "m.room.encrypted",
-  RoomMember: "m.room.member",
-  Location: "m.location",
-} as const;
-
-const RelationType = {
-  Replace: "m.replace",
-} as const;
-
-// Type for raw Matrix events from matrix-bot-sdk
-type MatrixRawEvent = {
-  event_id: string;
-  sender: string;
-  type: string;
-  origin_server_ts: number;
-  content: Record<string, unknown>;
-  unsigned?: {
-    age?: number;
-    redacted_because?: unknown;
-  };
-};
-
-type RoomMessageEventContent = MessageEventContent & {
-  url?: string;
-  file?: EncryptedFile;
-  info?: {
-    mimetype?: string;
-  };
-  "m.relates_to"?: {
-    rel_type?: string;
-    event_id?: string;
-    "m.in_reply_to"?: { event_id?: string };
-  };
-};
-
-type MatrixLocationPayload = {
-  text: string;
-  context: ReturnType<typeof toLocationContext>;
-};
-
-type GeoUriParams = {
-  latitude: number;
-  longitude: number;
-  accuracy?: number;
-};
-
-function parseGeoUri(value: string): GeoUriParams | null {
-  const trimmed = value.trim();
-  if (!trimmed) return null;
-  if (!trimmed.toLowerCase().startsWith("geo:")) return null;
-  const payload = trimmed.slice(4);
-  const [coordsPart, ...paramParts] = payload.split(";");
-  const coords = coordsPart.split(",");
-  if (coords.length < 2) return null;
-  const latitude = Number.parseFloat(coords[0] ?? "");
-  const longitude = Number.parseFloat(coords[1] ?? "");
-  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) return null;
-
-  const params = new Map<string, string>();
-  for (const part of paramParts) {
-    const segment = part.trim();
-    if (!segment) continue;
-    const eqIndex = segment.indexOf("=");
-    const rawKey = eqIndex === -1 ? segment : segment.slice(0, eqIndex);
-    const rawValue = eqIndex === -1 ? "" : segment.slice(eqIndex + 1);
-    const key = rawKey.trim().toLowerCase();
-    if (!key) continue;
-    const valuePart = rawValue.trim();
-    params.set(key, valuePart ? decodeURIComponent(valuePart) : "");
-  }
-
-  const accuracyRaw = params.get("u");
-  const accuracy = accuracyRaw ? Number.parseFloat(accuracyRaw) : undefined;
-
-  return {
-    latitude,
-    longitude,
-    accuracy: Number.isFinite(accuracy) ? accuracy : undefined,
-  };
-}
-
-function resolveMatrixLocation(params: {
-  eventType: string;
-  content: LocationMessageEventContent;
-}): MatrixLocationPayload | null {
-  const { eventType, content } = params;
-  const isLocation =
-    eventType === EventType.Location ||
-    (eventType === EventType.RoomMessage && content.msgtype === EventType.Location);
-  if (!isLocation) return null;
-  const geoUri = typeof content.geo_uri === "string" ? content.geo_uri.trim() : "";
-  if (!geoUri) return null;
-  const parsed = parseGeoUri(geoUri);
-  if (!parsed) return null;
-  const caption = typeof content.body === "string" ? content.body.trim() : "";
-  const location: NormalizedLocation = {
-    latitude: parsed.latitude,
-    longitude: parsed.longitude,
-    accuracy: parsed.accuracy,
-    caption: caption || undefined,
-    source: "pin",
-    isLive: false,
-  };
-
-  return {
-    text: formatLocationText(location),
-    context: toLocationContext(location),
-  };
-}
-
 export type MonitorMatrixOpts = {
   runtime?: RuntimeEnv;
   abortSignal?: AbortSignal;
@@ -343,604 +200,40 @@ export async function monitorMatrixProvider(opts: MonitorMatrixOpts = {}): Promi
   const warnedEncryptedRooms = new Set<string>();
   const warnedCryptoMissingRooms = new Set<string>();
 
-  const roomInfoCache = new Map<
-    string,
-    { name?: string; canonicalAlias?: string; altAliases: string[] }
-  >();
-
-  // Helper to get room info
-  const getRoomInfo = async (roomId: string) => {
-    const cached = roomInfoCache.get(roomId);
-    if (cached) return cached;
-    let name: string | undefined;
-    let canonicalAlias: string | undefined;
-    let altAliases: string[] = [];
-    try {
-      const nameState = await client.getRoomStateEvent(roomId, "m.room.name", "").catch(() => null);
-      name = nameState?.name;
-    } catch { /* ignore */ }
-    try {
-      const aliasState = await client.getRoomStateEvent(roomId, "m.room.canonical_alias", "").catch(() => null);
-      canonicalAlias = aliasState?.alias;
-      altAliases = aliasState?.alt_aliases ?? [];
-    } catch { /* ignore */ }
-    const info = { name, canonicalAlias, altAliases };
-    roomInfoCache.set(roomId, info);
-    return info;
-  };
-
-  // Helper to get member display name
-  const getMemberDisplayName = async (roomId: string, userId: string): Promise<string> => {
-    try {
-      const memberState = await client.getRoomStateEvent(roomId, "m.room.member", userId).catch(() => null);
-      return memberState?.displayname ?? userId;
-    } catch {
-      return userId;
-    }
-  };
-
-  const handleRoomMessage = async (
-    roomId: string,
-    event: MatrixRawEvent,
-  ) => {
-    try {
-      const eventType = event.type;
-      if (eventType === EventType.RoomMessageEncrypted) {
-        // Encrypted messages are decrypted automatically by matrix-bot-sdk with crypto enabled
-        return;
-      }
-
-      const isPollEvent = isPollStartType(eventType);
-      const locationContent = event.content as LocationMessageEventContent;
-      const isLocationEvent =
-        eventType === EventType.Location ||
-        (eventType === EventType.RoomMessage &&
-          locationContent.msgtype === EventType.Location);
-      if (eventType !== EventType.RoomMessage && !isPollEvent && !isLocationEvent) return;
-      logVerboseMessage(
-        `matrix: room.message recv room=${roomId} type=${eventType} id=${event.event_id ?? "unknown"}`,
-      );
-      if (event.unsigned?.redacted_because) return;
-      const senderId = event.sender;
-      if (!senderId) return;
-      const selfUserId = await client.getUserId();
-      if (senderId === selfUserId) return;
-      const eventTs = event.origin_server_ts;
-      const eventAge = event.unsigned?.age;
-      if (typeof eventTs === "number" && eventTs < startupMs - startupGraceMs) {
-        return;
-      }
-      if (
-        typeof eventTs !== "number" &&
-        typeof eventAge === "number" &&
-        eventAge > startupGraceMs
-      ) {
-        return;
-      }
-
-      const roomInfo = await getRoomInfo(roomId);
-      const roomName = roomInfo.name;
-      const roomAliases = [
-        roomInfo.canonicalAlias ?? "",
-        ...roomInfo.altAliases,
-      ].filter(Boolean);
-
-      let content = event.content as RoomMessageEventContent;
-      if (isPollEvent) {
-        const pollStartContent = event.content as PollStartContent;
-        const pollSummary = parsePollStartContent(pollStartContent);
-        if (pollSummary) {
-          pollSummary.eventId = event.event_id ?? "";
-          pollSummary.roomId = roomId;
-          pollSummary.sender = senderId;
-          const senderDisplayName = await getMemberDisplayName(roomId, senderId);
-          pollSummary.senderName = senderDisplayName;
-          const pollText = formatPollAsText(pollSummary);
-          content = {
-            msgtype: "m.text",
-            body: pollText,
-          } as unknown as RoomMessageEventContent;
-        } else {
-          return;
-        }
-      }
-
-      const locationPayload = resolveMatrixLocation({
-        eventType,
-        content: content as LocationMessageEventContent,
-      });
-
-      const relates = content["m.relates_to"];
-      if (relates && "rel_type" in relates) {
-        if (relates.rel_type === RelationType.Replace) return;
-      }
-
-      const isDirectMessage = await directTracker.isDirectMessage({
-        roomId,
-        senderId,
-        selfUserId,
-      });
-      const isRoom = !isDirectMessage;
-
-      if (isRoom && groupPolicy === "disabled") return;
-
-      const roomConfigInfo = isRoom
-        ? resolveMatrixRoomConfig({
-            rooms: roomsConfig,
-            roomId,
-            aliases: roomAliases,
-            name: roomName,
-          })
-        : undefined;
-      const roomConfig = roomConfigInfo?.config;
-      const roomMatchMeta = roomConfigInfo
-        ? `matchKey=${roomConfigInfo.matchKey ?? "none"} matchSource=${
-            roomConfigInfo.matchSource ?? "none"
-          }`
-        : "matchKey=none matchSource=none";
-
-      if (isRoom && roomConfig && !roomConfigInfo?.allowed) {
-        logVerboseMessage(`matrix: room disabled room=${roomId} (${roomMatchMeta})`);
-        return;
-      }
-      if (isRoom && groupPolicy === "allowlist") {
-        if (!roomConfigInfo?.allowlistConfigured) {
-          logVerboseMessage(`matrix: drop room message (no allowlist, ${roomMatchMeta})`);
-          return;
-        }
-        if (!roomConfig) {
-          logVerboseMessage(`matrix: drop room message (not in allowlist, ${roomMatchMeta})`);
-          return;
-        }
-      }
-
-      const senderName = await getMemberDisplayName(roomId, senderId);
-      const storeAllowFrom = await core.channel.pairing.readAllowFromStore("matrix").catch(() => []);
-      const effectiveAllowFrom = normalizeAllowListLower([...allowFrom, ...storeAllowFrom]);
-      const groupAllowFrom = cfg.channels?.matrix?.groupAllowFrom ?? [];
-      const effectiveGroupAllowFrom = normalizeAllowListLower([
-        ...groupAllowFrom,
-        ...storeAllowFrom,
-      ]);
-      const groupAllowConfigured = effectiveGroupAllowFrom.length > 0;
-
-      if (isDirectMessage) {
-        if (!dmEnabled || dmPolicy === "disabled") return;
-        if (dmPolicy !== "open") {
-          const allowMatch = resolveMatrixAllowListMatch({
-            allowList: effectiveAllowFrom,
-            userId: senderId,
-            userName: senderName,
-          });
-          const allowMatchMeta = formatAllowlistMatchMeta(allowMatch);
-          if (!allowMatch.allowed) {
-            if (dmPolicy === "pairing") {
-              const { code, created } = await core.channel.pairing.upsertPairingRequest({
-                channel: "matrix",
-                id: senderId,
-                meta: { name: senderName },
-              });
-              if (created) {
-                logVerboseMessage(
-                  `matrix pairing request sender=${senderId} name=${senderName ?? "unknown"} (${allowMatchMeta})`,
-                );
-                try {
-                  await sendMessageMatrix(
-                    `room:${roomId}`,
-                    [
-                      "Clawdbot: access not configured.",
-                      "",
-                      `Pairing code: ${code}`,
-                      "",
-                      "Ask the bot owner to approve with:",
-                      "clawdbot pairing approve matrix <code>",
-                    ].join("\n"),
-                    { client },
-                  );
-                } catch (err) {
-                  logVerboseMessage(`matrix pairing reply failed for ${senderId}: ${String(err)}`);
-                }
-              }
-            }
-            if (dmPolicy !== "pairing") {
-              logVerboseMessage(
-                `matrix: blocked dm sender ${senderId} (dmPolicy=${dmPolicy}, ${allowMatchMeta})`,
-              );
-            }
-            return;
-          }
-        }
-      }
-
-      const roomUsers = roomConfig?.users ?? [];
-      if (isRoom && roomUsers.length > 0) {
-        const userMatch = resolveMatrixAllowListMatch({
-          allowList: normalizeAllowListLower(roomUsers),
-          userId: senderId,
-          userName: senderName,
-        });
-        if (!userMatch.allowed) {
-          logVerboseMessage(
-            `matrix: blocked sender ${senderId} (room users allowlist, ${roomMatchMeta}, ${formatAllowlistMatchMeta(
-              userMatch,
-            )})`,
-          );
-          return;
-        }
-      }
-      if (isRoom && groupPolicy === "allowlist" && roomUsers.length === 0 && groupAllowConfigured) {
-        const groupAllowMatch = resolveMatrixAllowListMatch({
-          allowList: effectiveGroupAllowFrom,
-          userId: senderId,
-          userName: senderName,
-        });
-        if (!groupAllowMatch.allowed) {
-          logVerboseMessage(
-            `matrix: blocked sender ${senderId} (groupAllowFrom, ${roomMatchMeta}, ${formatAllowlistMatchMeta(
-              groupAllowMatch,
-            )})`,
-          );
-          return;
-        }
-      }
-      if (isRoom) {
-        logVerboseMessage(`matrix: allow room ${roomId} (${roomMatchMeta})`);
-      }
-
-      const rawBody = locationPayload?.text
-        ?? (typeof content.body === "string" ? content.body.trim() : "");
-      let media: {
-        path: string;
-        contentType?: string;
-        placeholder: string;
-      } | null = null;
-      const contentUrl =
-        "url" in content && typeof content.url === "string" ? content.url : undefined;
-      const contentFile =
-        "file" in content && content.file && typeof content.file === "object"
-          ? (content.file as EncryptedFile)
-          : undefined;
-      const mediaUrl = contentUrl ?? contentFile?.url;
-      if (!rawBody && !mediaUrl) {
-        return;
-      }
-
-      const contentType =
-        "info" in content && content.info && "mimetype" in content.info
-          ? (content.info as { mimetype?: string }).mimetype
-          : undefined;
-      if (mediaUrl?.startsWith("mxc://")) {
-        try {
-          media = await downloadMatrixMedia({
-            client,
-            mxcUrl: mediaUrl,
-            contentType,
-            maxBytes: mediaMaxBytes,
-            file: contentFile,
-          });
-        } catch (err) {
-          logVerboseMessage(`matrix: media download failed: ${String(err)}`);
-        }
-      }
-
-      const bodyText = rawBody || media?.placeholder || "";
-      if (!bodyText) return;
-
-      const { wasMentioned, hasExplicitMention } = resolveMentions({
-        content,
-        userId: selfUserId,
-        text: bodyText,
-        mentionRegexes,
-      });
-      const allowTextCommands = core.channel.commands.shouldHandleTextCommands({
-        cfg,
-        surface: "matrix",
-      });
-      const useAccessGroups = cfg.commands?.useAccessGroups !== false;
-      const senderAllowedForCommands = resolveMatrixAllowListMatches({
-        allowList: effectiveAllowFrom,
-        userId: senderId,
-        userName: senderName,
-      });
-      const senderAllowedForGroup = groupAllowConfigured
-        ? resolveMatrixAllowListMatches({
-            allowList: effectiveGroupAllowFrom,
-            userId: senderId,
-            userName: senderName,
-          })
-        : false;
-      const senderAllowedForRoomUsers =
-        isRoom && roomUsers.length > 0
-          ? resolveMatrixAllowListMatches({
-              allowList: normalizeAllowListLower(roomUsers),
-              userId: senderId,
-              userName: senderName,
-            })
-          : false;
-      const commandAuthorized = core.channel.commands.resolveCommandAuthorizedFromAuthorizers({
-        useAccessGroups,
-        authorizers: [
-          { configured: effectiveAllowFrom.length > 0, allowed: senderAllowedForCommands },
-          { configured: roomUsers.length > 0, allowed: senderAllowedForRoomUsers },
-          { configured: groupAllowConfigured, allowed: senderAllowedForGroup },
-        ],
-      });
-      if (
-        isRoom &&
-        allowTextCommands &&
-        core.channel.text.hasControlCommand(bodyText, cfg) &&
-        !commandAuthorized
-      ) {
-        logVerboseMessage(`matrix: drop control command from unauthorized sender ${senderId}`);
-        return;
-      }
-      const shouldRequireMention = isRoom
-        ? roomConfig?.autoReply === true
-          ? false
-          : roomConfig?.autoReply === false
-            ? true
-            : typeof roomConfig?.requireMention === "boolean"
-              ? roomConfig?.requireMention
-              : true
-        : false;
-      const shouldBypassMention =
-        allowTextCommands &&
-        isRoom &&
-        shouldRequireMention &&
-        !wasMentioned &&
-        !hasExplicitMention &&
-        commandAuthorized &&
-        core.channel.text.hasControlCommand(bodyText);
-      if (isRoom && shouldRequireMention && !wasMentioned && !shouldBypassMention) {
-        logger.info({ roomId, reason: "no-mention" }, "skipping room message");
-        return;
-      }
-
-      const messageId = event.event_id ?? "";
-      const replyToEventId = content["m.relates_to"]?.["m.in_reply_to"]?.event_id;
-      const threadRootId = resolveMatrixThreadRootId({ event, content });
-	      const threadTarget = resolveMatrixThreadTarget({
-	        threadReplies,
-	        messageId,
-	        threadRootId,
-	        isThreadRoot: false, // matrix-bot-sdk doesn't have this info readily available
-	      });
-
-	      const route = core.channel.routing.resolveAgentRoute({
-	        cfg,
-	        channel: "matrix",
-	        peer: {
-	          kind: isDirectMessage ? "dm" : "channel",
-	          id: isDirectMessage ? senderId : roomId,
-	        },
-	      });
-	      const envelopeFrom = isDirectMessage ? senderName : (roomName ?? roomId);
-	      const textWithId = `${bodyText}\n[matrix event id: ${messageId} room: ${roomId}]`;
-	      const storePath = core.channel.session.resolveStorePath(cfg.session?.store, {
-	        agentId: route.agentId,
-	      });
-	      const envelopeOptions = core.channel.reply.resolveEnvelopeFormatOptions(cfg);
-	      const previousTimestamp = core.channel.session.readSessionUpdatedAt({
-	        storePath,
-	        sessionKey: route.sessionKey,
-	      });
-      const body = core.channel.reply.formatAgentEnvelope({
-        channel: "Matrix",
-        from: envelopeFrom,
-        timestamp: eventTs ?? undefined,
-        previousTimestamp,
-        envelope: envelopeOptions,
-        body: textWithId,
-      });
-
-      const groupSystemPrompt = roomConfig?.systemPrompt?.trim() || undefined;
-      const ctxPayload = core.channel.reply.finalizeInboundContext({
-	        Body: body,
-	        RawBody: bodyText,
-	        CommandBody: bodyText,
-	        From: isDirectMessage ? `matrix:${senderId}` : `matrix:channel:${roomId}`,
-	        To: `room:${roomId}`,
-	        SessionKey: route.sessionKey,
-	        AccountId: route.accountId,
-        ChatType: isDirectMessage ? "direct" : "channel",
-        ConversationLabel: envelopeFrom,
-        SenderName: senderName,
-        SenderId: senderId,
-        SenderUsername: senderId.split(":")[0]?.replace(/^@/, ""),
-        GroupSubject: isRoom ? (roomName ?? roomId) : undefined,
-        GroupChannel: isRoom ? (roomInfo.canonicalAlias ?? roomId) : undefined,
-        GroupSystemPrompt: isRoom ? groupSystemPrompt : undefined,
-        Provider: "matrix" as const,
-        Surface: "matrix" as const,
-        WasMentioned: isRoom ? wasMentioned : undefined,
-        MessageSid: messageId,
-        ReplyToId: threadTarget ? undefined : (replyToEventId ?? undefined),
-        MessageThreadId: threadTarget,
-        Timestamp: eventTs ?? undefined,
-        MediaPath: media?.path,
-        MediaType: media?.contentType,
-        MediaUrl: media?.path,
-        ...(locationPayload?.context ?? {}),
-	        CommandAuthorized: commandAuthorized,
-	        CommandSource: "text" as const,
-	        OriginatingChannel: "matrix" as const,
-	        OriginatingTo: `room:${roomId}`,
-	      });
-
-	      void core.channel.session.recordSessionMetaFromInbound({
-	        storePath,
-	        sessionKey: ctxPayload.SessionKey ?? route.sessionKey,
-	        ctx: ctxPayload,
-      }).catch((err) => {
-        logger.warn(
-          { error: String(err), storePath, sessionKey: ctxPayload.SessionKey ?? route.sessionKey },
-          "failed updating session meta",
-        );
-      });
-
-      if (isDirectMessage) {
-        await core.channel.session.updateLastRoute({
-          storePath,
-          sessionKey: route.mainSessionKey,
-          channel: "matrix",
-          to: `room:${roomId}`,
-          accountId: route.accountId,
-          ctx: ctxPayload,
-        });
-      }
-
-      const preview = bodyText.slice(0, 200).replace(/\n/g, "\\n");
-      logVerboseMessage(`matrix inbound: room=${roomId} from=${senderId} preview="${preview}"`);
-
-      const ackReaction = (cfg.messages?.ackReaction ?? "").trim();
-      const ackScope = cfg.messages?.ackReactionScope ?? "group-mentions";
-      const shouldAckReaction = () => {
-        if (!ackReaction) return false;
-        if (ackScope === "all") return true;
-        if (ackScope === "direct") return isDirectMessage;
-        if (ackScope === "group-all") return isRoom;
-        if (ackScope === "group-mentions") {
-          if (!isRoom) return false;
-          if (!shouldRequireMention) return false;
-          return wasMentioned || shouldBypassMention;
-        }
-        return false;
-      };
-      if (shouldAckReaction() && messageId) {
-        reactMatrixMessage(roomId, messageId, ackReaction, client).catch((err) => {
-          logVerboseMessage(`matrix react failed for room ${roomId}: ${String(err)}`);
-        });
-      }
-
-      const replyTarget = ctxPayload.To;
-      if (!replyTarget) {
-        runtime.error?.("matrix: missing reply target");
-        return;
-      }
-
-      if (messageId) {
-        sendReadReceiptMatrix(roomId, messageId, client).catch((err) => {
-          logVerboseMessage(
-            `matrix: read receipt failed room=${roomId} id=${messageId}: ${String(err)}`,
-          );
-        });
-      }
-
-      let didSendReply = false;
-      const { dispatcher, replyOptions, markDispatchIdle } = core.channel.reply.createReplyDispatcherWithTyping({
-        responsePrefix: core.channel.reply.resolveEffectiveMessagesConfig(cfg, route.agentId).responsePrefix,
-        humanDelay: core.channel.reply.resolveHumanDelayConfig(cfg, route.agentId),
-        deliver: async (payload) => {
-          await deliverMatrixReplies({
-            replies: [payload],
-            roomId,
-            client,
-            runtime,
-            textLimit,
-            replyToMode,
-            threadId: threadTarget,
-          });
-          didSendReply = true;
-        },
-        onError: (err, info) => {
-          runtime.error?.(`matrix ${info.kind} reply failed: ${String(err)}`);
-        },
-        onReplyStart: () => sendTypingMatrix(roomId, true, undefined, client).catch(() => {}),
-        onIdle: () => sendTypingMatrix(roomId, false, undefined, client).catch(() => {}),
-      });
-
-      const { queuedFinal, counts } = await core.channel.reply.dispatchReplyFromConfig({
-        ctx: ctxPayload,
-        cfg,
-        dispatcher,
-        replyOptions: {
-          ...replyOptions,
-          skillFilter: roomConfig?.skills,
-        },
-      });
-      markDispatchIdle();
-      if (!queuedFinal) return;
-      didSendReply = true;
-      const finalCount = counts.final;
-      logVerboseMessage(
-        `matrix: delivered ${finalCount} reply${finalCount === 1 ? "" : "ies"} to ${replyTarget}`,
-      );
-      if (didSendReply) {
-        const preview = bodyText.replace(/\s+/g, " ").slice(0, 160);
-        core.system.enqueueSystemEvent(`Matrix message from ${senderName}: ${preview}`, {
-          sessionKey: route.sessionKey,
-          contextKey: `matrix:message:${roomId}:${messageId || "unknown"}`,
-        });
-      }
-    } catch (err) {
-      runtime.error?.(`matrix handler failed: ${String(err)}`);
-    }
-  };
-
-  // matrix-bot-sdk uses on("room.message", handler)
-  client.on("room.message", handleRoomMessage);
-
-  client.on("room.encrypted_event", (roomId: string, event: MatrixRawEvent) => {
-    const eventId = event?.event_id ?? "unknown";
-    const eventType = event?.type ?? "unknown";
-    logVerboseMessage(`matrix: encrypted event room=${roomId} type=${eventType} id=${eventId}`);
+  const { getRoomInfo, getMemberDisplayName } = createMatrixRoomInfoResolver(client);
+  const handleRoomMessage = createMatrixRoomMessageHandler({
+    client,
+    core,
+    cfg,
+    runtime,
+    logger,
+    logVerboseMessage,
+    allowFrom,
+    roomsConfig,
+    mentionRegexes,
+    groupPolicy,
+    replyToMode,
+    threadReplies,
+    dmEnabled,
+    dmPolicy,
+    textLimit,
+    mediaMaxBytes,
+    startupMs,
+    startupGraceMs,
+    directTracker,
+    getRoomInfo,
+    getMemberDisplayName,
   });
 
-  client.on("room.decrypted_event", (roomId: string, event: MatrixRawEvent) => {
-    const eventId = event?.event_id ?? "unknown";
-    const eventType = event?.type ?? "unknown";
-    logVerboseMessage(`matrix: decrypted event room=${roomId} type=${eventType} id=${eventId}`);
-  });
-
-  // Handle failed E2EE decryption
-  client.on("room.failed_decryption", async (roomId: string, event: MatrixRawEvent, error: Error) => {
-    logger.warn({ roomId, eventId: event.event_id, error: error.message }, "Failed to decrypt message");
-    logVerboseMessage(
-      `matrix: failed decrypt room=${roomId} id=${event.event_id ?? "unknown"} error=${error.message}`,
-    );
-  });
-
-  client.on("room.invite", (roomId: string, event: MatrixRawEvent) => {
-    const eventId = event?.event_id ?? "unknown";
-    const sender = event?.sender ?? "unknown";
-    const isDirect = (event?.content as { is_direct?: boolean } | undefined)?.is_direct === true;
-    logVerboseMessage(
-      `matrix: invite room=${roomId} sender=${sender} direct=${String(isDirect)} id=${eventId}`,
-    );
-  });
-
-  client.on("room.join", (roomId: string, event: MatrixRawEvent) => {
-    const eventId = event?.event_id ?? "unknown";
-    logVerboseMessage(`matrix: join room=${roomId} id=${eventId}`);
-  });
-
-  client.on("room.event", (roomId: string, event: MatrixRawEvent) => {
-    const eventType = event?.type ?? "unknown";
-    if (eventType === EventType.RoomMessageEncrypted) {
-      logVerboseMessage(
-        `matrix: encrypted raw event room=${roomId} id=${event?.event_id ?? "unknown"}`,
-      );
-      if (auth.encryption !== true && !warnedEncryptedRooms.has(roomId)) {
-        warnedEncryptedRooms.add(roomId);
-        const warning =
-          "matrix: encrypted event received without encryption enabled; set channels.matrix.encryption=true and verify the device to decrypt";
-        logger.warn({ roomId }, warning);
-      }
-      if (auth.encryption === true && !client.crypto && !warnedCryptoMissingRooms.has(roomId)) {
-        warnedCryptoMissingRooms.add(roomId);
-        const warning =
-          "matrix: encryption enabled but crypto is unavailable; install @matrix-org/matrix-sdk-crypto-nodejs and restart";
-        logger.warn({ roomId }, warning);
-      }
-      return;
-    }
-    if (eventType === EventType.RoomMember) {
-      const membership = (event?.content as { membership?: string } | undefined)?.membership;
-      const stateKey = (event as { state_key?: string }).state_key ?? "";
-      logVerboseMessage(
-        `matrix: member event room=${roomId} stateKey=${stateKey} membership=${membership ?? "unknown"}`,
-      );
-    }
+  registerMatrixMonitorEvents({
+    client,
+    auth,
+    logVerboseMessage,
+    warnedEncryptedRooms,
+    warnedCryptoMissingRooms,
+    logger,
+    formatNativeDependencyHint: core.system.formatNativeDependencyHint,
+    onRoomMessage: handleRoomMessage,
   });
 
   logVerboseMessage("matrix: starting client");

extensions/matrix/src/matrix/monitor/location.ts

@@ -0,0 +1,83 @@
+import type { LocationMessageEventContent } from "matrix-bot-sdk";
+
+import {
+  formatLocationText,
+  toLocationContext,
+  type NormalizedLocation,
+} from "clawdbot/plugin-sdk";
+import { EventType } from "./types.js";
+
+export type MatrixLocationPayload = {
+  text: string;
+  context: ReturnType<typeof toLocationContext>;
+};
+
+type GeoUriParams = {
+  latitude: number;
+  longitude: number;
+  accuracy?: number;
+};
+
+function parseGeoUri(value: string): GeoUriParams | null {
+  const trimmed = value.trim();
+  if (!trimmed) return null;
+  if (!trimmed.toLowerCase().startsWith("geo:")) return null;
+  const payload = trimmed.slice(4);
+  const [coordsPart, ...paramParts] = payload.split(";");
+  const coords = coordsPart.split(",");
+  if (coords.length < 2) return null;
+  const latitude = Number.parseFloat(coords[0] ?? "");
+  const longitude = Number.parseFloat(coords[1] ?? "");
+  if (!Number.isFinite(latitude) || !Number.isFinite(longitude)) return null;
+
+  const params = new Map<string, string>();
+  for (const part of paramParts) {
+    const segment = part.trim();
+    if (!segment) continue;
+    const eqIndex = segment.indexOf("=");
+    const rawKey = eqIndex === -1 ? segment : segment.slice(0, eqIndex);
+    const rawValue = eqIndex === -1 ? "" : segment.slice(eqIndex + 1);
+    const key = rawKey.trim().toLowerCase();
+    if (!key) continue;
+    const valuePart = rawValue.trim();
+    params.set(key, valuePart ? decodeURIComponent(valuePart) : "");
+  }
+
+  const accuracyRaw = params.get("u");
+  const accuracy = accuracyRaw ? Number.parseFloat(accuracyRaw) : undefined;
+
+  return {
+    latitude,
+    longitude,
+    accuracy: Number.isFinite(accuracy) ? accuracy : undefined,
+  };
+}
+
+export function resolveMatrixLocation(params: {
+  eventType: string;
+  content: LocationMessageEventContent;
+}): MatrixLocationPayload | null {
+  const { eventType, content } = params;
+  const isLocation =
+    eventType === EventType.Location ||
+    (eventType === EventType.RoomMessage && content.msgtype === EventType.Location);
+  if (!isLocation) return null;
+  const geoUri = typeof content.geo_uri === "string" ? content.geo_uri.trim() : "";
+  if (!geoUri) return null;
+  const parsed = parseGeoUri(geoUri);
+  if (!parsed) return null;
+  const caption = typeof content.body === "string" ? content.body.trim() : "";
+  const location: NormalizedLocation = {
+    latitude: parsed.latitude,
+    longitude: parsed.longitude,
+    accuracy: parsed.accuracy,
+    caption: caption || undefined,
+    source: "pin",
+    isLive: false,
+  };
+
+  return {
+    text: formatLocationText(location),
+    context: toLocationContext(location),
+  };
+}

extensions/matrix/src/matrix/monitor/room-info.ts

@@ -0,0 +1,58 @@
+import type { MatrixClient } from "matrix-bot-sdk";
+
+export type MatrixRoomInfo = {
+  name?: string;
+  canonicalAlias?: string;
+  altAliases: string[];
+};
+
+export function createMatrixRoomInfoResolver(client: MatrixClient) {
+  const roomInfoCache = new Map<string, MatrixRoomInfo>();
+
+  const getRoomInfo = async (roomId: string): Promise<MatrixRoomInfo> => {
+    const cached = roomInfoCache.get(roomId);
+    if (cached) return cached;
+    let name: string | undefined;
+    let canonicalAlias: string | undefined;
+    let altAliases: string[] = [];
+    try {
+      const nameState = await client
+        .getRoomStateEvent(roomId, "m.room.name", "")
+        .catch(() => null);
+      name = nameState?.name;
+    } catch {
+      // ignore
+    }
+    try {
+      const aliasState = await client
+        .getRoomStateEvent(roomId, "m.room.canonical_alias", "")
+        .catch(() => null);
+      canonicalAlias = aliasState?.alias;
+      altAliases = aliasState?.alt_aliases ?? [];
+    } catch {
+      // ignore
+    }
+    const info = { name, canonicalAlias, altAliases };
+    roomInfoCache.set(roomId, info);
+    return info;
+  };
+
+  const getMemberDisplayName = async (
+    roomId: string,
+    userId: string,
+  ): Promise<string> => {
+    try {
+      const memberState = await client
+        .getRoomStateEvent(roomId, "m.room.member", userId)
+        .catch(() => null);
+      return memberState?.displayname ?? userId;
+    } catch {
+      return userId;
+    }
+  };
+
+  return {
+    getRoomInfo,
+    getMemberDisplayName,
+  };
+}

extensions/matrix/src/matrix/monitor/types.ts

@@ -0,0 +1,38 @@
+import type { EncryptedFile, MessageEventContent } from "matrix-bot-sdk";
+
+export const EventType = {
+  RoomMessage: "m.room.message",
+  RoomMessageEncrypted: "m.room.encrypted",
+  RoomMember: "m.room.member",
+  Location: "m.location",
+} as const;
+
+export const RelationType = {
+  Replace: "m.replace",
+  Thread: "m.thread",
+} as const;
+
+export type MatrixRawEvent = {
+  event_id: string;
+  sender: string;
+  type: string;
+  origin_server_ts: number;
+  content: Record<string, unknown>;
+  unsigned?: {
+    age?: number;
+    redacted_because?: unknown;
+  };
+};
+
+export type RoomMessageEventContent = MessageEventContent & {
+  url?: string;
+  file?: EncryptedFile;
+  info?: {
+    mimetype?: string;
+  };
+  "m.relates_to"?: {
+    rel_type?: string;
+    event_id?: string;
+    "m.in_reply_to"?: { event_id?: string };
+  };
+};

extensions/matrix/src/matrix/send.ts

@@ -1,504 +1,38 @@
-import type {
-  DimensionalFileInfo,
-  EncryptedFile,
-  FileWithThumbnailInfo,
-  MessageEventContent,
-  TextualMessageEventContent,
-  TimedFileInfo,
-  VideoFileInfo,
-  MatrixClient,
-} from "matrix-bot-sdk";
-import { parseBuffer, type IFileInfo } from "music-metadata";
+import type { MatrixClient } from "matrix-bot-sdk";
 
 import type { PollInput } from "clawdbot/plugin-sdk";
 import { getMatrixRuntime } from "../runtime.js";
-import { getActiveMatrixClient } from "./active-client.js";
-import {
-  createMatrixClient,
-  isBunRuntime,
-  resolveMatrixAuth,
-  resolveSharedMatrixClient,
-} from "./client.js";
-import { markdownToMatrixHtml } from "./format.js";
 import { buildPollStartContent, M_POLL_START } from "./poll-types.js";
-import type { CoreConfig } from "../types.js";
+import { resolveMatrixClient, resolveMediaMaxBytes } from "./send/client.js";
+import {
+  buildReplyRelation,
+  buildTextContent,
+  buildThreadRelation,
+  resolveMatrixMsgType,
+  resolveMatrixVoiceDecision,
+} from "./send/formatting.js";
+import {
+  buildMediaContent,
+  prepareImageInfo,
+  resolveMediaDurationMs,
+  uploadMediaMaybeEncrypted,
+} from "./send/media.js";
+import { normalizeThreadId, resolveMatrixRoomId } from "./send/targets.js";
+import {
+  EventType,
+  MsgType,
+  RelationType,
+  type MatrixOutboundContent,
+  type MatrixSendOpts,
+  type MatrixSendResult,
+  type ReactionEventContent,
+} from "./send/types.js";
 
 const MATRIX_TEXT_LIMIT = 4000;
 const getCore = () => getMatrixRuntime();
 
-// Message types
-const MsgType = {
-  Text: "m.text",
-  Image: "m.image",
-  Audio: "m.audio",
-  Video: "m.video",
-  File: "m.file",
-  Notice: "m.notice",
-} as const;
-
-// Relation types
-const RelationType = {
-  Annotation: "m.annotation",
-  Replace: "m.replace",
-  Thread: "m.thread",
-} as const;
-
-// Event types
-const EventType = {
-  Direct: "m.direct",
-  Reaction: "m.reaction",
-  RoomMessage: "m.room.message",
-} as const;
-
-type MatrixDirectAccountData = Record<string, string[]>;
-
-type MatrixReplyRelation = {
-  "m.in_reply_to": { event_id: string };
-};
-
-type MatrixThreadRelation = {
-  rel_type: typeof RelationType.Thread;
-  event_id: string;
-  is_falling_back?: boolean;
-  "m.in_reply_to"?: { event_id: string };
-};
-
-type MatrixRelation = MatrixReplyRelation | MatrixThreadRelation;
-
-type MatrixReplyMeta = {
-  "m.relates_to"?: MatrixRelation;
-};
-
-type MatrixMediaInfo = FileWithThumbnailInfo | DimensionalFileInfo | TimedFileInfo | VideoFileInfo;
-
-type MatrixTextContent = TextualMessageEventContent & MatrixReplyMeta;
-
-type MatrixMediaContent = MessageEventContent &
-  MatrixReplyMeta & {
-    info?: MatrixMediaInfo;
-    url?: string;
-    file?: EncryptedFile;
-    filename?: string;
-    "org.matrix.msc3245.voice"?: Record<string, never>;
-    "org.matrix.msc1767.audio"?: { duration: number };
-  };
-
-type MatrixOutboundContent = MatrixTextContent | MatrixMediaContent;
-
-type ReactionEventContent = {
-  "m.relates_to": {
-    rel_type: typeof RelationType.Annotation;
-    event_id: string;
-    key: string;
-  };
-};
-
-export type MatrixSendResult = {
-  messageId: string;
-  roomId: string;
-};
-
-export type MatrixSendOpts = {
-  client?: MatrixClient;
-  mediaUrl?: string;
-  replyToId?: string;
-  threadId?: string | number | null;
-  timeoutMs?: number;
-  /** Send audio as voice message (voice bubble) instead of audio file. Defaults to false. */
-  audioAsVoice?: boolean;
-};
-
-function ensureNodeRuntime() {
-  if (isBunRuntime()) {
-    throw new Error("Matrix support requires Node (bun runtime not supported)");
-  }
-}
-
-function resolveMediaMaxBytes(): number | undefined {
-  const cfg = getCore().config.loadConfig() as CoreConfig;
-  if (typeof cfg.channels?.matrix?.mediaMaxMb === "number") {
-    return cfg.channels.matrix.mediaMaxMb * 1024 * 1024;
-  }
-  return undefined;
-}
-
-function normalizeTarget(raw: string): string {
-  const trimmed = raw.trim();
-  if (!trimmed) {
-    throw new Error("Matrix target is required (room:<id> or #alias)");
-  }
-  return trimmed;
-}
-
-function normalizeThreadId(raw?: string | number | null): string | null {
-  if (raw === undefined || raw === null) return null;
-  const trimmed = String(raw).trim();
-  return trimmed ? trimmed : null;
-}
-
-async function resolveDirectRoomId(client: MatrixClient, userId: string): Promise<string> {
-  const trimmed = userId.trim();
-  if (!trimmed.startsWith("@")) {
-    throw new Error(`Matrix user IDs must be fully qualified (got "${trimmed}")`);
-  }
-  // matrix-bot-sdk: use getAccountData to retrieve m.direct
-  try {
-    const directContent = await client.getAccountData(EventType.Direct) as MatrixDirectAccountData | null;
-    const list = Array.isArray(directContent?.[trimmed]) ? directContent[trimmed] : [];
-    if (list.length > 0) return list[0];
-  } catch {
-    // Ignore errors, try fetching from server
-  }
-  throw new Error(
-    `No m.direct room found for ${trimmed}. Open a DM first so Matrix can set m.direct.`,
-  );
-}
-
-export async function resolveMatrixRoomId(
-  client: MatrixClient,
-  raw: string,
-): Promise<string> {
-  const target = normalizeTarget(raw);
-  const lowered = target.toLowerCase();
-  if (lowered.startsWith("matrix:")) {
-    return await resolveMatrixRoomId(client, target.slice("matrix:".length));
-  }
-  if (lowered.startsWith("room:")) {
-    return await resolveMatrixRoomId(client, target.slice("room:".length));
-  }
-  if (lowered.startsWith("channel:")) {
-    return await resolveMatrixRoomId(client, target.slice("channel:".length));
-  }
-  if (lowered.startsWith("user:")) {
-    return await resolveDirectRoomId(client, target.slice("user:".length));
-  }
-  if (target.startsWith("@")) {
-    return await resolveDirectRoomId(client, target);
-  }
-  if (target.startsWith("#")) {
-    const resolved = await client.resolveRoom(target);
-    if (!resolved) {
-      throw new Error(`Matrix alias ${target} could not be resolved`);
-    }
-    return resolved;
-  }
-  return target;
-}
-
-type MatrixMediaMsgType =
-  | typeof MsgType.Image
-  | typeof MsgType.Audio
-  | typeof MsgType.Video
-  | typeof MsgType.File;
-
-type MediaKind = "image" | "audio" | "video" | "document" | "unknown";
-
-function buildMatrixMediaInfo(params: {
-  size: number;
-  mimetype?: string;
-  durationMs?: number;
-  imageInfo?: DimensionalFileInfo;
-}): MatrixMediaInfo | undefined {
-  const base: FileWithThumbnailInfo = {};
-  if (Number.isFinite(params.size)) {
-    base.size = params.size;
-  }
-  if (params.mimetype) {
-    base.mimetype = params.mimetype;
-  }
-  if (params.imageInfo) {
-    const dimensional: DimensionalFileInfo = {
-      ...base,
-      ...params.imageInfo,
-    };
-    if (typeof params.durationMs === "number") {
-      const videoInfo: VideoFileInfo = {
-        ...dimensional,
-        duration: params.durationMs,
-      };
-      return videoInfo;
-    }
-    return dimensional;
-  }
-  if (typeof params.durationMs === "number") {
-    const timedInfo: TimedFileInfo = {
-      ...base,
-      duration: params.durationMs,
-    };
-    return timedInfo;
-  }
-  if (Object.keys(base).length === 0) return undefined;
-  return base;
-}
-
-type MatrixFormattedContent = MessageEventContent & {
-  format?: string;
-  formatted_body?: string;
-};
-
-function buildMediaContent(params: {
-  msgtype: MatrixMediaMsgType;
-  body: string;
-  url?: string;
-  filename?: string;
-  mimetype?: string;
-  size: number;
-  relation?: MatrixRelation;
-  isVoice?: boolean;
-  durationMs?: number;
-  imageInfo?: DimensionalFileInfo;
-  file?: EncryptedFile; // For encrypted media
-}): MatrixMediaContent {
-  const info = buildMatrixMediaInfo({
-    size: params.size,
-    mimetype: params.mimetype,
-    durationMs: params.durationMs,
-    imageInfo: params.imageInfo,
-  });
-  const base: MatrixMediaContent = {
-    msgtype: params.msgtype,
-    body: params.body,
-    filename: params.filename,
-    info: info ?? undefined,
-  };
-  // Encrypted media should only include the "file" payload, not top-level "url".
-  if (!params.file && params.url) {
-    base.url = params.url;
-  }
-  // For encrypted files, add the file object
-  if (params.file) {
-    base.file = params.file;
-  }
-  if (params.isVoice) {
-    base["org.matrix.msc3245.voice"] = {};
-    if (typeof params.durationMs === "number") {
-      base["org.matrix.msc1767.audio"] = {
-        duration: params.durationMs,
-      };
-    }
-  }
-  if (params.relation) {
-    base["m.relates_to"] = params.relation;
-  }
-  applyMatrixFormatting(base, params.body);
-  return base;
-}
-
-function buildTextContent(body: string, relation?: MatrixRelation): MatrixTextContent {
-  const content: MatrixTextContent = relation
-    ? {
-        msgtype: MsgType.Text,
-        body,
-        "m.relates_to": relation,
-      }
-    : {
-        msgtype: MsgType.Text,
-        body,
-      };
-  applyMatrixFormatting(content, body);
-  return content;
-}
-
-function applyMatrixFormatting(content: MatrixFormattedContent, body: string): void {
-  const formatted = markdownToMatrixHtml(body ?? "");
-  if (!formatted) return;
-  content.format = "org.matrix.custom.html";
-  content.formatted_body = formatted;
-}
-
-function buildReplyRelation(replyToId?: string): MatrixReplyRelation | undefined {
-  const trimmed = replyToId?.trim();
-  if (!trimmed) return undefined;
-  return { "m.in_reply_to": { event_id: trimmed } };
-}
-
-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) },
-  };
-}
-
-function resolveMatrixMsgType(
-  contentType?: string,
-  fileName?: string,
-): MatrixMediaMsgType {
-  const kind = getCore().media.mediaKindFromMime(contentType ?? "");
-  switch (kind) {
-    case "image":
-      return MsgType.Image;
-    case "audio":
-      return MsgType.Audio;
-    case "video":
-      return MsgType.Video;
-    default:
-      return MsgType.File;
-  }
-}
-
-function resolveMatrixVoiceDecision(opts: {
-  wantsVoice: boolean;
-  contentType?: string;
-  fileName?: string;
-}): { useVoice: boolean } {
-  if (!opts.wantsVoice) return { useVoice: false };
-  if (getCore().media.isVoiceCompatibleAudio({ contentType: opts.contentType, fileName: opts.fileName })) {
-    return { useVoice: true };
-  }
-  return { useVoice: false };
-}
-
-const THUMBNAIL_MAX_SIDE = 800;
-const THUMBNAIL_QUALITY = 80;
-
-async function prepareImageInfo(params: {
-  buffer: Buffer;
-  client: MatrixClient;
-}): Promise<DimensionalFileInfo | undefined> {
-  const meta = await getCore().media.getImageMetadata(params.buffer).catch(() => null);
-  if (!meta) return undefined;
-  const imageInfo: DimensionalFileInfo = { w: meta.width, h: meta.height };
-  const maxDim = Math.max(meta.width, meta.height);
-  if (maxDim > THUMBNAIL_MAX_SIDE) {
-    try {
-      const thumbBuffer = await getCore().media.resizeToJpeg({
-        buffer: params.buffer,
-        maxSide: THUMBNAIL_MAX_SIDE,
-        quality: THUMBNAIL_QUALITY,
-        withoutEnlargement: true,
-      });
-      const thumbMeta = await getCore().media.getImageMetadata(thumbBuffer).catch(() => null);
-      const thumbUri = await params.client.uploadContent(
-        thumbBuffer,
-        "image/jpeg",
-        "thumbnail.jpg",
-      );
-      imageInfo.thumbnail_url = thumbUri;
-      if (thumbMeta) {
-        imageInfo.thumbnail_info = {
-          w: thumbMeta.width,
-          h: thumbMeta.height,
-          mimetype: "image/jpeg",
-          size: thumbBuffer.byteLength,
-        };
-      }
-    } catch {
-      // Thumbnail generation failed, continue without it
-    }
-  }
-  return imageInfo;
-}
-
-async function resolveMediaDurationMs(params: {
-  buffer: Buffer;
-  contentType?: string;
-  fileName?: string;
-  kind: MediaKind;
-}): Promise<number | undefined> {
-  if (params.kind !== "audio" && params.kind !== "video") return undefined;
-  try {
-    const fileInfo: IFileInfo | string | undefined =
-      params.contentType || params.fileName
-        ? {
-            mimeType: params.contentType,
-            size: params.buffer.byteLength,
-            path: params.fileName,
-          }
-        : undefined;
-    const metadata = await parseBuffer(params.buffer, fileInfo, {
-      duration: true,
-      skipCovers: true,
-    });
-    const durationSeconds = metadata.format.duration;
-    if (typeof durationSeconds === "number" && Number.isFinite(durationSeconds)) {
-      return Math.max(0, Math.round(durationSeconds * 1000));
-    }
-  } catch {
-    // Duration is optional; ignore parse failures.
-  }
-  return undefined;
-}
-
-async function uploadFile(
-  client: MatrixClient,
-  file: Buffer,
-  params: {
-    contentType?: string;
-    filename?: string;
-  },
-): Promise<string> {
-  return await client.uploadContent(file, params.contentType, params.filename);
-}
-
-/**
- * Upload media with optional encryption for E2EE rooms.
- */
-async function uploadMediaMaybeEncrypted(
-  client: MatrixClient,
-  roomId: string,
-  buffer: Buffer,
-  params: {
-    contentType?: string;
-    filename?: string;
-  },
-): Promise<{ url: string; file?: EncryptedFile }> {
-  // Check if room is encrypted and crypto is available
-  const isEncrypted = client.crypto && await client.crypto.isRoomEncrypted(roomId);
-  
-  if (isEncrypted && client.crypto) {
-    // Encrypt the media before uploading
-    const encrypted = await client.crypto.encryptMedia(buffer);
-    const mxc = await client.uploadContent(encrypted.buffer, params.contentType, params.filename);
-    const file: EncryptedFile = { url: mxc, ...encrypted.file };
-    return {
-      url: mxc,
-      file,
-    };
-  }
-  
-  // Upload unencrypted
-  const mxc = await uploadFile(client, buffer, params);
-  return { url: mxc };
-}
-
-async function resolveMatrixClient(opts: {
-  client?: MatrixClient;
-  timeoutMs?: number;
-}): Promise<{ client: MatrixClient; stopOnDone: boolean }> {
-  ensureNodeRuntime();
-  if (opts.client) return { client: opts.client, stopOnDone: false };
-  const active = getActiveMatrixClient();
-  if (active) return { client: active, stopOnDone: false };
-  const shouldShareClient = Boolean(process.env.CLAWDBOT_GATEWAY_PORT);
-  if (shouldShareClient) {
-    const client = await resolveSharedMatrixClient({
-      timeoutMs: opts.timeoutMs,
-    });
-    return { client, stopOnDone: false };
-  }
-  const auth = await resolveMatrixAuth();
-  const client = await createMatrixClient({
-    homeserver: auth.homeserver,
-    userId: auth.userId,
-    accessToken: auth.accessToken,
-    encryption: auth.encryption,
-    localTimeoutMs: opts.timeoutMs,
-  });
-  if (auth.encryption && client.crypto) {
-    try {
-      const joinedRooms = await client.getJoinedRooms();
-      await client.crypto.prepare(joinedRooms);
-    } catch {
-      // Ignore crypto prep failures for one-off sends; normal sync will retry.
-    }
-  }
-  // matrix-bot-sdk uses start() instead of startClient()
-  await client.start();
-  return { client, stopOnDone: true };
-}
+export type { MatrixSendOpts, MatrixSendResult } from "./send/types.js";
+export { resolveMatrixRoomId } from "./send/targets.js";
 
 export async function sendMessageMatrix(
   to: string,
@@ -551,7 +85,9 @@ export async function sendMessageMatrix(
       });
       const msgtype = useVoice ? MsgType.Audio : baseMsgType;
       const isImage = msgtype === MsgType.Image;
-      const imageInfo = isImage ? await prepareImageInfo({ buffer: media.buffer, client }) : undefined;
+      const imageInfo = isImage
+        ? await prepareImageInfo({ buffer: media.buffer, client })
+        : undefined;
       const [firstChunk, ...rest] = chunks;
       const body = useVoice ? "Voice message" : (firstChunk ?? media.fileName ?? "(file)");
       const content = buildMediaContent({

extensions/matrix/src/matrix/send/client.ts

@@ -0,0 +1,63 @@
+import type { MatrixClient } from "matrix-bot-sdk";
+
+import { getMatrixRuntime } from "../../runtime.js";
+import { getActiveMatrixClient } from "../active-client.js";
+import {
+  createMatrixClient,
+  isBunRuntime,
+  resolveMatrixAuth,
+  resolveSharedMatrixClient,
+} from "../client.js";
+import type { CoreConfig } from "../types.js";
+
+const getCore = () => getMatrixRuntime();
+
+export function ensureNodeRuntime() {
+  if (isBunRuntime()) {
+    throw new Error("Matrix support requires Node (bun runtime not supported)");
+  }
+}
+
+export function resolveMediaMaxBytes(): number | undefined {
+  const cfg = getCore().config.loadConfig() as CoreConfig;
+  if (typeof cfg.channels?.matrix?.mediaMaxMb === "number") {
+    return cfg.channels.matrix.mediaMaxMb * 1024 * 1024;
+  }
+  return undefined;
+}
+
+export async function resolveMatrixClient(opts: {
+  client?: MatrixClient;
+  timeoutMs?: number;
+}): Promise<{ client: MatrixClient; stopOnDone: boolean }> {
+  ensureNodeRuntime();
+  if (opts.client) return { client: opts.client, stopOnDone: false };
+  const active = getActiveMatrixClient();
+  if (active) return { client: active, stopOnDone: false };
+  const shouldShareClient = Boolean(process.env.CLAWDBOT_GATEWAY_PORT);
+  if (shouldShareClient) {
+    const client = await resolveSharedMatrixClient({
+      timeoutMs: opts.timeoutMs,
+    });
+    return { client, stopOnDone: false };
+  }
+  const auth = await resolveMatrixAuth();
+  const client = await createMatrixClient({
+    homeserver: auth.homeserver,
+    userId: auth.userId,
+    accessToken: auth.accessToken,
+    encryption: auth.encryption,
+    localTimeoutMs: opts.timeoutMs,
+  });
+  if (auth.encryption && client.crypto) {
+    try {
+      const joinedRooms = await client.getJoinedRooms();
+      await client.crypto.prepare(joinedRooms);
+    } catch {
+      // Ignore crypto prep failures for one-off sends; normal sync will retry.
+    }
+  }
+  // matrix-bot-sdk uses start() instead of startClient()
+  await client.start();
+  return { client, stopOnDone: true };
+}

extensions/matrix/src/matrix/send/formatting.ts

@@ -0,0 +1,92 @@
+import { markdownToMatrixHtml } from "../format.js";
+import { getMatrixRuntime } from "../../runtime.js";
+import {
+  MsgType,
+  RelationType,
+  type MatrixFormattedContent,
+  type MatrixMediaMsgType,
+  type MatrixRelation,
+  type MatrixReplyRelation,
+  type MatrixTextContent,
+  type MatrixThreadRelation,
+} from "./types.js";
+
+const getCore = () => getMatrixRuntime();
+
+export function buildTextContent(
+  body: string,
+  relation?: MatrixRelation,
+): MatrixTextContent {
+  const content: MatrixTextContent = relation
+    ? {
+        msgtype: MsgType.Text,
+        body,
+        "m.relates_to": relation,
+      }
+    : {
+        msgtype: MsgType.Text,
+        body,
+      };
+  applyMatrixFormatting(content, body);
+  return content;
+}
+
+export function applyMatrixFormatting(content: MatrixFormattedContent, body: string): void {
+  const formatted = markdownToMatrixHtml(body ?? "");
+  if (!formatted) return;
+  content.format = "org.matrix.custom.html";
+  content.formatted_body = formatted;
+}
+
+export function buildReplyRelation(replyToId?: string): MatrixReplyRelation | undefined {
+  const trimmed = replyToId?.trim();
+  if (!trimmed) return undefined;
+  return { "m.in_reply_to": { event_id: trimmed } };
+}
+
+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) },
+  };
+}
+
+export function resolveMatrixMsgType(
+  contentType?: string,
+  _fileName?: string,
+): MatrixMediaMsgType {
+  const kind = getCore().media.mediaKindFromMime(contentType ?? "");
+  switch (kind) {
+    case "image":
+      return MsgType.Image;
+    case "audio":
+      return MsgType.Audio;
+    case "video":
+      return MsgType.Video;
+    default:
+      return MsgType.File;
+  }
+}
+
+export function resolveMatrixVoiceDecision(opts: {
+  wantsVoice: boolean;
+  contentType?: string;
+  fileName?: string;
+}): { useVoice: boolean } {
+  if (!opts.wantsVoice) return { useVoice: false };
+  if (
+    getCore().media.isVoiceCompatibleAudio({
+      contentType: opts.contentType,
+      fileName: opts.fileName,
+    })
+  ) {
+    return { useVoice: true };
+  }
+  return { useVoice: false };
+}

extensions/matrix/src/matrix/send/media.ts

@@ -0,0 +1,220 @@
+import type {
+  DimensionalFileInfo,
+  EncryptedFile,
+  FileWithThumbnailInfo,
+  MatrixClient,
+  TimedFileInfo,
+  VideoFileInfo,
+} from "matrix-bot-sdk";
+import { parseBuffer, type IFileInfo } from "music-metadata";
+
+import { getMatrixRuntime } from "../../runtime.js";
+import {
+  type MatrixMediaContent,
+  type MatrixMediaInfo,
+  type MatrixMediaMsgType,
+  type MatrixRelation,
+  type MediaKind,
+} from "./types.js";
+import { applyMatrixFormatting } from "./formatting.js";
+
+const getCore = () => getMatrixRuntime();
+
+export function buildMatrixMediaInfo(params: {
+  size: number;
+  mimetype?: string;
+  durationMs?: number;
+  imageInfo?: DimensionalFileInfo;
+}): MatrixMediaInfo | undefined {
+  const base: FileWithThumbnailInfo = {};
+  if (Number.isFinite(params.size)) {
+    base.size = params.size;
+  }
+  if (params.mimetype) {
+    base.mimetype = params.mimetype;
+  }
+  if (params.imageInfo) {
+    const dimensional: DimensionalFileInfo = {
+      ...base,
+      ...params.imageInfo,
+    };
+    if (typeof params.durationMs === "number") {
+      const videoInfo: VideoFileInfo = {
+        ...dimensional,
+        duration: params.durationMs,
+      };
+      return videoInfo;
+    }
+    return dimensional;
+  }
+  if (typeof params.durationMs === "number") {
+    const timedInfo: TimedFileInfo = {
+      ...base,
+      duration: params.durationMs,
+    };
+    return timedInfo;
+  }
+  if (Object.keys(base).length === 0) return undefined;
+  return base;
+}
+
+export function buildMediaContent(params: {
+  msgtype: MatrixMediaMsgType;
+  body: string;
+  url?: string;
+  filename?: string;
+  mimetype?: string;
+  size: number;
+  relation?: MatrixRelation;
+  isVoice?: boolean;
+  durationMs?: number;
+  imageInfo?: DimensionalFileInfo;
+  file?: EncryptedFile;
+}): MatrixMediaContent {
+  const info = buildMatrixMediaInfo({
+    size: params.size,
+    mimetype: params.mimetype,
+    durationMs: params.durationMs,
+    imageInfo: params.imageInfo,
+  });
+  const base: MatrixMediaContent = {
+    msgtype: params.msgtype,
+    body: params.body,
+    filename: params.filename,
+    info: info ?? undefined,
+  };
+  // Encrypted media should only include the "file" payload, not top-level "url".
+  if (!params.file && params.url) {
+    base.url = params.url;
+  }
+  // For encrypted files, add the file object
+  if (params.file) {
+    base.file = params.file;
+  }
+  if (params.isVoice) {
+    base["org.matrix.msc3245.voice"] = {};
+    if (typeof params.durationMs === "number") {
+      base["org.matrix.msc1767.audio"] = {
+        duration: params.durationMs,
+      };
+    }
+  }
+  if (params.relation) {
+    base["m.relates_to"] = params.relation;
+  }
+  applyMatrixFormatting(base, params.body);
+  return base;
+}
+
+const THUMBNAIL_MAX_SIDE = 800;
+const THUMBNAIL_QUALITY = 80;
+
+export async function prepareImageInfo(params: {
+  buffer: Buffer;
+  client: MatrixClient;
+}): Promise<DimensionalFileInfo | undefined> {
+  const meta = await getCore().media.getImageMetadata(params.buffer).catch(() => null);
+  if (!meta) return undefined;
+  const imageInfo: DimensionalFileInfo = { w: meta.width, h: meta.height };
+  const maxDim = Math.max(meta.width, meta.height);
+  if (maxDim > THUMBNAIL_MAX_SIDE) {
+    try {
+      const thumbBuffer = await getCore().media.resizeToJpeg({
+        buffer: params.buffer,
+        maxSide: THUMBNAIL_MAX_SIDE,
+        quality: THUMBNAIL_QUALITY,
+        withoutEnlargement: true,
+      });
+      const thumbMeta = await getCore().media.getImageMetadata(thumbBuffer).catch(() => null);
+      const thumbUri = await params.client.uploadContent(
+        thumbBuffer,
+        "image/jpeg",
+        "thumbnail.jpg",
+      );
+      imageInfo.thumbnail_url = thumbUri;
+      if (thumbMeta) {
+        imageInfo.thumbnail_info = {
+          w: thumbMeta.width,
+          h: thumbMeta.height,
+          mimetype: "image/jpeg",
+          size: thumbBuffer.byteLength,
+        };
+      }
+    } catch {
+      // Thumbnail generation failed, continue without it
+    }
+  }
+  return imageInfo;
+}
+
+export async function resolveMediaDurationMs(params: {
+  buffer: Buffer;
+  contentType?: string;
+  fileName?: string;
+  kind: MediaKind;
+}): Promise<number | undefined> {
+  if (params.kind !== "audio" && params.kind !== "video") return undefined;
+  try {
+    const fileInfo: IFileInfo | string | undefined =
+      params.contentType || params.fileName
+        ? {
+            mimeType: params.contentType,
+            size: params.buffer.byteLength,
+            path: params.fileName,
+          }
+        : undefined;
+    const metadata = await parseBuffer(params.buffer, fileInfo, {
+      duration: true,
+      skipCovers: true,
+    });
+    const durationSeconds = metadata.format.duration;
+    if (typeof durationSeconds === "number" && Number.isFinite(durationSeconds)) {
+      return Math.max(0, Math.round(durationSeconds * 1000));
+    }
+  } catch {
+    // Duration is optional; ignore parse failures.
+  }
+  return undefined;
+}
+
+async function uploadFile(
+  client: MatrixClient,
+  file: Buffer,
+  params: {
+    contentType?: string;
+    filename?: string;
+  },
+): Promise<string> {
+  return await client.uploadContent(file, params.contentType, params.filename);
+}
+
+/**
+ * Upload media with optional encryption for E2EE rooms.
+ */
+export async function uploadMediaMaybeEncrypted(
+  client: MatrixClient,
+  roomId: string,
+  buffer: Buffer,
+  params: {
+    contentType?: string;
+    filename?: string;
+  },
+): Promise<{ url: string; file?: EncryptedFile }> {
+  // Check if room is encrypted and crypto is available
+  const isEncrypted = client.crypto && await client.crypto.isRoomEncrypted(roomId);
+
+  if (isEncrypted && client.crypto) {
+    // Encrypt the media before uploading
+    const encrypted = await client.crypto.encryptMedia(buffer);
+    const mxc = await client.uploadContent(encrypted.buffer, params.contentType, params.filename);
+    const file: EncryptedFile = { url: mxc, ...encrypted.file };
+    return {
+      url: mxc,
+      file,
+    };
+  }
+
+  // Upload unencrypted
+  const mxc = await uploadFile(client, buffer, params);
+  return { url: mxc };
+}

extensions/matrix/src/matrix/send/targets.ts

@@ -0,0 +1,66 @@
+import type { MatrixClient } from "matrix-bot-sdk";
+
+import { EventType, type MatrixDirectAccountData } from "./types.js";
+
+function normalizeTarget(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("Matrix target is required (room:<id> or #alias)");
+  }
+  return trimmed;
+}
+
+export function normalizeThreadId(raw?: string | number | null): string | null {
+  if (raw === undefined || raw === null) return null;
+  const trimmed = String(raw).trim();
+  return trimmed ? trimmed : null;
+}
+
+async function resolveDirectRoomId(client: MatrixClient, userId: string): Promise<string> {
+  const trimmed = userId.trim();
+  if (!trimmed.startsWith("@")) {
+    throw new Error(`Matrix user IDs must be fully qualified (got "${trimmed}")`);
+  }
+  // matrix-bot-sdk: use getAccountData to retrieve m.direct
+  try {
+    const directContent = await client.getAccountData(EventType.Direct) as MatrixDirectAccountData | null;
+    const list = Array.isArray(directContent?.[trimmed]) ? directContent[trimmed] : [];
+    if (list.length > 0) return list[0];
+  } catch {
+    // Ignore errors, try fetching from server
+  }
+  throw new Error(
+    `No m.direct room found for ${trimmed}. Open a DM first so Matrix can set m.direct.`,
+  );
+}
+
+export async function resolveMatrixRoomId(
+  client: MatrixClient,
+  raw: string,
+): Promise<string> {
+  const target = normalizeTarget(raw);
+  const lowered = target.toLowerCase();
+  if (lowered.startsWith("matrix:")) {
+    return await resolveMatrixRoomId(client, target.slice("matrix:".length));
+  }
+  if (lowered.startsWith("room:")) {
+    return await resolveMatrixRoomId(client, target.slice("room:".length));
+  }
+  if (lowered.startsWith("channel:")) {
+    return await resolveMatrixRoomId(client, target.slice("channel:".length));
+  }
+  if (lowered.startsWith("user:")) {
+    return await resolveDirectRoomId(client, target.slice("user:".length));
+  }
+  if (target.startsWith("@")) {
+    return await resolveDirectRoomId(client, target);
+  }
+  if (target.startsWith("#")) {
+    const resolved = await client.resolveRoom(target);
+    if (!resolved) {
+      throw new Error(`Matrix alias ${target} could not be resolved`);
+    }
+    return resolved;
+  }
+  return target;
+}

extensions/matrix/src/matrix/send/types.ts

@@ -0,0 +1,108 @@
+import type {
+  DimensionalFileInfo,
+  EncryptedFile,
+  FileWithThumbnailInfo,
+  MessageEventContent,
+  TextualMessageEventContent,
+  TimedFileInfo,
+  VideoFileInfo,
+} from "matrix-bot-sdk";
+
+// Message types
+export const MsgType = {
+  Text: "m.text",
+  Image: "m.image",
+  Audio: "m.audio",
+  Video: "m.video",
+  File: "m.file",
+  Notice: "m.notice",
+} as const;
+
+// Relation types
+export const RelationType = {
+  Annotation: "m.annotation",
+  Replace: "m.replace",
+  Thread: "m.thread",
+} as const;
+
+// Event types
+export const EventType = {
+  Direct: "m.direct",
+  Reaction: "m.reaction",
+  RoomMessage: "m.room.message",
+} as const;
+
+export type MatrixDirectAccountData = Record<string, string[]>;
+
+export type MatrixReplyRelation = {
+  "m.in_reply_to": { event_id: string };
+};
+
+export type MatrixThreadRelation = {
+  rel_type: typeof RelationType.Thread;
+  event_id: string;
+  is_falling_back?: boolean;
+  "m.in_reply_to"?: { event_id: string };
+};
+
+export type MatrixRelation = MatrixReplyRelation | MatrixThreadRelation;
+
+export type MatrixReplyMeta = {
+  "m.relates_to"?: MatrixRelation;
+};
+
+export type MatrixMediaInfo =
+  | FileWithThumbnailInfo
+  | DimensionalFileInfo
+  | TimedFileInfo
+  | VideoFileInfo;
+
+export type MatrixTextContent = TextualMessageEventContent & MatrixReplyMeta;
+
+export type MatrixMediaContent = MessageEventContent &
+  MatrixReplyMeta & {
+    info?: MatrixMediaInfo;
+    url?: string;
+    file?: EncryptedFile;
+    filename?: string;
+    "org.matrix.msc3245.voice"?: Record<string, never>;
+    "org.matrix.msc1767.audio"?: { duration: number };
+  };
+
+export type MatrixOutboundContent = MatrixTextContent | MatrixMediaContent;
+
+export type ReactionEventContent = {
+  "m.relates_to": {
+    rel_type: typeof RelationType.Annotation;
+    event_id: string;
+    key: string;
+  };
+};
+
+export type MatrixSendResult = {
+  messageId: string;
+  roomId: string;
+};
+
+export type MatrixSendOpts = {
+  client?: import("matrix-bot-sdk").MatrixClient;
+  mediaUrl?: string;
+  replyToId?: string;
+  threadId?: string | number | null;
+  timeoutMs?: number;
+  /** Send audio as voice message (voice bubble) instead of audio file. Defaults to false. */
+  audioAsVoice?: boolean;
+};
+
+export type MatrixMediaMsgType =
+  | typeof MsgType.Image
+  | typeof MsgType.Audio
+  | typeof MsgType.Video
+  | typeof MsgType.File;
+
+export type MediaKind = "image" | "audio" | "video" | "document" | "unknown";
+
+export type MatrixFormattedContent = MessageEventContent & {
+  format?: string;
+  formatted_body?: string;
+};

extensions/memory-lancedb/package.json

@@ -4,9 +4,9 @@
   "type": "module",
   "description": "Clawdbot LanceDB-backed long-term memory plugin with auto-recall/capture",
   "dependencies": {
-    "@lancedb/lancedb": "^0.15.0",
+    "@lancedb/lancedb": "^0.23.0",
     "@sinclair/typebox": "0.34.47",
-    "openai": "^4.104.0"
+    "openai": "^6.16.0"
   },
   "clawdbot": {
     "extensions": [

extensions/zalouser/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 2026.1.17-1
+
+- Initial version with full channel plugin support
+- QR code login via zca-cli
+- Multi-account support
+- Agent tool for sending messages
+- Group and DM policy support
+- ChannelDock for lightweight shared metadata
+- Zod-based config schema validation
+- Setup adapter for programmatic configuration
+- Dedicated probe and status issues modules

extensions/zalouser/index.ts

@@ -1,7 +1,7 @@
 import type { ClawdbotPluginApi } from "clawdbot/plugin-sdk";
 import { emptyPluginConfigSchema } from "clawdbot/plugin-sdk";
 
-import { zalouserPlugin } from "./src/channel.js";
+import { zalouserDock, zalouserPlugin } from "./src/channel.js";
 import { ZalouserToolSchema, executeZalouserTool } from "./src/tool.js";
 import { setZalouserRuntime } from "./src/runtime.js";
 
@@ -13,7 +13,7 @@ const plugin = {
   register(api: ClawdbotPluginApi) {
     setZalouserRuntime(api.runtime);
     // Register channel plugin (for onboarding & gateway)
-    api.registerChannel(zalouserPlugin);
+    api.registerChannel({ plugin: zalouserPlugin, dock: zalouserDock });
 
     // Register agent tool
     api.registerTool({

extensions/zalouser/src/channel.ts

@@ -1,13 +1,17 @@
 import type {
   ChannelAccountSnapshot,
   ChannelDirectoryEntry,
+  ChannelDock,
   ChannelPlugin,
   ClawdbotConfig,
 } from "clawdbot/plugin-sdk";
 import {
+  applyAccountNameToChannelSection,
+  buildChannelConfigSchema,
   DEFAULT_ACCOUNT_ID,
   deleteAccountFromConfigSection,
   formatPairingApproveHint,
+  migrateBaseNameToDefaultAccount,
   normalizeAccountId,
   setAccountEnabledInConfigSection,
 } from "clawdbot/plugin-sdk";
@@ -23,6 +27,9 @@ import { zalouserOnboardingAdapter } from "./onboarding.js";
 import { sendMessageZalouser } from "./send.js";
 import { checkZcaInstalled, parseJsonOutput, runZca, runZcaInteractive } from "./zca.js";
 import type { ZcaFriend, ZcaGroup, ZcaUserInfo } from "./types.js";
+import { ZalouserConfigSchema } from "./config-schema.js";
+import { collectZalouserStatusIssues } from "./status-issues.js";
+import { probeZalouser } from "./probe.js";
 
 const meta = {
   id: "zalouser",
@@ -72,6 +79,34 @@ function mapGroup(params: {
   };
 }
 
+export const zalouserDock: ChannelDock = {
+  id: "zalouser",
+  capabilities: {
+    chatTypes: ["direct", "group"],
+    media: true,
+    blockStreaming: true,
+  },
+  outbound: { textChunkLimit: 2000 },
+  config: {
+    resolveAllowFrom: ({ cfg, accountId }) =>
+      (resolveZalouserAccountSync({ cfg: cfg as ClawdbotConfig, accountId }).config.allowFrom ?? []).map(
+        (entry) => String(entry),
+      ),
+    formatAllowFrom: ({ allowFrom }) =>
+      allowFrom
+        .map((entry) => String(entry).trim())
+        .filter(Boolean)
+        .map((entry) => entry.replace(/^(zalouser|zlu):/i, ""))
+        .map((entry) => entry.toLowerCase()),
+  },
+  groups: {
+    resolveRequireMention: () => true,
+  },
+  threading: {
+    resolveReplyToMode: () => "off",
+  },
+};
+
 export const zalouserPlugin: ChannelPlugin<ResolvedZalouserAccount> = {
   id: "zalouser",
   meta,
@@ -86,6 +121,7 @@ export const zalouserPlugin: ChannelPlugin<ResolvedZalouserAccount> = {
     blockStreaming: true,
   },
   reload: { configPrefixes: ["channels.zalouser"] },
+  configSchema: buildChannelConfigSchema(ZalouserConfigSchema),
   config: {
     listAccountIds: (cfg) => listZalouserAccountIds(cfg as ClawdbotConfig),
     resolveAccount: (cfg, accountId) =>
@@ -156,6 +192,61 @@ export const zalouserPlugin: ChannelPlugin<ResolvedZalouserAccount> = {
   threading: {
     resolveReplyToMode: () => "off",
   },
+  setup: {
+    resolveAccountId: ({ accountId }) => normalizeAccountId(accountId),
+    applyAccountName: ({ cfg, accountId, name }) =>
+      applyAccountNameToChannelSection({
+        cfg: cfg as ClawdbotConfig,
+        channelKey: "zalouser",
+        accountId,
+        name,
+      }),
+    validateInput: () => null,
+    applyAccountConfig: ({ cfg, accountId, input }) => {
+      const namedConfig = applyAccountNameToChannelSection({
+        cfg: cfg as ClawdbotConfig,
+        channelKey: "zalouser",
+        accountId,
+        name: input.name,
+      });
+      const next =
+        accountId !== DEFAULT_ACCOUNT_ID
+          ? migrateBaseNameToDefaultAccount({
+              cfg: namedConfig,
+              channelKey: "zalouser",
+            })
+          : namedConfig;
+      if (accountId === DEFAULT_ACCOUNT_ID) {
+        return {
+          ...next,
+          channels: {
+            ...next.channels,
+            zalouser: {
+              ...next.channels?.zalouser,
+              enabled: true,
+            },
+          },
+        } as ClawdbotConfig;
+      }
+      return {
+        ...next,
+        channels: {
+          ...next.channels,
+          zalouser: {
+            ...next.channels?.zalouser,
+            enabled: true,
+            accounts: {
+              ...(next.channels?.zalouser?.accounts ?? {}),
+              [accountId]: {
+                ...(next.channels?.zalouser?.accounts?.[accountId] ?? {}),
+                enabled: true,
+              },
+            },
+          },
+        },
+      } as ClawdbotConfig;
+    },
+  },
   messaging: {
     normalizeTarget: (raw) => {
       const trimmed = raw?.trim();
@@ -424,6 +515,7 @@ export const zalouserPlugin: ChannelPlugin<ResolvedZalouserAccount> = {
       lastStopAt: null,
       lastError: null,
     },
+    collectStatusIssues: collectZalouserStatusIssues,
     buildChannelSummary: ({ snapshot }) => ({
       configured: snapshot.configured ?? false,
       running: snapshot.running ?? false,
@@ -433,22 +525,12 @@ export const zalouserPlugin: ChannelPlugin<ResolvedZalouserAccount> = {
       probe: snapshot.probe,
       lastProbeAt: snapshot.lastProbeAt ?? null,
     }),
-    probeAccount: async ({ account, timeoutMs }) => {
-      const result = await runZca(["me", "info", "-j"], {
-        profile: account.profile,
-        timeout: timeoutMs,
-      });
-      if (!result.ok) {
-        return { ok: false, error: result.stderr };
-      }
-      try {
-        return { ok: true, user: JSON.parse(result.stdout) };
-      } catch {
-        return { ok: false, error: "Failed to parse user info" };
-      }
-    },
+    probeAccount: async ({ account, timeoutMs }) =>
+      probeZalouser(account.profile, timeoutMs),
     buildAccountSnapshot: async ({ account, runtime }) => {
-      const configured = await checkZcaAuthenticated(account.profile);
+      const zcaInstalled = await checkZcaInstalled();
+      const configured = zcaInstalled ? await checkZcaAuthenticated(account.profile) : false;
+      const configError = zcaInstalled ? "not authenticated" : "zca CLI not found in PATH";
       return {
         accountId: account.accountId,
         name: account.name,
@@ -457,7 +539,7 @@ export const zalouserPlugin: ChannelPlugin<ResolvedZalouserAccount> = {
         running: runtime?.running ?? false,
         lastStartAt: runtime?.lastStartAt ?? null,
         lastStopAt: runtime?.lastStopAt ?? null,
-        lastError: configured ? (runtime?.lastError ?? null) : "not configured",
+        lastError: configured ? (runtime?.lastError ?? null) : runtime?.lastError ?? configError,
         lastInboundAt: runtime?.lastInboundAt ?? null,
         lastOutboundAt: runtime?.lastOutboundAt ?? null,
         dmPolicy: account.config.dmPolicy ?? "pairing",

extensions/zalouser/src/config-schema.ts

@@ -0,0 +1,24 @@
+import { z } from "zod";
+
+const allowFromEntry = z.union([z.string(), z.number()]);
+
+const groupConfigSchema = z.object({
+  allow: z.boolean().optional(),
+  enabled: z.boolean().optional(),
+});
+
+const zalouserAccountSchema = z.object({
+  name: z.string().optional(),
+  enabled: z.boolean().optional(),
+  profile: z.string().optional(),
+  dmPolicy: z.enum(["pairing", "allowlist", "open", "disabled"]).optional(),
+  allowFrom: z.array(allowFromEntry).optional(),
+  groupPolicy: z.enum(["disabled", "allowlist", "open"]).optional(),
+  groups: z.object({}).catchall(groupConfigSchema).optional(),
+  messagePrefix: z.string().optional(),
+});
+
+export const ZalouserConfigSchema = zalouserAccountSchema.extend({
+  accounts: z.object({}).catchall(zalouserAccountSchema).optional(),
+  defaultAccount: z.string().optional(),
+});

extensions/zalouser/src/probe.ts

@@ -0,0 +1,28 @@
+import { runZca, parseJsonOutput } from "./zca.js";
+import type { ZcaUserInfo } from "./types.js";
+
+export interface ZalouserProbeResult {
+  ok: boolean;
+  user?: ZcaUserInfo;
+  error?: string;
+}
+
+export async function probeZalouser(
+  profile: string,
+  timeoutMs?: number,
+): Promise<ZalouserProbeResult> {
+  const result = await runZca(["me", "info", "-j"], {
+    profile,
+    timeout: timeoutMs,
+  });
+
+  if (!result.ok) {
+    return { ok: false, error: result.stderr || "Failed to probe" };
+  }
+
+  const user = parseJsonOutput<ZcaUserInfo>(result.stdout);
+  if (!user) {
+    return { ok: false, error: "Failed to parse user info" };
+  }
+  return { ok: true, user };
+}

extensions/zalouser/src/status-issues.test.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from "vitest";
+
+import { collectZalouserStatusIssues } from "./status-issues.js";
+
+describe("collectZalouserStatusIssues", () => {
+  it("flags missing zca when configured is false", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: false,
+        lastError: "zca CLI not found in PATH",
+      },
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.kind).toBe("runtime");
+    expect(issues[0]?.message).toMatch(/zca CLI not found/i);
+  });
+
+  it("flags missing auth when configured is false", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: false,
+        lastError: "not authenticated",
+      },
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.kind).toBe("auth");
+    expect(issues[0]?.message).toMatch(/Not authenticated/i);
+  });
+
+  it("warns when dmPolicy is open", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: true,
+        configured: true,
+        dmPolicy: "open",
+      },
+    ]);
+    expect(issues).toHaveLength(1);
+    expect(issues[0]?.kind).toBe("config");
+  });
+
+  it("skips disabled accounts", () => {
+    const issues = collectZalouserStatusIssues([
+      {
+        accountId: "default",
+        enabled: false,
+        configured: false,
+        lastError: "zca CLI not found in PATH",
+      },
+    ]);
+    expect(issues).toHaveLength(0);
+  });
+});

extensions/zalouser/src/status-issues.ts

@@ -0,0 +1,81 @@
+import type { ChannelAccountSnapshot, ChannelStatusIssue } from "clawdbot/plugin-sdk";
+
+type ZalouserAccountStatus = {
+  accountId?: unknown;
+  enabled?: unknown;
+  configured?: unknown;
+  dmPolicy?: unknown;
+  lastError?: unknown;
+};
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+  Boolean(value && typeof value === "object");
+
+const asString = (value: unknown): string | undefined =>
+  typeof value === "string" ? value : typeof value === "number" ? String(value) : undefined;
+
+function readZalouserAccountStatus(value: ChannelAccountSnapshot): ZalouserAccountStatus | null {
+  if (!isRecord(value)) return null;
+  return {
+    accountId: value.accountId,
+    enabled: value.enabled,
+    configured: value.configured,
+    dmPolicy: value.dmPolicy,
+    lastError: value.lastError,
+  };
+}
+
+function isMissingZca(lastError?: string): boolean {
+  if (!lastError) return false;
+  const lower = lastError.toLowerCase();
+  return lower.includes("zca") && (lower.includes("not found") || lower.includes("enoent"));
+}
+
+export function collectZalouserStatusIssues(
+  accounts: ChannelAccountSnapshot[],
+): ChannelStatusIssue[] {
+  const issues: ChannelStatusIssue[] = [];
+  for (const entry of accounts) {
+    const account = readZalouserAccountStatus(entry);
+    if (!account) continue;
+    const accountId = asString(account.accountId) ?? "default";
+    const enabled = account.enabled !== false;
+    if (!enabled) continue;
+
+    const configured = account.configured === true;
+    const lastError = asString(account.lastError)?.trim();
+
+    if (!configured) {
+      if (isMissingZca(lastError)) {
+        issues.push({
+          channel: "zalouser",
+          accountId,
+          kind: "runtime",
+          message: "zca CLI not found in PATH.",
+          fix: "Install zca-cli and ensure it is on PATH for the Gateway process.",
+        });
+      } else {
+        issues.push({
+          channel: "zalouser",
+          accountId,
+          kind: "auth",
+          message: "Not authenticated (no zca session).",
+          fix: "Run: clawdbot channels login --channel zalouser",
+        });
+      }
+      continue;
+    }
+
+    if (account.dmPolicy === "open") {
+      issues.push({
+        channel: "zalouser",
+        accountId,
+        kind: "config",
+        message:
+          'Zalo Personal dmPolicy is "open", allowing any user to message the bot without pairing.',
+        fix: 'Set channels.zalouser.dmPolicy to "pairing" or "allowlist" to restrict access.',
+      });
+    }
+  }
+  return issues;
+}

package.json

@@ -150,10 +150,10 @@
     "@grammyjs/transformer-throttler": "^1.2.1",
     "@homebridge/ciao": "^1.3.4",
     "@lydell/node-pty": "1.2.0-beta.3",
-    "@mariozechner/pi-agent-core": "0.46.0",
-    "@mariozechner/pi-ai": "0.46.0",
-    "@mariozechner/pi-coding-agent": "^0.46.0",
-    "@mariozechner/pi-tui": "^0.46.0",
+    "@mariozechner/pi-agent-core": "0.49.2",
+    "@mariozechner/pi-ai": "0.49.2",
+    "@mariozechner/pi-coding-agent": "^0.49.2",
+    "@mariozechner/pi-tui": "^0.49.2",
     "@mozilla/readability": "^0.6.0",
     "@sinclair/typebox": "0.34.47",
     "@slack/bolt": "^4.6.0",
@@ -163,7 +163,7 @@
     "body-parser": "^2.2.2",
     "chalk": "^5.6.2",
     "chokidar": "^5.0.0",
-    "chromium-bidi": "12.0.1",
+    "chromium-bidi": "13.0.0",
     "cli-highlight": "^2.1.11",
     "commander": "^14.0.2",
     "croner": "^9.1.0",
@@ -180,14 +180,14 @@
     "linkedom": "^0.18.12",
     "long": "5.3.2",
     "markdown-it": "^14.1.0",
-    "osc-progress": "^0.2.0",
+    "osc-progress": "^0.3.0",
     "pdfjs-dist": "^5.4.530",
     "playwright-core": "1.57.0",
     "proper-lockfile": "^4.1.2",
     "qrcode-terminal": "^0.12.0",
     "sharp": "^0.34.5",
     "sqlite-vec": "0.1.7-alpha.2",
-    "tar": "7.5.3",
+    "tar": "7.5.4",
     "tslog": "^4.10.2",
     "undici": "^7.18.2",
     "ws": "^8.19.0",
@@ -196,7 +196,7 @@
   },
   "optionalDependencies": {
     "@napi-rs/canvas": "^0.1.88",
-    "node-llama-cpp": "3.14.5"
+    "node-llama-cpp": "3.15.0"
   },
   "devDependencies": {
     "@grammyjs/types": "^3.23.0",
@@ -215,11 +215,11 @@
     "lit": "^3.3.2",
     "lucide": "^0.562.0",
     "ollama": "^0.6.3",
-    "oxfmt": "0.24.0",
-    "oxlint": "^1.39.0",
+    "oxfmt": "0.26.0",
+    "oxlint": "^1.41.0",
     "oxlint-tsgolint": "^0.11.1",
     "quicktype-core": "^23.2.6",
-    "rolldown": "1.0.0-beta.59",
+    "rolldown": "1.0.0-beta.60",
     "signal-utils": "^0.21.1",
     "tsx": "^4.21.0",
     "typescript": "^5.9.3",

src/agents/auth-profiles/external-cli-sync.ts

@@ -179,9 +179,10 @@ export function syncExternalCliCredentials(
     !existingCodex ||
     existingCodex.provider !== "openai-codex" ||
     !isExternalProfileFresh(existingCodex, now);
-  const codexCreds = shouldSyncCodex || duplicateExistingId
-    ? readCodexCliCredentialsCached({ ttlMs: EXTERNAL_CLI_SYNC_TTL_MS })
-    : null;
+  const codexCreds =
+    shouldSyncCodex || duplicateExistingId
+      ? readCodexCliCredentialsCached({ ttlMs: EXTERNAL_CLI_SYNC_TTL_MS })
+      : null;
   if (codexCreds) {
     const duplicateProfileId = findDuplicateCodexProfile(store, codexCreds);
     if (duplicateProfileId) {

src/agents/bash-tools.exec.path.test.ts

@@ -0,0 +1,100 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import type { ExecApprovalsResolved } from "../infra/exec-approvals.js";
+import { sanitizeBinaryOutput } from "./shell-utils.js";
+
+const isWin = process.platform === "win32";
+
+vi.mock("../infra/shell-env.js", async (importOriginal) => {
+  const mod = await importOriginal<typeof import("../infra/shell-env.js")>();
+  return {
+    ...mod,
+    getShellPathFromLoginShell: vi.fn(() => "/custom/bin:/opt/bin"),
+    resolveShellEnvFallbackTimeoutMs: vi.fn(() => 1234),
+  };
+});
+
+vi.mock("../infra/exec-approvals.js", async (importOriginal) => {
+  const mod = await importOriginal<typeof import("../infra/exec-approvals.js")>();
+  const approvals: ExecApprovalsResolved = {
+    path: "/tmp/exec-approvals.json",
+    socketPath: "/tmp/exec-approvals.sock",
+    token: "token",
+    defaults: {
+      security: "full",
+      ask: "off",
+      askFallback: "full",
+      autoAllowSkills: false,
+    },
+    agent: {
+      security: "full",
+      ask: "off",
+      askFallback: "full",
+      autoAllowSkills: false,
+    },
+    allowlist: [],
+    file: {
+      version: 1,
+      socket: { path: "/tmp/exec-approvals.sock", token: "token" },
+      defaults: {
+        security: "full",
+        ask: "off",
+        askFallback: "full",
+        autoAllowSkills: false,
+      },
+      agents: {},
+    },
+  };
+  return { ...mod, resolveExecApprovals: () => approvals };
+});
+
+const normalizeText = (value?: string) =>
+  sanitizeBinaryOutput(value ?? "")
+    .replace(/\r\n/g, "\n")
+    .replace(/\r/g, "\n")
+    .trim();
+
+describe("exec PATH login shell merge", () => {
+  const originalPath = process.env.PATH;
+
+  afterEach(() => {
+    process.env.PATH = originalPath;
+  });
+
+  it("merges login-shell PATH for host=gateway", async () => {
+    if (isWin) return;
+    process.env.PATH = "/usr/bin";
+
+    const { createExecTool } = await import("./bash-tools.exec.js");
+    const { getShellPathFromLoginShell } = await import("../infra/shell-env.js");
+    const shellPathMock = vi.mocked(getShellPathFromLoginShell);
+    shellPathMock.mockClear();
+    shellPathMock.mockReturnValue("/custom/bin:/opt/bin");
+
+    const tool = createExecTool({ host: "gateway", security: "full", ask: "off" });
+    const result = await tool.execute("call1", { command: "echo $PATH" });
+    const text = normalizeText(result.content.find((c) => c.type === "text")?.text);
+
+    expect(text).toBe("/custom/bin:/opt/bin:/usr/bin");
+    expect(shellPathMock).toHaveBeenCalledTimes(1);
+  });
+
+  it("skips login-shell PATH when env.PATH is provided", async () => {
+    if (isWin) return;
+    process.env.PATH = "/usr/bin";
+
+    const { createExecTool } = await import("./bash-tools.exec.js");
+    const { getShellPathFromLoginShell } = await import("../infra/shell-env.js");
+    const shellPathMock = vi.mocked(getShellPathFromLoginShell);
+    shellPathMock.mockClear();
+
+    const tool = createExecTool({ host: "gateway", security: "full", ask: "off" });
+    const result = await tool.execute("call1", {
+      command: "echo $PATH",
+      env: { PATH: "/explicit/bin" },
+    });
+    const text = normalizeText(result.content.find((c) => c.type === "text")?.text);
+
+    expect(text).toBe("/explicit/bin");
+    expect(shellPathMock).not.toHaveBeenCalled();
+  });
+});

src/agents/bash-tools.exec.ts

@@ -18,6 +18,10 @@ import {
 } from "../infra/exec-approvals.js";
 import { requestHeartbeatNow } from "../infra/heartbeat-wake.js";
 import { buildNodeShellCommand } from "../infra/node-shell.js";
+import {
+  getShellPathFromLoginShell,
+  resolveShellEnvFallbackTimeoutMs,
+} from "../infra/shell-env.js";
 import { enqueueSystemEvent } from "../infra/system-events.js";
 import { logInfo } from "../logger.js";
 import {
@@ -249,6 +253,17 @@ function applyPathPrepend(
   if (merged) env.PATH = merged;
 }
 
+function applyShellPath(env: Record<string, string>, shellPath?: string | null) {
+  if (!shellPath) return;
+  const entries = shellPath
+    .split(path.delimiter)
+    .map((part) => part.trim())
+    .filter(Boolean);
+  if (entries.length === 0) return;
+  const merged = mergePathPrepend(env.PATH, entries);
+  if (merged) env.PATH = merged;
+}
+
 function maybeNotifyOnExit(session: ProcessSession, status: "completed" | "failed") {
   if (!session.backgrounded || !session.notifyOnExit || session.exitNotified) return;
   const sessionKey = session.sessionKey?.trim();
@@ -422,6 +437,13 @@ export function createExecTool(
             containerWorkdir: containerWorkdir ?? sandbox.containerWorkdir,
           })
         : mergedEnv;
+      if (!sandbox && host === "gateway" && !params.env?.PATH) {
+        const shellPath = getShellPathFromLoginShell({
+          env: process.env,
+          timeoutMs: resolveShellEnvFallbackTimeoutMs(process.env),
+        });
+        applyShellPath(env, shellPath);
+      }
       applyPathPrepend(env, defaultPathPrepend);
 
       if (host === "node") {

src/agents/cli-runner/helpers.ts

@@ -11,6 +11,7 @@ import type { CliBackendConfig } from "../../config/types.js";
 import { runExec } from "../../process/exec.js";
 import type { EmbeddedContextFile } from "../pi-embedded-helpers.js";
 import { buildSystemPromptParams } from "../system-prompt-params.js";
+import { resolveDefaultModelForAgent } from "../model-selection.js";
 import { buildAgentSystemPrompt } from "../system-prompt.js";
 
 const CLI_RUN_QUEUE = new Map<string, Promise<unknown>>();
@@ -174,6 +175,11 @@ export function buildSystemPrompt(params: {
   modelDisplay: string;
   agentId?: string;
 }) {
+  const defaultModelRef = resolveDefaultModelForAgent({
+    cfg: params.config ?? {},
+    agentId: params.agentId,
+  });
+  const defaultModelLabel = `${defaultModelRef.provider}/${defaultModelRef.model}`;
   const { runtimeInfo, userTimezone, userTime, userTimeFormat } = buildSystemPromptParams({
     config: params.config,
     agentId: params.agentId,
@@ -183,6 +189,7 @@ export function buildSystemPrompt(params: {
       arch: os.arch(),
       node: process.version,
       model: params.modelDisplay,
+      defaultModel: defaultModelLabel,
     },
   });
   return buildAgentSystemPrompt({

src/agents/model-auth.ts

@@ -38,9 +38,9 @@ function resolveProviderConfig(
   }
   return (
     (providers[normalized] as ModelProviderConfig | undefined) ??
-    (Object.entries(providers).find(
-      ([key]) => normalizeProviderId(key) === normalized,
-    )?.[1] as ModelProviderConfig | undefined)
+    (Object.entries(providers).find(([key]) => normalizeProviderId(key) === normalized)?.[1] as
+      | ModelProviderConfig
+      | undefined)
   );
 }
 
@@ -353,7 +353,5 @@ export async function getApiKeyForModel(params: {
 export function requireApiKey(auth: ResolvedProviderAuth, provider: string): string {
   const key = auth.apiKey?.trim();
   if (key) return key;
-  throw new Error(
-    `No API key resolved for provider "${provider}" (auth mode: ${auth.mode}).`,
-  );
+  throw new Error(`No API key resolved for provider "${provider}" (auth mode: ${auth.mode}).`);
 }

src/agents/model-compat.ts

@@ -3,7 +3,7 @@ import type { Api, Model } from "@mariozechner/pi-ai";
 export function normalizeModelCompat(model: Model<Api>): Model<Api> {
   const baseUrl = model.baseUrl ?? "";
   const isZai = model.provider === "zai" || baseUrl.includes("api.z.ai");
-  if (!isZai) return model;
+  if (!isZai || model.api !== "openai-completions") return model;
 
   const compat = model.compat ?? {};
   if (compat.supportsDeveloperRole === false) return model;

src/agents/model-selection.ts

@@ -1,6 +1,8 @@
 import type { ClawdbotConfig } from "../config/config.js";
 import type { ModelCatalogEntry } from "./model-catalog.js";
 import { normalizeGoogleModelId } from "./models-config.providers.js";
+import { resolveAgentModelPrimary } from "./agent-scope.js";
+import { DEFAULT_MODEL, DEFAULT_PROVIDER } from "./defaults.js";
 
 export type ModelRef = {
   provider: string;
@@ -141,6 +143,38 @@ export function resolveConfiguredModelRef(params: {
   return { provider: params.defaultProvider, model: params.defaultModel };
 }
 
+export function resolveDefaultModelForAgent(params: {
+  cfg: ClawdbotConfig;
+  agentId?: string;
+}): ModelRef {
+  const agentModelOverride = params.agentId
+    ? resolveAgentModelPrimary(params.cfg, params.agentId)
+    : undefined;
+  const cfg =
+    agentModelOverride && agentModelOverride.length > 0
+      ? {
+          ...params.cfg,
+          agents: {
+            ...params.cfg.agents,
+            defaults: {
+              ...params.cfg.agents?.defaults,
+              model: {
+                ...(typeof params.cfg.agents?.defaults?.model === "object"
+                  ? params.cfg.agents.defaults.model
+                  : undefined),
+                primary: agentModelOverride,
+              },
+            },
+          },
+        }
+      : params.cfg;
+  return resolveConfiguredModelRef({
+    cfg,
+    defaultProvider: DEFAULT_PROVIDER,
+    defaultModel: DEFAULT_MODEL,
+  });
+}
+
 export function buildAllowedModelSet(params: {
   cfg: ClawdbotConfig;
   catalog: ModelCatalogEntry[];

src/agents/pi-embedded-runner/model.ts

@@ -55,8 +55,7 @@ export function resolveModel(
     const inlineModels = buildInlineProviderModels(providers);
     const normalizedProvider = normalizeProviderId(provider);
     const inlineMatch = inlineModels.find(
-      (entry) =>
-        normalizeProviderId(entry.provider) === normalizedProvider && entry.id === modelId,
+      (entry) => normalizeProviderId(entry.provider) === normalizedProvider && entry.id === modelId,
     );
     if (inlineMatch) {
       const normalized = normalizeModelCompat(inlineMatch as Model<Api>);

src/agents/pi-embedded-runner/run/attempt.ts

@@ -43,6 +43,7 @@ import {
   resolveSkillsPromptForRun,
 } from "../../skills.js";
 import { buildSystemPromptReport } from "../../system-prompt-report.js";
+import { resolveDefaultModelForAgent } from "../../model-selection.js";
 
 import { isAbortError } from "../abort.js";
 import { buildEmbeddedExtensionPaths } from "../extensions.js";
@@ -212,6 +213,11 @@ export async function runEmbeddedAttempt(
         })
       : undefined;
 
+    const defaultModelRef = resolveDefaultModelForAgent({
+      cfg: params.config ?? {},
+      agentId: sessionAgentId,
+    });
+    const defaultModelLabel = `${defaultModelRef.provider}/${defaultModelRef.model}`;
     const { runtimeInfo, userTimezone, userTime, userTimeFormat } = buildSystemPromptParams({
       config: params.config,
       agentId: sessionAgentId,
@@ -221,6 +227,7 @@ export async function runEmbeddedAttempt(
         arch: os.arch(),
         node: process.version,
         model: `${params.provider}/${params.modelId}`,
+        defaultModel: defaultModelLabel,
         channel: runtimeChannel,
         capabilities: runtimeCapabilities,
         channelActions,

src/agents/system-prompt-params.ts

@@ -13,6 +13,7 @@ export type RuntimeInfoInput = {
   arch: string;
   node: string;
   model: string;
+  defaultModel?: string;
   channel?: string;
   capabilities?: string[];
   /** Supported message actions for the current channel (e.g., react, edit, unsend) */

src/agents/system-prompt.test.ts

@@ -288,6 +288,7 @@ describe("buildAgentSystemPrompt", () => {
         arch: "arm64",
         node: "v20",
         model: "anthropic/claude",
+        defaultModel: "anthropic/claude-opus-4-5",
       },
       "telegram",
       ["inlineButtons"],
@@ -299,6 +300,7 @@ describe("buildAgentSystemPrompt", () => {
     expect(line).toContain("os=macOS (arm64)");
     expect(line).toContain("node=v20");
     expect(line).toContain("model=anthropic/claude");
+    expect(line).toContain("default_model=anthropic/claude-opus-4-5");
     expect(line).toContain("channel=telegram");
     expect(line).toContain("capabilities=inlineButtons");
     expect(line).toContain("thinking=low");

src/agents/system-prompt.ts

@@ -582,6 +582,7 @@ export function buildRuntimeLine(
     arch?: string;
     node?: string;
     model?: string;
+    defaultModel?: string;
   },
   runtimeChannel?: string,
   runtimeCapabilities: string[] = [],
@@ -597,6 +598,7 @@ export function buildRuntimeLine(
         : "",
     runtimeInfo?.node ? `node=${runtimeInfo.node}` : "",
     runtimeInfo?.model ? `model=${runtimeInfo.model}` : "",
+    runtimeInfo?.defaultModel ? `default_model=${runtimeInfo.defaultModel}` : "",
     runtimeChannel ? `channel=${runtimeChannel}` : "",
     runtimeChannel
       ? `capabilities=${runtimeCapabilities.length > 0 ? runtimeCapabilities.join(",") : "none"}`

src/agents/tools/message-tool.ts

@@ -7,6 +7,7 @@ import {
   CHANNEL_MESSAGE_ACTION_NAMES,
   type ChannelMessageActionName,
 } from "../../channels/plugins/types.js";
+import { BLUEBUBBLES_GROUP_ACTIONS } from "../../channels/plugins/bluebubbles-actions.js";
 import type { ClawdbotConfig } from "../../config/config.js";
 import { loadConfig } from "../../config/config.js";
 import {
@@ -25,14 +26,6 @@ import type { AnyAgentTool } from "./common.js";
 import { jsonResult, readNumberParam, readStringParam } from "./common.js";
 
 const AllMessageActions = CHANNEL_MESSAGE_ACTION_NAMES;
-const BLUEBUBBLES_GROUP_ACTIONS = new Set<ChannelMessageActionName>([
-  "renameGroup",
-  "setGroupIcon",
-  "addParticipant",
-  "removeParticipant",
-  "leaveGroup",
-]);
-
 function buildRoutingSchema() {
   return {
     channel: Type.Optional(Type.String()),

src/agents/tools/web-search.test.ts

@@ -18,19 +18,13 @@ describe("web_search perplexity baseUrl defaults", () => {
   });
 
   it("prefers explicit baseUrl over key-based defaults", () => {
-    expect(
-      resolvePerplexityBaseUrl(
-        { baseUrl: "https://example.com" },
-        "config",
-        "pplx-123",
-      ),
-    ).toBe("https://example.com");
+    expect(resolvePerplexityBaseUrl({ baseUrl: "https://example.com" }, "config", "pplx-123")).toBe(
+      "https://example.com",
+    );
   });
 
   it("defaults to direct when using PERPLEXITY_API_KEY", () => {
-    expect(resolvePerplexityBaseUrl(undefined, "perplexity_env")).toBe(
-      "https://api.perplexity.ai",
-    );
+    expect(resolvePerplexityBaseUrl(undefined, "perplexity_env")).toBe("https://api.perplexity.ai");
   });
 
   it("defaults to OpenRouter when using OPENROUTER_API_KEY", () => {

src/auto-reply/commands-registry.data.ts

@@ -131,6 +131,26 @@ function buildChatCommands(): ChatCommandDefinition[] {
       description: "List all slash commands.",
       textAlias: "/commands",
     }),
+    defineChatCommand({
+      key: "skill",
+      nativeName: "skill",
+      description: "Run a skill by name.",
+      textAlias: "/skill",
+      args: [
+        {
+          name: "name",
+          description: "Skill name",
+          type: "string",
+          required: true,
+        },
+        {
+          name: "input",
+          description: "Skill input",
+          type: "string",
+          captureRemaining: true,
+        },
+      ],
+    }),
     defineChatCommand({
       key: "status",
       nativeName: "status",
@@ -292,12 +312,14 @@ function buildChatCommands(): ChatCommandDefinition[] {
       nativeName: "reset",
       description: "Reset the current session.",
       textAlias: "/reset",
+      acceptsArgs: true,
     }),
     defineChatCommand({
       key: "new",
       nativeName: "new",
       description: "Start a new session.",
       textAlias: "/new",
+      acceptsArgs: true,
     }),
     defineChatCommand({
       key: "compact",

src/auto-reply/commands-registry.test.ts

@@ -31,6 +31,7 @@ describe("commands registry", () => {
     const specs = listNativeCommandSpecs();
     expect(specs.find((spec) => spec.name === "help")).toBeTruthy();
     expect(specs.find((spec) => spec.name === "stop")).toBeTruthy();
+    expect(specs.find((spec) => spec.name === "skill")).toBeTruthy();
     expect(specs.find((spec) => spec.name === "whoami")).toBeTruthy();
     expect(specs.find((spec) => spec.name === "compact")).toBeFalsy();
   });
@@ -81,6 +82,7 @@ describe("commands registry", () => {
   it("detects known text commands", () => {
     const detection = getCommandDetection();
     expect(detection.exact.has("/commands")).toBe(true);
+    expect(detection.exact.has("/skill")).toBe(true);
     expect(detection.exact.has("/compact")).toBe(true);
     expect(detection.exact.has("/whoami")).toBe(true);
     expect(detection.exact.has("/id")).toBe(true);

src/auto-reply/reply/commands-context-report.ts

@@ -7,6 +7,7 @@ import { getSkillsSnapshotVersion } from "../../agents/skills/refresh.js";
 import { buildAgentSystemPrompt } from "../../agents/system-prompt.js";
 import { buildSystemPromptReport } from "../../agents/system-prompt-report.js";
 import { buildSystemPromptParams } from "../../agents/system-prompt-params.js";
+import { resolveDefaultModelForAgent } from "../../agents/model-selection.js";
 import { buildToolSummaryMap } from "../../agents/tool-summaries.js";
 import { resolveBootstrapContextForRun } from "../../agents/bootstrap-files.js";
 import type { SessionSystemPromptReport } from "../../config/sessions/types.js";
@@ -93,6 +94,11 @@ async function resolveContextReport(
     sessionKey: params.sessionKey,
     config: params.cfg,
   });
+  const defaultModelRef = resolveDefaultModelForAgent({
+    cfg: params.cfg,
+    agentId: sessionAgentId,
+  });
+  const defaultModelLabel = `${defaultModelRef.provider}/${defaultModelRef.model}`;
   const { runtimeInfo, userTimezone, userTime, userTimeFormat } = buildSystemPromptParams({
     config: params.cfg,
     agentId: sessionAgentId,
@@ -102,6 +108,7 @@ async function resolveContextReport(
       arch: "unknown",
       node: process.version,
       model: `${params.provider}/${params.model}`,
+      defaultModel: defaultModelLabel,
     },
   });
   const sandboxInfo = sandboxRuntime.sandboxed

src/auto-reply/reply/directive-handling.persist.ts

@@ -1,16 +1,15 @@
 import {
   resolveAgentDir,
-  resolveAgentModelPrimary,
   resolveDefaultAgentId,
   resolveSessionAgentId,
 } from "../../agents/agent-scope.js";
 import { lookupContextTokens } from "../../agents/context.js";
-import { DEFAULT_CONTEXT_TOKENS, DEFAULT_MODEL, DEFAULT_PROVIDER } from "../../agents/defaults.js";
+import { DEFAULT_CONTEXT_TOKENS } from "../../agents/defaults.js";
 import {
   buildModelAliasIndex,
   type ModelAliasIndex,
   modelKey,
-  resolveConfiguredModelRef,
+  resolveDefaultModelForAgent,
   resolveModelRefFromString,
 } from "../../agents/model-selection.js";
 import type { ClawdbotConfig } from "../../config/config.js";
@@ -239,36 +238,14 @@ export function resolveDefaultModel(params: { cfg: ClawdbotConfig; agentId?: str
   defaultModel: string;
   aliasIndex: ModelAliasIndex;
 } {
-  const agentModelOverride = params.agentId
-    ? resolveAgentModelPrimary(params.cfg, params.agentId)
-    : undefined;
-  const cfg =
-    agentModelOverride && agentModelOverride.length > 0
-      ? {
-          ...params.cfg,
-          agents: {
-            ...params.cfg.agents,
-            defaults: {
-              ...params.cfg.agents?.defaults,
-              model: {
-                ...(typeof params.cfg.agents?.defaults?.model === "object"
-                  ? params.cfg.agents.defaults.model
-                  : undefined),
-                primary: agentModelOverride,
-              },
-            },
-          },
-        }
-      : params.cfg;
-  const mainModel = resolveConfiguredModelRef({
-    cfg,
-    defaultProvider: DEFAULT_PROVIDER,
-    defaultModel: DEFAULT_MODEL,
+  const mainModel = resolveDefaultModelForAgent({
+    cfg: params.cfg,
+    agentId: params.agentId,
   });
   const defaultProvider = mainModel.provider;
   const defaultModel = mainModel.model;
   const aliasIndex = buildModelAliasIndex({
-    cfg,
+    cfg: params.cfg,
     defaultProvider,
   });
   return { defaultProvider, defaultModel, aliasIndex };

src/auto-reply/reply/get-reply-run.ts

@@ -38,6 +38,7 @@ import { SILENT_REPLY_TOKEN } from "../tokens.js";
 import type { GetReplyOptions, ReplyPayload } from "../types.js";
 import { runReplyAgent } from "./agent-runner.js";
 import { applySessionHints } from "./body.js";
+import { routeReply } from "./route-reply.js";
 import type { buildCommandContext } from "./commands.js";
 import type { InlineDirectives } from "./directive-handling.js";
 import { buildGroupIntro } from "./groups.js";
@@ -51,7 +52,7 @@ type AgentDefaults = NonNullable<ClawdbotConfig["agents"]>["defaults"];
 type ExecOverrides = Pick<ExecToolDefaults, "host" | "security" | "ask" | "node">;
 
 const BARE_SESSION_RESET_PROMPT =
-  "A new session was started via /new or /reset. Say hi briefly (1-2 sentences) and ask what the user wants to do next. Do not mention internal steps, files, tools, or reasoning.";
+  "A new session was started via /new or /reset. Say hi briefly (1-2 sentences) and ask what the user wants to do next. If the runtime model differs from default_model in the system prompt, mention the default model in the greeting. Do not mention internal steps, files, tools, or reasoning.";
 
 type RunPreparedReplyParams = {
   ctx: MsgContext;
@@ -92,9 +93,11 @@ type RunPreparedReplyParams = {
   };
   typing: TypingController;
   opts?: GetReplyOptions;
+  defaultProvider: string;
   defaultModel: string;
   timeoutMs: number;
   isNewSession: boolean;
+  resetTriggered: boolean;
   systemSent: boolean;
   sessionEntry?: SessionEntry;
   sessionStore?: Record<string, SessionEntry>;
@@ -220,9 +223,11 @@ export async function runPreparedReply(
     perMessageQueueOptions,
     typing,
     opts,
+    defaultProvider,
     defaultModel,
     timeoutMs,
     isNewSession,
+    resetTriggered,
     systemSent,
     sessionKey,
     sessionId,
@@ -369,6 +374,27 @@ export async function runPreparedReply(
       }
     }
   }
+  if (resetTriggered && command.isAuthorizedSender) {
+    const channel = ctx.OriginatingChannel || (command.channel as any);
+    const to = ctx.OriginatingTo || command.from || command.to;
+    if (channel && to) {
+      const modelLabel = `${provider}/${model}`;
+      const defaultLabel = `${defaultProvider}/${defaultModel}`;
+      const text =
+        modelLabel === defaultLabel
+          ? `✅ New session started · model: ${modelLabel}`
+          : `✅ New session started · model: ${modelLabel} (default: ${defaultLabel})`;
+      await routeReply({
+        payload: { text },
+        channel,
+        to,
+        sessionKey,
+        accountId: ctx.AccountId,
+        threadId: ctx.MessageThreadId,
+        cfg,
+      });
+    }
+  }
   const sessionIdFinal = sessionId ?? crypto.randomUUID();
   const sessionFile = resolveSessionFilePath(sessionIdFinal, sessionEntry);
   const queueBodyBase = [threadStarterNote, baseBodyFinal].filter(Boolean).join("\n\n");

src/auto-reply/reply/get-reply.ts

@@ -19,6 +19,7 @@ import { handleInlineActions } from "./get-reply-inline-actions.js";
 import { runPreparedReply } from "./get-reply-run.js";
 import { finalizeInboundContext } from "./inbound-context.js";
 import { initSessionState } from "./session.js";
+import { applyResetModelOverride } from "./session-reset-model.js";
 import { stageSandboxMedia } from "./stage-sandbox-media.js";
 import { createTypingController } from "./typing.js";
 
@@ -103,6 +104,7 @@ export async function getReplyFromConfig(
     sessionKey,
     sessionId,
     isNewSession,
+    resetTriggered,
     systemSent,
     abortedLastRun,
     storePath,
@@ -110,8 +112,24 @@ export async function getReplyFromConfig(
     groupResolution,
     isGroup,
     triggerBodyNormalized,
+    bodyStripped,
   } = sessionState;
 
+  await applyResetModelOverride({
+    cfg,
+    resetTriggered,
+    bodyStripped,
+    sessionCtx,
+    ctx: finalized,
+    sessionEntry,
+    sessionStore,
+    sessionKey,
+    storePath,
+    defaultProvider,
+    defaultModel,
+    aliasIndex,
+  });
+
   const directiveResult = await resolveReplyDirectives({
     ctx: finalized,
     cfg,
@@ -256,9 +274,11 @@ export async function getReplyFromConfig(
     perMessageQueueOptions,
     typing,
     opts,
+    defaultProvider,
     defaultModel,
     timeoutMs,
     isNewSession,
+    resetTriggered,
     systemSent,
     sessionEntry,
     sessionStore,

src/auto-reply/reply/session-reset-model.test.ts

@@ -0,0 +1,74 @@
+import { describe, expect, it, vi } from "vitest";
+
+import type { ClawdbotConfig } from "../../config/config.js";
+import { buildModelAliasIndex } from "../../agents/model-selection.js";
+import { applyResetModelOverride } from "./session-reset-model.js";
+
+vi.mock("../../agents/model-catalog.js", () => ({
+  loadModelCatalog: vi.fn(async () => [
+    { provider: "minimax", id: "m2.1", name: "M2.1" },
+    { provider: "openai", id: "gpt-4o-mini", name: "GPT-4o mini" },
+  ]),
+}));
+
+describe("applyResetModelOverride", () => {
+  it("selects a model hint and strips it from the body", async () => {
+    const cfg = {} as ClawdbotConfig;
+    const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: "openai" });
+    const sessionEntry = {
+      sessionId: "s1",
+      updatedAt: Date.now(),
+    };
+    const sessionStore = { "agent:main:dm:1": sessionEntry };
+    const sessionCtx = { BodyStripped: "minimax summarize" };
+    const ctx = { ChatType: "direct" };
+
+    await applyResetModelOverride({
+      cfg,
+      resetTriggered: true,
+      bodyStripped: "minimax summarize",
+      sessionCtx,
+      ctx,
+      sessionEntry,
+      sessionStore,
+      sessionKey: "agent:main:dm:1",
+      defaultProvider: "openai",
+      defaultModel: "gpt-4o-mini",
+      aliasIndex,
+    });
+
+    expect(sessionEntry.providerOverride).toBe("minimax");
+    expect(sessionEntry.modelOverride).toBe("m2.1");
+    expect(sessionCtx.BodyStripped).toBe("summarize");
+  });
+
+  it("skips when resetTriggered is false", async () => {
+    const cfg = {} as ClawdbotConfig;
+    const aliasIndex = buildModelAliasIndex({ cfg, defaultProvider: "openai" });
+    const sessionEntry = {
+      sessionId: "s1",
+      updatedAt: Date.now(),
+    };
+    const sessionStore = { "agent:main:dm:1": sessionEntry };
+    const sessionCtx = { BodyStripped: "minimax summarize" };
+    const ctx = { ChatType: "direct" };
+
+    await applyResetModelOverride({
+      cfg,
+      resetTriggered: false,
+      bodyStripped: "minimax summarize",
+      sessionCtx,
+      ctx,
+      sessionEntry,
+      sessionStore,
+      sessionKey: "agent:main:dm:1",
+      defaultProvider: "openai",
+      defaultModel: "gpt-4o-mini",
+      aliasIndex,
+    });
+
+    expect(sessionEntry.providerOverride).toBeUndefined();
+    expect(sessionEntry.modelOverride).toBeUndefined();
+    expect(sessionCtx.BodyStripped).toBe("minimax summarize");
+  });
+});

src/auto-reply/reply/session-reset-model.ts

@@ -0,0 +1,191 @@
+import { loadModelCatalog } from "../../agents/model-catalog.js";
+import {
+  buildAllowedModelSet,
+  modelKey,
+  normalizeProviderId,
+  resolveModelRefFromString,
+  type ModelAliasIndex,
+} from "../../agents/model-selection.js";
+import type { ClawdbotConfig } from "../../config/config.js";
+import type { SessionEntry } from "../../config/sessions.js";
+import { updateSessionStore } from "../../config/sessions.js";
+import type { MsgContext, TemplateContext } from "../templating.js";
+import { formatInboundBodyWithSenderMeta } from "./inbound-sender-meta.js";
+import { resolveModelDirectiveSelection, type ModelDirectiveSelection } from "./model-selection.js";
+
+type ResetModelResult = {
+  selection?: ModelDirectiveSelection;
+  cleanedBody?: string;
+};
+
+function splitBody(body: string) {
+  const tokens = body.split(/\s+/).filter(Boolean);
+  return {
+    tokens,
+    first: tokens[0],
+    second: tokens[1],
+    rest: tokens.slice(2),
+  };
+}
+
+function buildSelectionFromExplicit(params: {
+  raw: string;
+  defaultProvider: string;
+  defaultModel: string;
+  aliasIndex: ModelAliasIndex;
+  allowedModelKeys: Set<string>;
+}): ModelDirectiveSelection | undefined {
+  const resolved = resolveModelRefFromString({
+    raw: params.raw,
+    defaultProvider: params.defaultProvider,
+    aliasIndex: params.aliasIndex,
+  });
+  if (!resolved) return undefined;
+  const key = modelKey(resolved.ref.provider, resolved.ref.model);
+  if (params.allowedModelKeys.size > 0 && !params.allowedModelKeys.has(key)) return undefined;
+  const isDefault =
+    resolved.ref.provider === params.defaultProvider && resolved.ref.model === params.defaultModel;
+  return {
+    provider: resolved.ref.provider,
+    model: resolved.ref.model,
+    isDefault,
+    ...(resolved.alias ? { alias: resolved.alias } : undefined),
+  };
+}
+
+function applySelectionToSession(params: {
+  selection: ModelDirectiveSelection;
+  sessionEntry?: SessionEntry;
+  sessionStore?: Record<string, SessionEntry>;
+  sessionKey?: string;
+  storePath?: string;
+}) {
+  const { selection, sessionEntry, sessionStore, sessionKey, storePath } = params;
+  if (!sessionEntry || !sessionStore || !sessionKey) return;
+  let updated = false;
+  if (selection.isDefault) {
+    if (sessionEntry.providerOverride || sessionEntry.modelOverride) {
+      delete sessionEntry.providerOverride;
+      delete sessionEntry.modelOverride;
+      updated = true;
+    }
+  } else {
+    if (sessionEntry.providerOverride !== selection.provider) {
+      sessionEntry.providerOverride = selection.provider;
+      updated = true;
+    }
+    if (sessionEntry.modelOverride !== selection.model) {
+      sessionEntry.modelOverride = selection.model;
+      updated = true;
+    }
+  }
+  if (!updated) return;
+  sessionEntry.updatedAt = Date.now();
+  sessionStore[sessionKey] = sessionEntry;
+  if (storePath) {
+    updateSessionStore(storePath, (store) => {
+      store[sessionKey] = sessionEntry;
+    }).catch(() => {
+      // Ignore persistence errors; session still proceeds.
+    });
+  }
+}
+
+export async function applyResetModelOverride(params: {
+  cfg: ClawdbotConfig;
+  resetTriggered: boolean;
+  bodyStripped?: string;
+  sessionCtx: TemplateContext;
+  ctx: MsgContext;
+  sessionEntry?: SessionEntry;
+  sessionStore?: Record<string, SessionEntry>;
+  sessionKey?: string;
+  storePath?: string;
+  defaultProvider: string;
+  defaultModel: string;
+  aliasIndex: ModelAliasIndex;
+}): Promise<ResetModelResult> {
+  if (!params.resetTriggered) return {};
+  const rawBody = params.bodyStripped?.trim();
+  if (!rawBody) return {};
+
+  const { tokens, first, second } = splitBody(rawBody);
+  if (!first) return {};
+
+  const catalog = await loadModelCatalog({ config: params.cfg });
+  const allowed = buildAllowedModelSet({
+    cfg: params.cfg,
+    catalog,
+    defaultProvider: params.defaultProvider,
+    defaultModel: params.defaultModel,
+  });
+  const allowedModelKeys = allowed.allowedKeys;
+  if (allowedModelKeys.size === 0) return {};
+
+  const providers = new Set<string>();
+  for (const key of allowedModelKeys) {
+    const slash = key.indexOf("/");
+    if (slash <= 0) continue;
+    providers.add(normalizeProviderId(key.slice(0, slash)));
+  }
+
+  const resolveSelection = (raw: string) =>
+    resolveModelDirectiveSelection({
+      raw,
+      defaultProvider: params.defaultProvider,
+      defaultModel: params.defaultModel,
+      aliasIndex: params.aliasIndex,
+      allowedModelKeys,
+    });
+
+  let selection: ModelDirectiveSelection | undefined;
+  let consumed = 0;
+
+  if (providers.has(normalizeProviderId(first)) && second) {
+    const composite = `${normalizeProviderId(first)}/${second}`;
+    const resolved = resolveSelection(composite);
+    if (resolved.selection) {
+      selection = resolved.selection;
+      consumed = 2;
+    }
+  }
+
+  if (!selection) {
+    selection = buildSelectionFromExplicit({
+      raw: first,
+      defaultProvider: params.defaultProvider,
+      defaultModel: params.defaultModel,
+      aliasIndex: params.aliasIndex,
+      allowedModelKeys,
+    });
+    if (selection) consumed = 1;
+  }
+
+  if (!selection) {
+    const resolved = resolveSelection(first);
+    const allowFuzzy = providers.has(normalizeProviderId(first)) || first.trim().length >= 6;
+    if (allowFuzzy) {
+      selection = resolved.selection;
+      if (selection) consumed = 1;
+    }
+  }
+
+  if (!selection) return {};
+
+  const cleanedBody = tokens.slice(consumed).join(" ").trim();
+  params.sessionCtx.BodyStripped = formatInboundBodyWithSenderMeta({
+    ctx: params.ctx,
+    body: cleanedBody,
+  });
+  params.sessionCtx.BodyForCommands = cleanedBody;
+
+  applySelectionToSession({
+    selection,
+    sessionEntry: params.sessionEntry,
+    sessionStore: params.sessionStore,
+    sessionKey: params.sessionKey,
+    storePath: params.storePath,
+  });
+
+  return { selection, cleanedBody };
+}

src/auto-reply/reply/session.test.ts

@@ -151,6 +151,34 @@ describe("initSessionState RawBody", () => {
     expect(result.bodyStripped).toBe("");
   });
 
+  it("preserves argument casing while still matching reset triggers case-insensitively", async () => {
+    const root = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-rawbody-reset-case-"));
+    const storePath = path.join(root, "sessions.json");
+
+    const cfg = {
+      session: {
+        store: storePath,
+        resetTriggers: ["/new"],
+      },
+    } as ClawdbotConfig;
+
+    const ctx = {
+      RawBody: "/NEW KeepThisCase",
+      ChatType: "direct",
+      SessionKey: "agent:main:whatsapp:dm:S1",
+    };
+
+    const result = await initSessionState({
+      ctx,
+      cfg,
+      commandAuthorized: true,
+    });
+
+    expect(result.isNewSession).toBe(true);
+    expect(result.bodyStripped).toBe("KeepThisCase");
+    expect(result.triggerBodyNormalized).toBe("/NEW KeepThisCase");
+  });
+
   it("falls back to Body when RawBody is undefined", async () => {
     const root = await fs.mkdtemp(path.join(os.tmpdir(), "clawdbot-rawbody-fallback-"));
     const storePath = path.join(root, "sessions.json");

src/auto-reply/reply/session.ts

@@ -40,6 +40,7 @@ export type SessionInitResult = {
   sessionKey: string;
   sessionId: string;
   isNewSession: boolean;
+  resetTriggered: boolean;
   systemSent: boolean;
   abortedLastRun: boolean;
   storePath: string;
@@ -135,7 +136,10 @@ export async function initSessionState(params: {
   // Prefer CommandBody/RawBody (clean message) for command detection; fall back
   // to Body which may contain structural context (history, sender labels).
   const commandSource = ctx.BodyForCommands ?? ctx.CommandBody ?? ctx.RawBody ?? ctx.Body ?? "";
-  const triggerBodyNormalized = stripStructuralPrefixes(commandSource).trim().toLowerCase();
+  // IMPORTANT: do NOT lowercase the entire command body.
+  // Users often pass case-sensitive arguments (e.g. filesystem paths on Linux).
+  // Command parsing downstream lowercases only the command token for matching.
+  const triggerBodyNormalized = stripStructuralPrefixes(commandSource).trim();
 
   // Use CommandBody/RawBody for reset trigger matching (clean message without structural context).
   const rawBody = commandSource;
@@ -151,17 +155,27 @@ export async function initSessionState(params: {
   const strippedForReset = isGroup
     ? stripMentions(triggerBodyNormalized, ctx, cfg, agentId)
     : triggerBodyNormalized;
+
+  // Reset triggers are configured as lowercased commands (e.g. "/new"), but users may type
+  // "/NEW" etc. Match case-insensitively while keeping the original casing for any stripped body.
+  const trimmedBodyLower = trimmedBody.toLowerCase();
+  const strippedForResetLower = strippedForReset.toLowerCase();
+
   for (const trigger of resetTriggers) {
     if (!trigger) continue;
     if (!resetAuthorized) break;
-    if (trimmedBody === trigger || strippedForReset === trigger) {
+    const triggerLower = trigger.toLowerCase();
+    if (trimmedBodyLower === triggerLower || strippedForResetLower === triggerLower) {
       isNewSession = true;
       bodyStripped = "";
       resetTriggered = true;
       break;
     }
-    const triggerPrefix = `${trigger} `;
-    if (trimmedBody.startsWith(triggerPrefix) || strippedForReset.startsWith(triggerPrefix)) {
+    const triggerPrefixLower = `${triggerLower} `;
+    if (
+      trimmedBodyLower.startsWith(triggerPrefixLower) ||
+      strippedForResetLower.startsWith(triggerPrefixLower)
+    ) {
       isNewSession = true;
       bodyStripped = strippedForReset.slice(trigger.length).trimStart();
       resetTriggered = true;
@@ -327,6 +341,7 @@ export async function initSessionState(params: {
     sessionKey,
     sessionId: sessionId ?? crypto.randomUUID(),
     isNewSession,
+    resetTriggered,
     systemSent,
     abortedLastRun,
     storePath,

src/auto-reply/skill-commands.test.ts

@@ -30,6 +30,24 @@ describe("resolveSkillCommandInvocation", () => {
     expect(invocation?.args).toBe("do the thing");
   });
 
+  it("supports /skill with name argument", () => {
+    const invocation = resolveSkillCommandInvocation({
+      commandBodyNormalized: "/skill demo_skill do the thing",
+      skillCommands: [{ name: "demo_skill", skillName: "demo-skill", description: "Demo" }],
+    });
+    expect(invocation?.command.name).toBe("demo_skill");
+    expect(invocation?.args).toBe("do the thing");
+  });
+
+  it("normalizes /skill lookup names", () => {
+    const invocation = resolveSkillCommandInvocation({
+      commandBodyNormalized: "/skill demo-skill",
+      skillCommands: [{ name: "demo_skill", skillName: "demo-skill", description: "Demo" }],
+    });
+    expect(invocation?.command.name).toBe("demo_skill");
+    expect(invocation?.args).toBeUndefined();
+  });
+
   it("returns null for unknown commands", () => {
     const invocation = resolveSkillCommandInvocation({
       commandBodyNormalized: "/unknown arg",

src/auto-reply/skill-commands.ts

@@ -55,6 +55,31 @@ export function listSkillCommandsForAgents(params: {
   return entries;
 }
 
+function normalizeSkillCommandLookup(value: string): string {
+  return value
+    .trim()
+    .toLowerCase()
+    .replace(/[\s_]+/g, "-");
+}
+
+function findSkillCommand(
+  skillCommands: SkillCommandSpec[],
+  rawName: string,
+): SkillCommandSpec | undefined {
+  const trimmed = rawName.trim();
+  if (!trimmed) return undefined;
+  const lowered = trimmed.toLowerCase();
+  const normalized = normalizeSkillCommandLookup(trimmed);
+  return skillCommands.find((entry) => {
+    if (entry.name.toLowerCase() === lowered) return true;
+    if (entry.skillName.toLowerCase() === lowered) return true;
+    return (
+      normalizeSkillCommandLookup(entry.name) === normalized ||
+      normalizeSkillCommandLookup(entry.skillName) === normalized
+    );
+  });
+}
+
 export function resolveSkillCommandInvocation(params: {
   commandBodyNormalized: string;
   skillCommands: SkillCommandSpec[];
@@ -65,6 +90,16 @@ export function resolveSkillCommandInvocation(params: {
   if (!match) return null;
   const commandName = match[1]?.trim().toLowerCase();
   if (!commandName) return null;
+  if (commandName === "skill") {
+    const remainder = match[2]?.trim();
+    if (!remainder) return null;
+    const skillMatch = remainder.match(/^([^\s]+)(?:\s+([\s\S]+))?$/);
+    if (!skillMatch) return null;
+    const skillCommand = findSkillCommand(params.skillCommands, skillMatch[1] ?? "");
+    if (!skillCommand) return null;
+    const args = skillMatch[2]?.trim();
+    return { command: skillCommand, args: args || undefined };
+  }
   const command = params.skillCommands.find((entry) => entry.name.toLowerCase() === commandName);
   if (!command) return null;
   const args = match[2]?.trim();

src/auto-reply/status.test.ts

@@ -366,6 +366,7 @@ describe("buildCommandsMessage", () => {
       commands: { config: false, debug: false },
     } as ClawdbotConfig);
     expect(text).toContain("/commands - List all slash commands.");
+    expect(text).toContain("/skill - Run a skill by name.");
     expect(text).toContain("/think (aliases: /thinking, /t) - Set thinking level.");
     expect(text).toContain("/compact (text-only) - Compact the session context.");
     expect(text).not.toContain("/config");
@@ -394,6 +395,7 @@ describe("buildHelpMessage", () => {
     const text = buildHelpMessage({
       commands: { config: false, debug: false },
     } as ClawdbotConfig);
+    expect(text).toContain("Skills: /skill <name> [input]");
     expect(text).not.toContain("/config");
     expect(text).not.toContain("/debug");
   });

src/auto-reply/status.ts

@@ -391,6 +391,7 @@ export function buildHelpMessage(cfg?: ClawdbotConfig): string {
     "ℹ️ Help",
     "Shortcuts: /new reset | /compact [instructions] | /restart relink (if enabled)",
     `Options: ${options.join(" | ")}`,
+    "Skills: /skill <name> [input]",
     "More: /commands for all slash commands",
   ].join("\n");
 }

src/browser/pw-ai.test.ts

@@ -84,6 +84,35 @@ describe("pw-ai", () => {
     expect(p2.session.detach).toHaveBeenCalledTimes(1);
   });
 
+  it("registers aria refs from ai snapshots for act commands", async () => {
+    const { chromium } = await import("playwright-core");
+    const snapshot = ['- button "OK" [ref=e1]', '- link "Docs" [ref=e2]'].join("\n");
+    const p1 = createPage({ targetId: "T1", snapshotFull: snapshot });
+    const browser = createBrowser([p1.page]);
+
+    (chromium.connectOverCDP as unknown as ReturnType<typeof vi.fn>).mockResolvedValue(browser);
+
+    const mod = await importModule();
+    const res = await mod.snapshotAiViaPlaywright({
+      cdpUrl: "http://127.0.0.1:18792",
+      targetId: "T1",
+    });
+
+    expect(res.refs).toMatchObject({
+      e1: { role: "button", name: "OK" },
+      e2: { role: "link", name: "Docs" },
+    });
+
+    await mod.clickViaPlaywright({
+      cdpUrl: "http://127.0.0.1:18792",
+      targetId: "T1",
+      ref: "e1",
+    });
+
+    expect(p1.locator).toHaveBeenCalledWith("aria-ref=e1");
+    expect(p1.click).toHaveBeenCalledTimes(1);
+  });
+
   it("truncates oversized snapshots", async () => {
     const { chromium } = await import("playwright-core");
     const longSnapshot = "A".repeat(20);