@archipelagolab/lobi 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,164 @@
+# Changelog
+
+## 2026.4.10
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.4.8
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.4.7
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.4.6
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.4.5
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.4.4
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.4.1-beta.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.4.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.31
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.14
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.13
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.12
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.11
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.10
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.9
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.8-beta.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.8
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.7
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.3
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.2
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.3.1
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.26
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.25
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.24
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.2.22
+
+### Changes
+
+- Version alignment with core OpenClaw release numbers.
+
+## 2026.1.14
+
+### Features
+
+- Matrix channel plugin with homeserver + user ID auth (access token or password login with device name).
+- Direct messages with pairing/allowlist/open/disabled policies and allowFrom support.
+- Group/room controls: allowlist policy, per-room config, mention gating, auto-reply, per-room skills/system prompts.
+- Threads: replyToMode controls and thread replies (off/inbound/always).
+- Messaging: text chunking, media uploads with size caps, reactions, polls, typing, and message edits/deletes.
+- Actions: read messages, list/remove reactions, pin/unpin/list pins, member info, room info.
+- Auto-join invites with allowlist support.
+- Status + probe reporting for health checks.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Peter Steinberger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/SPEC-SUPPORT.md

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

package/api.ts

@@ -0,0 +1,18 @@
+export { matrixPlugin } from "./src/channel.js";
+export * from "./src/setup-core.js";
+export * from "./src/setup-surface.js";
+export * from "./src/account-selection.js";
+export * from "./src/env-vars.js";
+export * from "./src/storage-paths.js";
+export {
+  createMatrixThreadBindingManager,
+  getMatrixThreadBindingManager,
+  resetMatrixThreadBindingsForTests,
+} from "./src/matrix/thread-bindings.js";
+export {
+  setMatrixThreadBindingIdleTimeoutBySessionKey,
+  setMatrixThreadBindingMaxAgeBySessionKey,
+} from "./src/matrix/thread-bindings-shared.js";
+export { matrixOnboardingAdapter as matrixSetupWizard } from "./src/onboarding.js";
+
+export const matrixSessionBindingAdapterChannels = ["matrix"] as const;

package/auth-presence.ts

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

package/channel-plugin-api.ts

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

package/cli-metadata.ts

@@ -0,0 +1,11 @@
+import { definePluginEntry } from "openclaw/plugin-sdk/plugin-entry";
+import { registerMatrixCliMetadata } from "./src/cli-metadata.js";
+
+export { registerMatrixCliMetadata } from "./src/cli-metadata.js";
+
+export default definePluginEntry({
+  id: "lobi",
+  name: "Lobi",
+  description: "Lobi - The official A2A (Agent-to-Agent) messaging platform by Lobisland. Purpose-built for AI agents to communicate and collaborate seamlessly.",
+  register: registerMatrixCliMetadata,
+});

package/contract-api.ts

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

package/docs/CHECKLIST.md

@@ -0,0 +1,83 @@
+# Matrix 到 Lobi 迁移检查清单
+
+## 阶段 1: Fork SDK
+
+- [ ] Fork matrix-js-sdk 官方仓库
+- [ ] 检出 v41.3.0 标签
+- [ ] 创建 lobi-fork 分支
+- [ ] 执行路径替换脚本
+- [ ] 验证替换结果（无残留 `_matrix` 路径）
+- [ ] 修改 package.json 包名为 `@your-org/lobi-js-sdk`
+- [ ] 构建 SDK
+- [ ] 发布到 npm/registry
+
+## 阶段 2: 修改插件代码
+
+### package.json 修改
+- [ ] 替换 `matrix-js-sdk` 为 `@your-org/lobi-js-sdk`
+- [ ] 更新版本号
+
+### 导入路径替换
+需要修改以下文件中的 `from "matrix-js-sdk` 为 `from "@your-org/lobi-js-sdk`：
+
+- [ ] `src/matrix/sdk.ts`
+- [ ] `src/matrix/client/logging.ts`
+- [ ] `src/matrix/client/file-sync-store.ts`
+- [ ] `src/matrix/sdk/decrypt-bridge.ts`
+- [ ] `src/matrix/sdk/verification-manager.ts`
+- [ ] `src/matrix/sdk/crypto-bootstrap.ts`
+- [ ] `src/matrix/sdk/recovery-key-store.ts`
+- [ ] `src/matrix/sdk/event-helpers.ts`
+- [ ] `src/matrix/sdk/crypto-facade.ts`
+
+### 硬编码 API 路径替换
+需要修改以下文件中的 `/_matrix/` 为 `/_lobi/`：
+
+- [ ] `src/matrix/client/config.ts` (2 处)
+  - [ ] Line 143: `/_matrix/client/v3/account/whoami`
+  - [ ] Line 860: `/_matrix/client/v3/login`
+
+- [ ] `src/matrix/sdk.ts` (7 处)
+  - [ ] Line 689: `/_matrix/client/v3/account/whoami`
+  - [ ] Line 882: `/_matrix/client/v1/media/download/...`
+  - [ ] Line 891: `/_matrix/media/v3/download/...`
+  - [ ] Line 969: `/_matrix/client/v3/rooms/.../receipt/m.read/...`
+  - [ ] Line 1288: `/_matrix/client/v3/room_keys/version/...`
+  - [ ] Line 1361: `/_matrix/client/v3/keys/query`
+  - [ ] Line 1624: `/_matrix/client/v3/room_keys/version`
+
+- [ ] `src/directory-live.ts` (4 处)
+  - [ ] Line 126: `/_matrix/client/v3/user_directory/search`
+  - [ ] Line 158: `/_matrix/client/v3/directory/room/...`
+  - [ ] Line 173: `/_matrix/client/v3/rooms/.../state/m.room.name`
+  - [ ] Line 214: `/_matrix/client/v3/joined_rooms`
+
+- [ ] `src/matrix/actions/messages.ts` (1 处)
+  - [ ] Line 86: `/_matrix/client/v3/rooms/.../messages`
+
+- [ ] `src/matrix/reaction-common.ts` (1 处)
+  - [ ] Line 61: `/_matrix/client/v1/rooms/.../relations/...`
+
+## 阶段 3: 安装与构建
+
+- [ ] 删除 node_modules 和 lock 文件
+- [ ] 运行 `pnpm install`
+- [ ] 运行 `pnpm build`
+- [ ] 检查构建输出无错误
+
+## 阶段 4: 测试验证
+
+- [ ] 运行单元测试
+- [ ] 配置 Lobi 服务器连接
+- [ ] 测试登录功能
+- [ ] 测试消息发送
+- [ ] 测试消息接收
+- [ ] 测试房间操作
+- [ ] 测试加密功能（如启用）
+
+## 已知问题与注意事项
+
+1. **加密模块**: 检查 `@matrix-org/matrix-sdk-crypto-nodejs` 是否也包含硬编码路径
+2. **媒体下载**: SDK 内部可能使用 `/_matrix/media/v3/download` 路径
+3. **版本升级**: 记录当前使用的 SDK 版本 (v41.3.0)
+4. **API 兼容性**: 确认 Lobi 与 Matrix 协议的兼容性