@kodelyth/matrix 2026.5.42 → 2026.6.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (205) hide show
  1. package/klaw.plugin.json +891 -3
  2. package/package.json +18 -6
  3. package/CHANGELOG.md +0 -321
  4. package/SPEC-SUPPORT.md +0 -116
  5. package/api.ts +0 -38
  6. package/auth-presence.ts +0 -56
  7. package/channel-plugin-api.ts +0 -3
  8. package/cli-metadata.ts +0 -11
  9. package/contract-api.ts +0 -17
  10. package/doctor-contract-api.ts +0 -1
  11. package/helper-api.ts +0 -3
  12. package/index.ts +0 -55
  13. package/plugin-entry.handlers.runtime.ts +0 -1
  14. package/runtime-api.ts +0 -72
  15. package/runtime-heavy-api.ts +0 -1
  16. package/runtime-setter-api.ts +0 -3
  17. package/secret-contract-api.ts +0 -5
  18. package/setup-entry.ts +0 -17
  19. package/setup-plugin-api.ts +0 -3
  20. package/src/account-selection.ts +0 -223
  21. package/src/actions.ts +0 -346
  22. package/src/approval-auth.ts +0 -25
  23. package/src/approval-handler.runtime.ts +0 -592
  24. package/src/approval-ids.ts +0 -6
  25. package/src/approval-native.ts +0 -345
  26. package/src/approval-reaction-auth.ts +0 -45
  27. package/src/approval-reactions.ts +0 -313
  28. package/src/auth-precedence.ts +0 -61
  29. package/src/channel-account-paths.ts +0 -97
  30. package/src/channel.runtime.ts +0 -17
  31. package/src/channel.setup.ts +0 -48
  32. package/src/channel.ts +0 -667
  33. package/src/cli-metadata.ts +0 -19
  34. package/src/cli.ts +0 -2298
  35. package/src/config-adapter.ts +0 -41
  36. package/src/config-schema.ts +0 -159
  37. package/src/config-ui-hints.ts +0 -56
  38. package/src/directory-live.ts +0 -238
  39. package/src/doctor-contract.ts +0 -287
  40. package/src/doctor.ts +0 -262
  41. package/src/env-vars.ts +0 -92
  42. package/src/exec-approval-resolver.ts +0 -23
  43. package/src/exec-approvals.ts +0 -287
  44. package/src/group-mentions.ts +0 -41
  45. package/src/legacy-crypto-inspector-availability.ts +0 -60
  46. package/src/legacy-crypto.ts +0 -531
  47. package/src/legacy-state.ts +0 -156
  48. package/src/matrix/account-config.ts +0 -175
  49. package/src/matrix/accounts.ts +0 -194
  50. package/src/matrix/actions/client.ts +0 -31
  51. package/src/matrix/actions/devices.ts +0 -34
  52. package/src/matrix/actions/limits.ts +0 -6
  53. package/src/matrix/actions/messages.ts +0 -129
  54. package/src/matrix/actions/pins.ts +0 -63
  55. package/src/matrix/actions/polls.ts +0 -109
  56. package/src/matrix/actions/profile.ts +0 -37
  57. package/src/matrix/actions/reactions.ts +0 -59
  58. package/src/matrix/actions/room.ts +0 -71
  59. package/src/matrix/actions/summary.ts +0 -88
  60. package/src/matrix/actions/types.ts +0 -63
  61. package/src/matrix/actions/verification.ts +0 -589
  62. package/src/matrix/actions.ts +0 -37
  63. package/src/matrix/active-client.ts +0 -26
  64. package/src/matrix/async-lock.ts +0 -18
  65. package/src/matrix/backup-health.ts +0 -124
  66. package/src/matrix/client/config-runtime-api.ts +0 -9
  67. package/src/matrix/client/config-secret-input.runtime.ts +0 -1
  68. package/src/matrix/client/config.ts +0 -853
  69. package/src/matrix/client/create-client.ts +0 -105
  70. package/src/matrix/client/env-auth.ts +0 -95
  71. package/src/matrix/client/file-sync-store.ts +0 -289
  72. package/src/matrix/client/logging.ts +0 -140
  73. package/src/matrix/client/migration-snapshot.runtime.ts +0 -1
  74. package/src/matrix/client/private-network-host.ts +0 -1
  75. package/src/matrix/client/runtime.ts +0 -4
  76. package/src/matrix/client/shared.ts +0 -316
  77. package/src/matrix/client/storage.ts +0 -543
  78. package/src/matrix/client/types.ts +0 -50
  79. package/src/matrix/client/url-validation.ts +0 -73
  80. package/src/matrix/client-bootstrap.ts +0 -173
  81. package/src/matrix/client.ts +0 -23
  82. package/src/matrix/config-paths.ts +0 -31
  83. package/src/matrix/config-update.ts +0 -292
  84. package/src/matrix/credentials-read.ts +0 -208
  85. package/src/matrix/credentials-write.runtime.ts +0 -35
  86. package/src/matrix/credentials.ts +0 -95
  87. package/src/matrix/deps.ts +0 -309
  88. package/src/matrix/device-health.ts +0 -29
  89. package/src/matrix/direct-management.ts +0 -349
  90. package/src/matrix/direct-room.ts +0 -128
  91. package/src/matrix/draft-stream.ts +0 -225
  92. package/src/matrix/encryption-guidance.ts +0 -24
  93. package/src/matrix/errors.ts +0 -21
  94. package/src/matrix/format.ts +0 -426
  95. package/src/matrix/legacy-crypto-inspector.ts +0 -95
  96. package/src/matrix/media-errors.ts +0 -20
  97. package/src/matrix/media-text.ts +0 -162
  98. package/src/matrix/monitor/access-state.ts +0 -145
  99. package/src/matrix/monitor/ack-config.ts +0 -27
  100. package/src/matrix/monitor/allowlist.ts +0 -89
  101. package/src/matrix/monitor/auto-join.ts +0 -86
  102. package/src/matrix/monitor/config.ts +0 -569
  103. package/src/matrix/monitor/context-summary.ts +0 -43
  104. package/src/matrix/monitor/direct.ts +0 -296
  105. package/src/matrix/monitor/events.ts +0 -397
  106. package/src/matrix/monitor/handler.ts +0 -2266
  107. package/src/matrix/monitor/inbound-dedupe.ts +0 -267
  108. package/src/matrix/monitor/index.ts +0 -540
  109. package/src/matrix/monitor/legacy-crypto-restore.ts +0 -139
  110. package/src/matrix/monitor/location.ts +0 -108
  111. package/src/matrix/monitor/media.ts +0 -119
  112. package/src/matrix/monitor/mentions.ts +0 -256
  113. package/src/matrix/monitor/reaction-events.ts +0 -197
  114. package/src/matrix/monitor/recent-invite.ts +0 -30
  115. package/src/matrix/monitor/replies.ts +0 -136
  116. package/src/matrix/monitor/reply-context.ts +0 -92
  117. package/src/matrix/monitor/room-history.ts +0 -301
  118. package/src/matrix/monitor/room-info.ts +0 -126
  119. package/src/matrix/monitor/rooms.ts +0 -52
  120. package/src/matrix/monitor/route.ts +0 -179
  121. package/src/matrix/monitor/runtime-api.ts +0 -28
  122. package/src/matrix/monitor/startup-verification.ts +0 -237
  123. package/src/matrix/monitor/startup.ts +0 -218
  124. package/src/matrix/monitor/status.ts +0 -120
  125. package/src/matrix/monitor/sync-lifecycle.ts +0 -91
  126. package/src/matrix/monitor/task-runner.ts +0 -38
  127. package/src/matrix/monitor/test-events.ts +0 -21
  128. package/src/matrix/monitor/thread-context.ts +0 -108
  129. package/src/matrix/monitor/threads.ts +0 -85
  130. package/src/matrix/monitor/types.ts +0 -30
  131. package/src/matrix/monitor/verification-events.ts +0 -643
  132. package/src/matrix/monitor/verification-utils.ts +0 -46
  133. package/src/matrix/outbound-media-runtime.ts +0 -1
  134. package/src/matrix/poll-summary.ts +0 -110
  135. package/src/matrix/poll-types.ts +0 -429
  136. package/src/matrix/probe.runtime.ts +0 -4
  137. package/src/matrix/probe.ts +0 -97
  138. package/src/matrix/profile.ts +0 -184
  139. package/src/matrix/reaction-common.ts +0 -147
  140. package/src/matrix/sdk/crypto-bootstrap.ts +0 -438
  141. package/src/matrix/sdk/crypto-facade.ts +0 -242
  142. package/src/matrix/sdk/crypto-node.runtime.ts +0 -17
  143. package/src/matrix/sdk/crypto-runtime.ts +0 -14
  144. package/src/matrix/sdk/decrypt-bridge.ts +0 -410
  145. package/src/matrix/sdk/event-helpers.ts +0 -83
  146. package/src/matrix/sdk/http-client.ts +0 -87
  147. package/src/matrix/sdk/idb-persistence-lock.ts +0 -51
  148. package/src/matrix/sdk/idb-persistence.ts +0 -288
  149. package/src/matrix/sdk/logger.ts +0 -108
  150. package/src/matrix/sdk/read-response-with-limit.ts +0 -19
  151. package/src/matrix/sdk/recovery-key-store.ts +0 -453
  152. package/src/matrix/sdk/timeout-abort-signal.ts +0 -1
  153. package/src/matrix/sdk/transport-runtime-api.ts +0 -18
  154. package/src/matrix/sdk/transport.ts +0 -352
  155. package/src/matrix/sdk/types.ts +0 -245
  156. package/src/matrix/sdk/verification-manager.ts +0 -795
  157. package/src/matrix/sdk/verification-status.ts +0 -23
  158. package/src/matrix/sdk.ts +0 -2152
  159. package/src/matrix/send/client.ts +0 -93
  160. package/src/matrix/send/formatting.ts +0 -189
  161. package/src/matrix/send/media.ts +0 -244
  162. package/src/matrix/send/targets.ts +0 -104
  163. package/src/matrix/send/types.ts +0 -131
  164. package/src/matrix/send.ts +0 -660
  165. package/src/matrix/session-store-metadata.ts +0 -108
  166. package/src/matrix/startup-abort.ts +0 -44
  167. package/src/matrix/subagent-hooks.ts +0 -308
  168. package/src/matrix/sync-state.ts +0 -27
  169. package/src/matrix/target-ids.ts +0 -79
  170. package/src/matrix/thread-bindings-shared.ts +0 -206
  171. package/src/matrix/thread-bindings.ts +0 -580
  172. package/src/matrix-migration.runtime.ts +0 -9
  173. package/src/migration-config.ts +0 -243
  174. package/src/migration-snapshot-backup.ts +0 -116
  175. package/src/migration-snapshot.ts +0 -53
  176. package/src/onboarding.ts +0 -775
  177. package/src/outbound.ts +0 -248
  178. package/src/plugin-entry.runtime.js +0 -115
  179. package/src/plugin-entry.runtime.ts +0 -70
  180. package/src/profile-update.ts +0 -71
  181. package/src/record-shared.ts +0 -3
  182. package/src/resolve-targets.ts +0 -175
  183. package/src/resolver.runtime.ts +0 -5
  184. package/src/resolver.ts +0 -21
  185. package/src/runtime-api.ts +0 -106
  186. package/src/runtime.ts +0 -13
  187. package/src/secret-contract.ts +0 -174
  188. package/src/session-route.ts +0 -126
  189. package/src/setup-bootstrap.ts +0 -102
  190. package/src/setup-config.ts +0 -222
  191. package/src/setup-contract.ts +0 -90
  192. package/src/setup-core.ts +0 -146
  193. package/src/setup-dm-policy.ts +0 -15
  194. package/src/setup-surface.ts +0 -4
  195. package/src/startup-maintenance.ts +0 -114
  196. package/src/storage-paths.ts +0 -92
  197. package/src/thread-binding-api.ts +0 -23
  198. package/src/tool-actions.runtime.ts +0 -1
  199. package/src/tool-actions.ts +0 -498
  200. package/src/types.ts +0 -257
  201. package/subagent-hooks-api.ts +0 -31
  202. package/test-api.ts +0 -21
  203. package/thread-binding-api.ts +0 -4
  204. package/thread-bindings-runtime.ts +0 -4
  205. package/tsconfig.json +0 -16
package/src/channel.ts DELETED
@@ -1,667 +0,0 @@
1
- import { describeAccountSnapshot } from "klaw/plugin-sdk/account-helpers";
2
- import {
3
- adaptScopedAccountAccessor,
4
- createScopedDmSecurityResolver,
5
- } from "klaw/plugin-sdk/channel-config-helpers";
6
- import type { ChannelDoctorAdapter } from "klaw/plugin-sdk/channel-contract";
7
- import { createChatChannelPlugin, type ChannelPlugin } from "klaw/plugin-sdk/channel-core";
8
- import { createChannelMessageAdapterFromOutbound } from "klaw/plugin-sdk/channel-message";
9
- import {
10
- createAllowlistProviderOpenWarningCollector,
11
- projectAccountConfigWarningCollector,
12
- } from "klaw/plugin-sdk/channel-policy";
13
- import type { ChannelOutboundAdapter } from "klaw/plugin-sdk/channel-send-result";
14
- import { createScopedAccountReplyToModeResolver } from "klaw/plugin-sdk/conversation-runtime";
15
- import {
16
- createChannelDirectoryAdapter,
17
- createResolvedDirectoryEntriesLister,
18
- createRuntimeDirectoryLiveAdapter,
19
- } from "klaw/plugin-sdk/directory-runtime";
20
- import { createLazyRuntimeNamedExport } from "klaw/plugin-sdk/lazy-runtime";
21
- import { createRuntimeOutboundDelegates } from "klaw/plugin-sdk/outbound-runtime";
22
- import {
23
- buildProbeChannelStatusSummary,
24
- collectStatusIssuesFromLastError,
25
- createComputedAccountStatusAdapter,
26
- createDefaultChannelRuntimeState,
27
- } from "klaw/plugin-sdk/status-helpers";
28
- import {
29
- normalizeLowercaseStringOrEmpty,
30
- normalizeOptionalString,
31
- } from "klaw/plugin-sdk/string-coerce-runtime";
32
- import { chunkTextForOutbound } from "klaw/plugin-sdk/text-chunking";
33
- import { matrixMessageActions } from "./actions.js";
34
- import { matrixApprovalCapability } from "./approval-native.js";
35
- import { createMatrixPairingText, createMatrixProbeAccount } from "./channel-account-paths.js";
36
- import { DEFAULT_ACCOUNT_ID, matrixConfigAdapter } from "./config-adapter.js";
37
- import { MatrixChannelConfigSchema } from "./config-schema.js";
38
- import {
39
- legacyConfigRules as MATRIX_LEGACY_CONFIG_RULES,
40
- normalizeCompatibilityConfig as normalizeMatrixCompatibilityConfig,
41
- } from "./doctor-contract.js";
42
- import { shouldSuppressLocalMatrixExecApprovalPrompt } from "./exec-approvals.js";
43
- import {
44
- resolveMatrixGroupRequireMention,
45
- resolveMatrixGroupToolPolicy,
46
- } from "./group-mentions.js";
47
- import {
48
- resolveMatrixAccount,
49
- resolveMatrixAccountConfig,
50
- type ResolvedMatrixAccount,
51
- } from "./matrix/accounts.js";
52
- import { normalizeMatrixUserId } from "./matrix/monitor/allowlist.js";
53
- import type { MatrixProbe } from "./matrix/probe.js";
54
- import {
55
- normalizeMatrixMessagingTarget,
56
- resolveMatrixDirectUserId,
57
- resolveMatrixTargetIdentity,
58
- } from "./matrix/target-ids.js";
59
- import {
60
- setMatrixThreadBindingIdleTimeoutBySessionKey,
61
- setMatrixThreadBindingMaxAgeBySessionKey,
62
- } from "./matrix/thread-bindings-shared.js";
63
- import { matrixResolverAdapter } from "./resolver.js";
64
- import { collectRuntimeConfigAssignments, secretTargetRegistryEntries } from "./secret-contract.js";
65
- import { resolveMatrixOutboundSessionRoute } from "./session-route.js";
66
- import {
67
- namedAccountPromotionKeys,
68
- resolveSingleAccountPromotionTarget,
69
- singleAccountKeysToMove,
70
- } from "./setup-contract.js";
71
- import { createMatrixSetupWizardProxy, matrixSetupAdapter } from "./setup-core.js";
72
- import { runMatrixStartupMaintenance } from "./startup-maintenance.js";
73
- import { resolveMatrixInboundConversation } from "./thread-binding-api.js";
74
- import type { CoreConfig } from "./types.js";
75
- // Mutex for serializing account startup (workaround for concurrent dynamic import race condition)
76
- let matrixStartupLock: Promise<void> = Promise.resolve();
77
-
78
- const loadMatrixSetupWizard = createLazyRuntimeNamedExport(
79
- () => import("./setup-surface.js"),
80
- "matrixSetupWizard",
81
- );
82
- const loadMatrixChannelRuntime = createLazyRuntimeNamedExport(
83
- () => import("./channel.runtime.js"),
84
- "matrixChannelRuntime",
85
- );
86
-
87
- const meta = {
88
- id: "matrix",
89
- label: "Matrix",
90
- selectionLabel: "Matrix (plugin)",
91
- docsPath: "/channels/matrix",
92
- docsLabel: "matrix",
93
- blurb: "open protocol; configure a homeserver + access token.",
94
- order: 70,
95
- quickstartAllowFrom: true,
96
- };
97
-
98
- function buildMatrixTrafficStatusSummary(
99
- snapshot?: {
100
- lastInboundAt?: number | null;
101
- lastOutboundAt?: number | null;
102
- } | null,
103
- ) {
104
- return {
105
- lastInboundAt: snapshot?.lastInboundAt ?? null,
106
- lastOutboundAt: snapshot?.lastOutboundAt ?? null,
107
- };
108
- }
109
-
110
- const matrixDoctor: ChannelDoctorAdapter = {
111
- dmAllowFromMode: "nestedOnly",
112
- groupModel: "sender",
113
- groupAllowFromFallbackToAllowFrom: false,
114
- warnOnEmptyGroupSenderAllowlist: true,
115
- legacyConfigRules: MATRIX_LEGACY_CONFIG_RULES,
116
- normalizeCompatibilityConfig: normalizeMatrixCompatibilityConfig,
117
- runConfigSequence: async ({ cfg, env, shouldRepair }) =>
118
- await (await import("./doctor.js")).runMatrixDoctorSequence({ cfg, env, shouldRepair }),
119
- cleanStaleConfig: async ({ cfg }) =>
120
- await (await import("./doctor.js")).cleanStaleMatrixPluginConfig(cfg),
121
- };
122
-
123
- const listMatrixDirectoryPeersFromConfig =
124
- createResolvedDirectoryEntriesLister<ResolvedMatrixAccount>({
125
- kind: "user",
126
- resolveAccount: adaptScopedAccountAccessor(resolveMatrixAccount),
127
- resolveSources: (account) => [
128
- account.config.dm?.allowFrom ?? [],
129
- account.config.groupAllowFrom ?? [],
130
- ...Object.values(account.config.groups ?? account.config.rooms ?? {}).map(
131
- (room) => room.users ?? [],
132
- ),
133
- ],
134
- normalizeId: (entry) => {
135
- const raw = entry.replace(/^matrix:/i, "").trim();
136
- if (!raw || raw === "*") {
137
- return null;
138
- }
139
- const lowered = normalizeLowercaseStringOrEmpty(raw);
140
- const cleaned = lowered.startsWith("user:") ? raw.slice("user:".length).trim() : raw;
141
- return cleaned.startsWith("@") ? `user:${cleaned}` : cleaned;
142
- },
143
- });
144
-
145
- const listMatrixDirectoryGroupsFromConfig =
146
- createResolvedDirectoryEntriesLister<ResolvedMatrixAccount>({
147
- kind: "group",
148
- resolveAccount: adaptScopedAccountAccessor(resolveMatrixAccount),
149
- resolveSources: (account) => [Object.keys(account.config.groups ?? account.config.rooms ?? {})],
150
- normalizeId: (entry) => {
151
- const raw = entry.replace(/^matrix:/i, "").trim();
152
- if (!raw || raw === "*") {
153
- return null;
154
- }
155
- const lowered = normalizeLowercaseStringOrEmpty(raw);
156
- if (lowered.startsWith("room:") || lowered.startsWith("channel:")) {
157
- return raw;
158
- }
159
- return raw.startsWith("!") ? `room:${raw}` : raw;
160
- },
161
- });
162
-
163
- function projectMatrixConversationBinding(binding: {
164
- boundAt: number;
165
- metadata?: {
166
- lastActivityAt?: number;
167
- idleTimeoutMs?: number;
168
- maxAgeMs?: number;
169
- };
170
- }) {
171
- return {
172
- boundAt: binding.boundAt,
173
- lastActivityAt:
174
- typeof binding.metadata?.lastActivityAt === "number"
175
- ? binding.metadata.lastActivityAt
176
- : binding.boundAt,
177
- idleTimeoutMs:
178
- typeof binding.metadata?.idleTimeoutMs === "number"
179
- ? binding.metadata.idleTimeoutMs
180
- : undefined,
181
- maxAgeMs:
182
- typeof binding.metadata?.maxAgeMs === "number" ? binding.metadata.maxAgeMs : undefined,
183
- };
184
- }
185
-
186
- const resolveMatrixDmPolicy = createScopedDmSecurityResolver<ResolvedMatrixAccount>({
187
- channelKey: "matrix",
188
- resolvePolicy: (account) => account.config.dm?.policy,
189
- resolveAllowFrom: (account) => account.config.dm?.allowFrom,
190
- allowFromPathSuffix: "dm.",
191
- normalizeEntry: (raw) => normalizeMatrixUserId(raw),
192
- });
193
-
194
- const collectMatrixSecurityWarnings =
195
- createAllowlistProviderOpenWarningCollector<ResolvedMatrixAccount>({
196
- providerConfigPresent: (cfg) => (cfg as CoreConfig).channels?.matrix !== undefined,
197
- resolveGroupPolicy: (account) => account.config.groupPolicy,
198
- buildOpenWarning: {
199
- surface: "Matrix rooms",
200
- openBehavior: "allows any room to trigger (mention-gated)",
201
- remediation:
202
- 'Set channels.matrix.groupPolicy="allowlist" + channels.matrix.groups (and optionally channels.matrix.groupAllowFrom) to restrict rooms',
203
- },
204
- });
205
-
206
- function resolveMatrixAccountConfigPath(accountId: string, field: string): string {
207
- return accountId === DEFAULT_ACCOUNT_ID
208
- ? `channels.matrix.${field}`
209
- : `channels.matrix.accounts.${accountId}.${field}`;
210
- }
211
-
212
- function collectMatrixSecurityWarningsForAccount(params: {
213
- account: ResolvedMatrixAccount;
214
- cfg: CoreConfig;
215
- }): string[] {
216
- const warnings = collectMatrixSecurityWarnings(params);
217
- if (params.account.accountId !== DEFAULT_ACCOUNT_ID) {
218
- const groupPolicyPath = resolveMatrixAccountConfigPath(params.account.accountId, "groupPolicy");
219
- const groupsPath = resolveMatrixAccountConfigPath(params.account.accountId, "groups");
220
- const groupAllowFromPath = resolveMatrixAccountConfigPath(
221
- params.account.accountId,
222
- "groupAllowFrom",
223
- );
224
- return warnings.map((warning) =>
225
- warning
226
- .replace("channels.matrix.groupPolicy", groupPolicyPath)
227
- .replace("channels.matrix.groups", groupsPath)
228
- .replace("channels.matrix.groupAllowFrom", groupAllowFromPath),
229
- );
230
- }
231
- if (params.account.config.autoJoin !== "always") {
232
- return warnings;
233
- }
234
- const autoJoinPath = resolveMatrixAccountConfigPath(params.account.accountId, "autoJoin");
235
- const autoJoinAllowlistPath = resolveMatrixAccountConfigPath(
236
- params.account.accountId,
237
- "autoJoinAllowlist",
238
- );
239
- return [
240
- ...warnings,
241
- `- Matrix invites: autoJoin="always" joins any invited room before message policy applies. Set ${autoJoinPath}="allowlist" + ${autoJoinAllowlistPath} (or ${autoJoinPath}="off") to restrict joins.`,
242
- ];
243
- }
244
-
245
- function normalizeMatrixAcpConversationId(conversationId: string) {
246
- const target = resolveMatrixTargetIdentity(conversationId);
247
- if (!target || target.kind !== "room") {
248
- return null;
249
- }
250
- return { conversationId: target.id };
251
- }
252
-
253
- function matchMatrixAcpConversation(params: {
254
- bindingConversationId: string;
255
- conversationId: string;
256
- parentConversationId?: string;
257
- }) {
258
- const binding = normalizeMatrixAcpConversationId(params.bindingConversationId);
259
- if (!binding) {
260
- return null;
261
- }
262
- if (binding.conversationId === params.conversationId) {
263
- return { conversationId: params.conversationId, matchPriority: 2 };
264
- }
265
- if (
266
- params.parentConversationId &&
267
- params.parentConversationId !== params.conversationId &&
268
- binding.conversationId === params.parentConversationId
269
- ) {
270
- return {
271
- conversationId: params.parentConversationId,
272
- matchPriority: 1,
273
- };
274
- }
275
- return null;
276
- }
277
-
278
- function resolveMatrixCommandConversation(params: {
279
- threadId?: string;
280
- originatingTo?: string;
281
- commandTo?: string;
282
- fallbackTo?: string;
283
- }) {
284
- const parentConversationId = [params.originatingTo, params.commandTo, params.fallbackTo]
285
- .map((candidate) => {
286
- const trimmed = candidate?.trim();
287
- if (!trimmed) {
288
- return undefined;
289
- }
290
- const target = resolveMatrixTargetIdentity(trimmed);
291
- return target?.kind === "room" ? target.id : undefined;
292
- })
293
- .find((candidate): candidate is string => Boolean(candidate));
294
- if (params.threadId) {
295
- return {
296
- conversationId: params.threadId,
297
- ...(parentConversationId ? { parentConversationId } : {}),
298
- };
299
- }
300
- return parentConversationId ? { conversationId: parentConversationId } : null;
301
- }
302
-
303
- function resolveMatrixDeliveryTarget(params: {
304
- conversationId: string;
305
- parentConversationId?: string;
306
- }) {
307
- const parentConversationId = params.parentConversationId?.trim();
308
- if (parentConversationId && parentConversationId !== params.conversationId.trim()) {
309
- const parentTarget = resolveMatrixTargetIdentity(parentConversationId);
310
- if (parentTarget?.kind === "room") {
311
- return {
312
- to: `room:${parentTarget.id}`,
313
- threadId: params.conversationId.trim(),
314
- };
315
- }
316
- }
317
- const conversationTarget = resolveMatrixTargetIdentity(params.conversationId);
318
- if (conversationTarget?.kind === "room") {
319
- return { to: `room:${conversationTarget.id}` };
320
- }
321
- return null;
322
- }
323
-
324
- const matrixChannelOutbound: ChannelOutboundAdapter = {
325
- deliveryMode: "direct",
326
- chunker: chunkTextForOutbound,
327
- chunkerMode: "markdown",
328
- textChunkLimit: 4000,
329
- deliveryCapabilities: {
330
- durableFinal: {
331
- text: true,
332
- media: true,
333
- replyTo: true,
334
- thread: true,
335
- messageSendingHooks: true,
336
- },
337
- },
338
- presentationCapabilities: {
339
- supported: true,
340
- buttons: true,
341
- selects: true,
342
- context: true,
343
- divider: true,
344
- limits: {
345
- text: {
346
- markdownDialect: "markdown",
347
- supportsEdit: true,
348
- },
349
- },
350
- },
351
- shouldSuppressLocalPayloadPrompt: ({ cfg, accountId, payload }) =>
352
- shouldSuppressLocalMatrixExecApprovalPrompt({
353
- cfg,
354
- accountId,
355
- payload,
356
- }),
357
- ...createRuntimeOutboundDelegates({
358
- getRuntime: loadMatrixChannelRuntime,
359
- renderPresentation: {
360
- resolve: (runtime) => runtime.matrixOutbound.renderPresentation,
361
- unavailableMessage: "Matrix outbound presentation rendering is unavailable",
362
- },
363
- sendPayload: {
364
- resolve: (runtime) => runtime.matrixOutbound.sendPayload,
365
- unavailableMessage: "Matrix outbound payload delivery is unavailable",
366
- },
367
- sendText: {
368
- resolve: (runtime) => runtime.matrixOutbound.sendText,
369
- unavailableMessage: "Matrix outbound text delivery is unavailable",
370
- },
371
- sendMedia: {
372
- resolve: (runtime) => runtime.matrixOutbound.sendMedia,
373
- unavailableMessage: "Matrix outbound media delivery is unavailable",
374
- },
375
- sendPoll: {
376
- resolve: (runtime) => runtime.matrixOutbound.sendPoll,
377
- unavailableMessage: "Matrix outbound poll delivery is unavailable",
378
- },
379
- }),
380
- };
381
-
382
- const matrixMessageAdapter = createChannelMessageAdapterFromOutbound({
383
- id: "matrix",
384
- outbound: matrixChannelOutbound,
385
- live: {
386
- capabilities: {
387
- draftPreview: true,
388
- previewFinalization: true,
389
- progressUpdates: true,
390
- quietFinalization: true,
391
- },
392
- finalizer: {
393
- capabilities: {
394
- finalEdit: true,
395
- normalFallback: true,
396
- discardPending: true,
397
- previewReceipt: true,
398
- },
399
- },
400
- },
401
- });
402
-
403
- export const matrixPlugin: ChannelPlugin<ResolvedMatrixAccount, MatrixProbe> =
404
- createChatChannelPlugin<ResolvedMatrixAccount, MatrixProbe>({
405
- base: {
406
- id: "matrix",
407
- meta,
408
- setupWizard: createMatrixSetupWizardProxy(async () => ({
409
- matrixSetupWizard: await loadMatrixSetupWizard(),
410
- })),
411
- capabilities: {
412
- chatTypes: ["direct", "group", "thread"],
413
- polls: true,
414
- reactions: true,
415
- threads: true,
416
- media: true,
417
- tts: {
418
- voice: {
419
- synthesisTarget: "voice-note",
420
- },
421
- },
422
- },
423
- reload: { configPrefixes: ["channels.matrix"] },
424
- configSchema: MatrixChannelConfigSchema,
425
- config: {
426
- ...matrixConfigAdapter,
427
- isConfigured: (account) => account.configured,
428
- describeAccount: (account) =>
429
- describeAccountSnapshot({
430
- account,
431
- configured: account.configured,
432
- extra: {
433
- baseUrl: account.homeserver,
434
- },
435
- }),
436
- },
437
- approvalCapability: matrixApprovalCapability,
438
- groups: {
439
- resolveRequireMention: resolveMatrixGroupRequireMention,
440
- resolveToolPolicy: resolveMatrixGroupToolPolicy,
441
- },
442
- conversationBindings: {
443
- supportsCurrentConversationBinding: true,
444
- defaultTopLevelPlacement: "child",
445
- setIdleTimeoutBySessionKey: ({ targetSessionKey, accountId, idleTimeoutMs }) =>
446
- setMatrixThreadBindingIdleTimeoutBySessionKey({
447
- targetSessionKey,
448
- accountId: accountId ?? "",
449
- idleTimeoutMs,
450
- }).map(projectMatrixConversationBinding),
451
- setMaxAgeBySessionKey: ({ targetSessionKey, accountId, maxAgeMs }) =>
452
- setMatrixThreadBindingMaxAgeBySessionKey({
453
- targetSessionKey,
454
- accountId: accountId ?? "",
455
- maxAgeMs,
456
- }).map(projectMatrixConversationBinding),
457
- },
458
- messaging: {
459
- defaultMarkdownTableMode: "bullets",
460
- targetPrefixes: ["matrix"],
461
- normalizeTarget: normalizeMatrixMessagingTarget,
462
- resolveInboundConversation: ({ to, conversationId, threadId }) =>
463
- resolveMatrixInboundConversation({ to, conversationId, threadId }),
464
- resolveDeliveryTarget: ({ conversationId, parentConversationId }) =>
465
- resolveMatrixDeliveryTarget({ conversationId, parentConversationId }),
466
- resolveOutboundSessionRoute: (params) => resolveMatrixOutboundSessionRoute(params),
467
- targetResolver: {
468
- looksLikeId: (raw) => {
469
- const trimmed = raw.trim();
470
- if (!trimmed) {
471
- return false;
472
- }
473
- if (/^(matrix:)?[!#@]/i.test(trimmed)) {
474
- return true;
475
- }
476
- return trimmed.includes(":");
477
- },
478
- hint: "<room|alias|user>",
479
- },
480
- },
481
- directory: createChannelDirectoryAdapter({
482
- listPeers: async (params) => {
483
- const entries = await listMatrixDirectoryPeersFromConfig(params);
484
- return entries.map((entry) => {
485
- const raw = entry.id.startsWith("user:") ? entry.id.slice("user:".length) : entry.id;
486
- const incomplete = !raw.startsWith("@") || !raw.includes(":");
487
- return incomplete
488
- ? Object.assign({}, entry, { name: `incomplete id; expected @user:server` })
489
- : entry;
490
- });
491
- },
492
- listGroups: async (params) => await listMatrixDirectoryGroupsFromConfig(params),
493
- ...createRuntimeDirectoryLiveAdapter({
494
- getRuntime: loadMatrixChannelRuntime,
495
- listPeersLive: (runtime) => runtime.listMatrixDirectoryPeersLive,
496
- listGroupsLive: (runtime) => runtime.listMatrixDirectoryGroupsLive,
497
- }),
498
- }),
499
- resolver: matrixResolverAdapter,
500
- actions: matrixMessageActions,
501
- message: matrixMessageAdapter,
502
- secrets: {
503
- secretTargetRegistryEntries,
504
- collectRuntimeConfigAssignments,
505
- },
506
- setup: {
507
- ...matrixSetupAdapter,
508
- singleAccountKeysToMove,
509
- namedAccountPromotionKeys,
510
- resolveSingleAccountPromotionTarget,
511
- },
512
- bindings: {
513
- compileConfiguredBinding: ({ conversationId }) =>
514
- normalizeMatrixAcpConversationId(conversationId),
515
- matchInboundConversation: ({ compiledBinding, conversationId, parentConversationId }) =>
516
- matchMatrixAcpConversation({
517
- bindingConversationId: compiledBinding.conversationId,
518
- conversationId,
519
- parentConversationId,
520
- }),
521
- resolveCommandConversation: ({ threadId, originatingTo, commandTo, fallbackTo }) =>
522
- resolveMatrixCommandConversation({
523
- threadId,
524
- originatingTo,
525
- commandTo,
526
- fallbackTo,
527
- }),
528
- },
529
- status: createComputedAccountStatusAdapter<ResolvedMatrixAccount, MatrixProbe>({
530
- defaultRuntime: createDefaultChannelRuntimeState(DEFAULT_ACCOUNT_ID),
531
- collectStatusIssues: (accounts) => collectStatusIssuesFromLastError("matrix", accounts),
532
- buildChannelSummary: ({ snapshot }) =>
533
- buildProbeChannelStatusSummary(snapshot, { baseUrl: snapshot.baseUrl ?? null }),
534
- probeAccount: async ({ account, timeoutMs, cfg }) =>
535
- await createMatrixProbeAccount({
536
- resolveMatrixAuth: async ({ cfg, accountId }) =>
537
- (await loadMatrixChannelRuntime()).resolveMatrixAuth({
538
- cfg,
539
- accountId,
540
- }),
541
- probeMatrix: async (params) =>
542
- await (await loadMatrixChannelRuntime()).probeMatrix(params),
543
- })({
544
- account,
545
- timeoutMs,
546
- cfg,
547
- }),
548
- resolveAccountSnapshot: ({ account, runtime }) => ({
549
- accountId: account.accountId,
550
- name: account.name,
551
- enabled: account.enabled,
552
- configured: account.configured,
553
- extra: {
554
- baseUrl: account.homeserver,
555
- lastProbeAt: runtime?.lastProbeAt ?? null,
556
- ...buildMatrixTrafficStatusSummary(runtime),
557
- },
558
- }),
559
- }),
560
- gateway: {
561
- startAccount: async (ctx) => {
562
- const account = ctx.account;
563
- ctx.setStatus({
564
- accountId: account.accountId,
565
- baseUrl: account.homeserver,
566
- });
567
- ctx.log?.info(
568
- `[${account.accountId}] starting provider (${account.homeserver ?? "matrix"})`,
569
- );
570
-
571
- // Serialize startup: wait for any previous startup to complete import phase.
572
- // This works around a race condition with concurrent dynamic imports.
573
- //
574
- // INVARIANT: The import() below cannot hang because:
575
- // 1. It only loads local ESM modules with no circular awaits
576
- // 2. Module initialization is synchronous (no top-level await in ./matrix/monitor/index.js)
577
- // 3. The lock only serializes the import phase, not the provider startup
578
- const previousLock = matrixStartupLock;
579
- let releaseLock: () => void = () => {};
580
- matrixStartupLock = new Promise<void>((resolve) => {
581
- releaseLock = resolve;
582
- });
583
- await previousLock;
584
-
585
- // Lazy import: the monitor pulls the reply pipeline; avoid ESM init cycles.
586
- // Wrap in try/finally to ensure lock is released even if import fails.
587
- let monitorMatrixProvider: typeof import("./matrix/monitor/index.js").monitorMatrixProvider;
588
- try {
589
- const module = await import("./matrix/monitor/index.js");
590
- monitorMatrixProvider = module.monitorMatrixProvider;
591
- } finally {
592
- // Release lock after import completes or fails
593
- releaseLock();
594
- }
595
-
596
- return monitorMatrixProvider({
597
- runtime: ctx.runtime,
598
- channelRuntime: ctx.channelRuntime,
599
- abortSignal: ctx.abortSignal,
600
- mediaMaxMb: account.config.mediaMaxMb,
601
- initialSyncLimit: account.config.initialSyncLimit,
602
- replyToMode: account.config.replyToMode,
603
- accountId: account.accountId,
604
- setStatus: ctx.setStatus,
605
- });
606
- },
607
- },
608
- doctor: matrixDoctor,
609
- lifecycle: {
610
- runStartupMaintenance: runMatrixStartupMaintenance,
611
- },
612
- heartbeat: {
613
- sendTyping: async ({ cfg, to, accountId }) => {
614
- await (
615
- await loadMatrixChannelRuntime()
616
- ).sendTypingMatrix(to, true, {
617
- cfg: cfg as CoreConfig,
618
- ...(accountId ? { accountId } : {}),
619
- });
620
- },
621
- clearTyping: async ({ cfg, to, accountId }) => {
622
- await (
623
- await loadMatrixChannelRuntime()
624
- ).sendTypingMatrix(to, false, {
625
- cfg: cfg as CoreConfig,
626
- ...(accountId ? { accountId } : {}),
627
- });
628
- },
629
- },
630
- },
631
- security: {
632
- resolveDmPolicy: resolveMatrixDmPolicy,
633
- collectWarnings: projectAccountConfigWarningCollector(
634
- (cfg) => cfg as CoreConfig,
635
- collectMatrixSecurityWarningsForAccount,
636
- ),
637
- },
638
- pairing: {
639
- text: createMatrixPairingText(
640
- async (to, message, options) =>
641
- await (await loadMatrixChannelRuntime()).sendMessageMatrix(to, message, options),
642
- ),
643
- },
644
- threading: {
645
- resolveReplyToMode: createScopedAccountReplyToModeResolver<
646
- ReturnType<typeof resolveMatrixAccountConfig>
647
- >({
648
- resolveAccount: adaptScopedAccountAccessor(resolveMatrixAccountConfig),
649
- resolveReplyToMode: (account) => account.replyToMode,
650
- }),
651
- buildToolContext: ({ context, hasRepliedRef }) => {
652
- const currentTarget = context.To;
653
- return {
654
- currentChannelId: normalizeOptionalString(currentTarget),
655
- currentThreadTs:
656
- context.MessageThreadId != null ? String(context.MessageThreadId) : undefined,
657
- currentDirectUserId: resolveMatrixDirectUserId({
658
- from: context.From,
659
- to: context.To,
660
- chatType: context.ChatType,
661
- }),
662
- hasRepliedRef,
663
- };
664
- },
665
- },
666
- outbound: matrixChannelOutbound,
667
- });
@@ -1,19 +0,0 @@
1
- import type { KlawPluginApi } from "klaw/plugin-sdk/channel-plugin-common";
2
-
3
- export function registerMatrixCliMetadata(api: KlawPluginApi) {
4
- api.registerCli(
5
- async ({ program }) => {
6
- const { registerMatrixCli } = await import("./cli.js");
7
- registerMatrixCli({ program });
8
- },
9
- {
10
- descriptors: [
11
- {
12
- name: "matrix",
13
- description: "Manage Matrix accounts, verification, devices, and profile state",
14
- hasSubcommands: true,
15
- },
16
- ],
17
- },
18
- );
19
- }