@archipelagolab/lobi 1.0.0

package/src/outbound.test.ts

@@ -0,0 +1,173 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import type { OpenClawConfig } from "../runtime-api.js";
+
+const mocks = vi.hoisted(() => ({
+  sendMessageMatrix: vi.fn(),
+  sendPollMatrix: vi.fn(),
+}));
+
+vi.mock("./matrix/send.js", () => ({
+  sendMessageMatrix: mocks.sendMessageMatrix,
+  sendPollMatrix: mocks.sendPollMatrix,
+}));
+
+vi.mock("./runtime.js", () => ({
+  getMatrixRuntime: () => ({
+    channel: {
+      text: {
+        chunkMarkdownText: (text: string) => [text],
+      },
+    },
+  }),
+}));
+
+import { matrixOutbound } from "./outbound.js";
+
+describe("matrixOutbound cfg threading", () => {
+  beforeEach(() => {
+    mocks.sendMessageMatrix.mockReset();
+    mocks.sendPollMatrix.mockReset();
+    mocks.sendMessageMatrix.mockResolvedValue({ messageId: "evt-1", roomId: "!room:example" });
+    mocks.sendPollMatrix.mockResolvedValue({ eventId: "$poll", roomId: "!room:example" });
+  });
+
+  it("chunks outbound text without requiring Matrix runtime initialization", () => {
+    const chunker = matrixOutbound.chunker;
+    if (!chunker) {
+      throw new Error("matrixOutbound.chunker missing");
+    }
+
+    expect(() => chunker("hello world", 5)).not.toThrow();
+    expect(chunker("hello world", 5)).toEqual(["hello", "world"]);
+  });
+
+  it("passes resolved cfg to sendMessageMatrix for text sends", async () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accessToken: "resolved-token",
+        },
+      },
+    } as OpenClawConfig;
+
+    await matrixOutbound.sendText!({
+      cfg,
+      to: "room:!room:example",
+      text: "hello",
+      accountId: "default",
+      threadId: "$thread",
+      replyToId: "$reply",
+    });
+
+    expect(mocks.sendMessageMatrix).toHaveBeenCalledWith(
+      "room:!room:example",
+      "hello",
+      expect.objectContaining({
+        cfg,
+        accountId: "default",
+        threadId: "$thread",
+        replyToId: "$reply",
+      }),
+    );
+  });
+
+  it("passes resolved cfg to sendMessageMatrix for media sends", async () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accessToken: "resolved-token",
+        },
+      },
+    } as OpenClawConfig;
+
+    await matrixOutbound.sendMedia!({
+      cfg,
+      to: "room:!room:example",
+      text: "caption",
+      mediaUrl: "file:///tmp/cat.png",
+      mediaLocalRoots: ["/tmp/openclaw"],
+      accountId: "default",
+      audioAsVoice: true,
+    });
+
+    expect(mocks.sendMessageMatrix).toHaveBeenCalledWith(
+      "room:!room:example",
+      "caption",
+      expect.objectContaining({
+        cfg,
+        mediaUrl: "file:///tmp/cat.png",
+        mediaLocalRoots: ["/tmp/openclaw"],
+        audioAsVoice: true,
+      }),
+    );
+  });
+
+  it("passes resolved cfg through injected deps.matrix", async () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accessToken: "resolved-token",
+        },
+      },
+    } as OpenClawConfig;
+    const matrix = vi.fn(async () => ({
+      messageId: "evt-injected",
+      roomId: "!room:example",
+    }));
+
+    await matrixOutbound.sendText!({
+      cfg,
+      to: "room:!room:example",
+      text: "hello via deps",
+      deps: { matrix },
+      accountId: "default",
+      threadId: "$thread",
+      replyToId: "$reply",
+    });
+
+    expect(matrix).toHaveBeenCalledWith(
+      "room:!room:example",
+      "hello via deps",
+      expect.objectContaining({
+        cfg,
+        accountId: "default",
+        threadId: "$thread",
+        replyToId: "$reply",
+      }),
+    );
+  });
+
+  it("passes resolved cfg to sendPollMatrix", async () => {
+    const cfg = {
+      channels: {
+        matrix: {
+          accessToken: "resolved-token",
+        },
+      },
+    } as OpenClawConfig;
+
+    await matrixOutbound.sendPoll!({
+      cfg,
+      to: "room:!room:example",
+      poll: {
+        question: "Snack?",
+        options: ["Pizza", "Sushi"],
+      },
+      accountId: "default",
+      threadId: "$thread",
+    });
+
+    expect(mocks.sendPollMatrix).toHaveBeenCalledWith(
+      "room:!room:example",
+      expect.objectContaining({
+        question: "Snack?",
+        options: ["Pizza", "Sushi"],
+      }),
+      expect.objectContaining({
+        cfg,
+        accountId: "default",
+        threadId: "$thread",
+      }),
+    );
+  });
+});

package/src/outbound.ts

@@ -0,0 +1,78 @@
+import { sendMessageMatrix, sendPollMatrix } from "./matrix/send.js";
+import {
+  chunkTextForOutbound,
+  resolveOutboundSendDep,
+  type ChannelOutboundAdapter,
+} from "./runtime-api.js";
+
+export const matrixOutbound: ChannelOutboundAdapter = {
+  deliveryMode: "direct",
+  chunker: chunkTextForOutbound,
+  chunkerMode: "markdown",
+  textChunkLimit: 4000,
+  sendText: async ({ cfg, to, text, deps, replyToId, threadId, accountId, audioAsVoice }) => {
+    const send =
+      resolveOutboundSendDep<typeof sendMessageMatrix>(deps, "matrix") ?? sendMessageMatrix;
+    const resolvedThreadId =
+      threadId !== undefined && threadId !== null ? String(threadId) : undefined;
+    const result = await send(to, text, {
+      cfg,
+      replyToId: replyToId ?? undefined,
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+      audioAsVoice,
+    });
+    return {
+      channel: "matrix",
+      messageId: result.messageId,
+      roomId: result.roomId,
+    };
+  },
+  sendMedia: async ({
+    cfg,
+    to,
+    text,
+    mediaUrl,
+    mediaLocalRoots,
+    mediaReadFile,
+    deps,
+    replyToId,
+    threadId,
+    accountId,
+    audioAsVoice,
+  }) => {
+    const send =
+      resolveOutboundSendDep<typeof sendMessageMatrix>(deps, "matrix") ?? sendMessageMatrix;
+    const resolvedThreadId =
+      threadId !== undefined && threadId !== null ? String(threadId) : undefined;
+    const result = await send(to, text, {
+      cfg,
+      mediaUrl,
+      mediaLocalRoots,
+      mediaReadFile,
+      replyToId: replyToId ?? undefined,
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+      audioAsVoice,
+    });
+    return {
+      channel: "matrix",
+      messageId: result.messageId,
+      roomId: result.roomId,
+    };
+  },
+  sendPoll: async ({ cfg, to, poll, threadId, accountId }) => {
+    const resolvedThreadId = threadId !== undefined && threadId !== null ? threadId : undefined;
+    const result = await sendPollMatrix(to, poll, {
+      cfg,
+      threadId: resolvedThreadId,
+      accountId: accountId ?? undefined,
+    });
+    return {
+      channel: "matrix",
+      messageId: result.eventId,
+      roomId: result.roomId,
+      pollId: result.eventId,
+    };
+  },
+};

package/src/plugin-entry.runtime.js

@@ -0,0 +1,159 @@
+// Thin ESM wrapper so native dynamic import() resolves in source-checkout mode
+// while packaged dist builds resolve a distinct runtime entry that cannot loop
+// back into this wrapper through the stable root runtime alias.
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const require = createRequire(import.meta.url);
+const { createJiti } = require("jiti");
+
+const PLUGIN_ID = "matrix";
+const OPENCLAW_PLUGIN_SDK_PREFIX = ["openclaw", "plugin-sdk"].join("/");
+const PLUGIN_SDK_EXPORT_PREFIX = "./plugin-sdk/";
+const PLUGIN_SDK_SOURCE_EXTENSIONS = [".ts", ".mts", ".js", ".mjs", ".cts", ".cjs"];
+const PLUGIN_ENTRY_RUNTIME_BASENAME = "plugin-entry.handlers.runtime";
+const JITI_EXTENSIONS = [
+  ".ts",
+  ".tsx",
+  ".mts",
+  ".cts",
+  ".mtsx",
+  ".ctsx",
+  ".js",
+  ".mjs",
+  ".cjs",
+  ".json",
+];
+
+function readPackageJson(packageRoot) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(packageRoot, "package.json"), "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function findOpenClawPackageRoot(startDir) {
+  let cursor = path.resolve(startDir);
+  for (let i = 0; i < 12; i += 1) {
+    const pkg = readPackageJson(cursor);
+    if (pkg?.name === "openclaw" && pkg.exports?.["./plugin-sdk"]) {
+      return { packageRoot: cursor, packageJson: pkg };
+    }
+    const parent = path.dirname(cursor);
+    if (parent === cursor) {
+      break;
+    }
+    cursor = parent;
+  }
+  return null;
+}
+
+function resolveExistingFile(basePath, extensions) {
+  for (const ext of extensions) {
+    const candidate = `${basePath}${ext}`;
+    if (fs.existsSync(candidate)) {
+      return candidate;
+    }
+  }
+  return null;
+}
+
+function buildPluginSdkAliasMap(moduleUrl) {
+  const location = findOpenClawPackageRoot(path.dirname(fileURLToPath(moduleUrl)));
+  if (!location) {
+    return {};
+  }
+
+  const { packageRoot, packageJson } = location;
+  const sourcePluginSdkDir = path.join(packageRoot, "src", "plugin-sdk");
+  const distPluginSdkDir = path.join(packageRoot, "dist", "plugin-sdk");
+  const aliasMap = {};
+  const rootAlias =
+    resolveExistingFile(path.join(sourcePluginSdkDir, "root-alias"), [".cjs"]) ??
+    resolveExistingFile(path.join(distPluginSdkDir, "root-alias"), [".cjs"]);
+  if (rootAlias) {
+    aliasMap[OPENCLAW_PLUGIN_SDK_PREFIX] = rootAlias;
+  }
+
+  for (const exportKey of Object.keys(packageJson.exports ?? {})) {
+    if (!exportKey.startsWith(PLUGIN_SDK_EXPORT_PREFIX)) {
+      continue;
+    }
+    const subpath = exportKey.slice(PLUGIN_SDK_EXPORT_PREFIX.length);
+    if (!subpath) {
+      continue;
+    }
+    const resolvedPath =
+      resolveExistingFile(path.join(sourcePluginSdkDir, subpath), PLUGIN_SDK_SOURCE_EXTENSIONS) ??
+      resolveExistingFile(path.join(distPluginSdkDir, subpath), [".js"]);
+    if (resolvedPath) {
+      aliasMap[`${OPENCLAW_PLUGIN_SDK_PREFIX}/${subpath}`] = resolvedPath;
+    }
+  }
+
+  const extensionApi =
+    resolveExistingFile(path.join(packageRoot, "src", "extensionAPI"), [".ts", ".js"]) ??
+    resolveExistingFile(path.join(packageRoot, "dist", "extensionAPI"), [".js"]);
+  if (extensionApi) {
+    aliasMap["openclaw/extension-api"] = extensionApi;
+  }
+
+  return aliasMap;
+}
+
+function resolveBundledPluginRuntimeModulePath(moduleUrl, params) {
+  const modulePath = fileURLToPath(moduleUrl);
+  const moduleDir = path.dirname(modulePath);
+  const localCandidates = [
+    path.join(moduleDir, "..", params.runtimeBasename),
+    path.join(moduleDir, "extensions", params.pluginId, params.runtimeBasename),
+  ];
+
+  for (const candidate of localCandidates) {
+    const resolved = resolveExistingFile(candidate, PLUGIN_SDK_SOURCE_EXTENSIONS);
+    if (resolved) {
+      return resolved;
+    }
+  }
+
+  const location = findOpenClawPackageRoot(moduleDir);
+  if (location) {
+    const { packageRoot } = location;
+    const packageCandidates = [
+      path.join(packageRoot, "extensions", params.pluginId, params.runtimeBasename),
+      path.join(packageRoot, "dist", "extensions", params.pluginId, params.runtimeBasename),
+    ];
+
+    for (const candidate of packageCandidates) {
+      const resolved = resolveExistingFile(candidate, PLUGIN_SDK_SOURCE_EXTENSIONS);
+      if (resolved) {
+        return resolved;
+      }
+    }
+  }
+
+  throw new Error(
+    `Cannot resolve ${params.pluginId} plugin runtime module ${params.runtimeBasename} from ${modulePath}`,
+  );
+}
+
+const jiti = createJiti(import.meta.url, {
+  alias: buildPluginSdkAliasMap(import.meta.url),
+  interopDefault: true,
+  tryNative: false,
+  extensions: JITI_EXTENSIONS,
+});
+
+const mod = jiti(
+  resolveBundledPluginRuntimeModulePath(import.meta.url, {
+    pluginId: PLUGIN_ID,
+    runtimeBasename: PLUGIN_ENTRY_RUNTIME_BASENAME,
+  }),
+);
+export const ensureMatrixCryptoRuntime = mod.ensureMatrixCryptoRuntime;
+export const handleVerifyRecoveryKey = mod.handleVerifyRecoveryKey;
+export const handleVerificationBootstrap = mod.handleVerificationBootstrap;
+export const handleVerificationStatus = mod.handleVerificationStatus;

package/src/plugin-entry.runtime.test.ts

@@ -0,0 +1,108 @@
+import fs from "node:fs";
+import { createRequire } from "node:module";
+import os from "node:os";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import { afterEach, expect, it } from "vitest";
+
+const tempDirs: string[] = [];
+const REPO_ROOT = process.cwd();
+const require = createRequire(import.meta.url);
+const JITI_ENTRY_PATH = require.resolve("jiti");
+const PACKAGED_RUNTIME_STUB = [
+  "export async function ensureMatrixCryptoRuntime() {}",
+  "export async function handleVerifyRecoveryKey() {}",
+  "export async function handleVerificationBootstrap() {}",
+  "export async function handleVerificationStatus() {}",
+  "",
+].join("\n");
+
+function makeFixtureRoot(prefix: string) {
+  const fixtureRoot = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  tempDirs.push(fixtureRoot);
+  return fixtureRoot;
+}
+
+function writeFixtureFile(fixtureRoot: string, relativePath: string, value: string) {
+  const fullPath = path.join(fixtureRoot, relativePath);
+  fs.mkdirSync(path.dirname(fullPath), { recursive: true });
+  fs.writeFileSync(fullPath, value, "utf8");
+}
+
+afterEach(() => {
+  for (const dir of tempDirs.splice(0, tempDirs.length)) {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+it("loads the plugin-entry runtime wrapper through native ESM import", async () => {
+  const wrapperPath = path.join(
+    process.cwd(),
+    "extensions",
+    "matrix",
+    "src",
+    "plugin-entry.runtime.js",
+  );
+  const wrapperUrl = pathToFileURL(wrapperPath);
+  const mod = await import(wrapperUrl.href);
+
+  expect(mod).toMatchObject({
+    ensureMatrixCryptoRuntime: expect.any(Function),
+    handleVerifyRecoveryKey: expect.any(Function),
+    handleVerificationBootstrap: expect.any(Function),
+    handleVerificationStatus: expect.any(Function),
+  });
+}, 240_000);
+
+it("loads the packaged runtime wrapper without recursing through the stable root alias", async () => {
+  const fixtureRoot = makeFixtureRoot(".tmp-matrix-runtime-");
+  const wrapperSource = fs.readFileSync(
+    path.join(REPO_ROOT, "extensions", "matrix", "src", "plugin-entry.runtime.js"),
+    "utf8",
+  );
+
+  writeFixtureFile(
+    fixtureRoot,
+    "package.json",
+    JSON.stringify(
+      {
+        name: "openclaw",
+        type: "module",
+        exports: {
+          "./plugin-sdk": "./dist/plugin-sdk/index.js",
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
+  writeFixtureFile(fixtureRoot, "dist/plugin-sdk/index.js", "export {};\n");
+  writeFixtureFile(
+    fixtureRoot,
+    "node_modules/jiti/index.js",
+    `module.exports = require(${JSON.stringify(JITI_ENTRY_PATH)});\n`,
+  );
+  writeFixtureFile(fixtureRoot, "dist/plugin-entry.runtime-C88YIa_v.js", wrapperSource);
+  writeFixtureFile(
+    fixtureRoot,
+    "dist/plugin-entry.runtime.js",
+    'export * from "./plugin-entry.runtime-C88YIa_v.js";\n',
+  );
+  writeFixtureFile(
+    fixtureRoot,
+    "dist/extensions/matrix/plugin-entry.handlers.runtime.js",
+    PACKAGED_RUNTIME_STUB,
+  );
+
+  const wrapperUrl = pathToFileURL(
+    path.join(fixtureRoot, "dist", "plugin-entry.runtime-C88YIa_v.js"),
+  );
+  const mod = await import(`${wrapperUrl.href}?t=${Date.now()}`);
+
+  expect(mod).toMatchObject({
+    ensureMatrixCryptoRuntime: expect.any(Function),
+    handleVerifyRecoveryKey: expect.any(Function),
+    handleVerificationBootstrap: expect.any(Function),
+    handleVerificationStatus: expect.any(Function),
+  });
+}, 240_000);

package/src/plugin-entry.runtime.ts

@@ -0,0 +1,68 @@
+import type { GatewayRequestHandlerOptions } from "openclaw/plugin-sdk/gateway-runtime";
+import { normalizeOptionalString } from "openclaw/plugin-sdk/text-runtime";
+import { formatMatrixErrorMessage } from "./matrix/errors.js";
+
+function sendError(respond: (ok: boolean, payload?: unknown) => void, err: unknown) {
+  respond(false, { error: formatMatrixErrorMessage(err) });
+}
+
+export async function ensureMatrixCryptoRuntime(
+  ...args: Parameters<typeof import("./matrix/deps.js").ensureMatrixCryptoRuntime>
+): Promise<void> {
+  const { ensureMatrixCryptoRuntime: ensureRuntime } = await import("./matrix/deps.js");
+  await ensureRuntime(...args);
+}
+
+export async function handleVerifyRecoveryKey({
+  params,
+  respond,
+}: GatewayRequestHandlerOptions): Promise<void> {
+  try {
+    const { verifyMatrixRecoveryKey } = await import("./matrix/actions/verification.js");
+    const key = normalizeOptionalString(params?.key);
+    if (!key) {
+      respond(false, { error: "key required" });
+      return;
+    }
+    const accountId = normalizeOptionalString(params?.accountId);
+    const result = await verifyMatrixRecoveryKey(key, { accountId });
+    respond(result.success, result);
+  } catch (err) {
+    sendError(respond, err);
+  }
+}
+
+export async function handleVerificationBootstrap({
+  params,
+  respond,
+}: GatewayRequestHandlerOptions): Promise<void> {
+  try {
+    const { bootstrapMatrixVerification } = await import("./matrix/actions/verification.js");
+    const accountId = normalizeOptionalString(params?.accountId);
+    const recoveryKey = typeof params?.recoveryKey === "string" ? params.recoveryKey : undefined;
+    const forceResetCrossSigning = params?.forceResetCrossSigning === true;
+    const result = await bootstrapMatrixVerification({
+      accountId,
+      recoveryKey,
+      forceResetCrossSigning,
+    });
+    respond(result.success, result);
+  } catch (err) {
+    sendError(respond, err);
+  }
+}
+
+export async function handleVerificationStatus({
+  params,
+  respond,
+}: GatewayRequestHandlerOptions): Promise<void> {
+  try {
+    const { getMatrixVerificationStatus } = await import("./matrix/actions/verification.js");
+    const accountId = normalizeOptionalString(params?.accountId);
+    const includeRecoveryKey = params?.includeRecoveryKey === true;
+    const status = await getMatrixVerificationStatus({ accountId, includeRecoveryKey });
+    respond(true, status);
+  } catch (err) {
+    sendError(respond, err);
+  }
+}

package/src/profile-update.ts

@@ -0,0 +1,68 @@
+import { normalizeAccountId } from "openclaw/plugin-sdk/account-id";
+import { updateMatrixOwnProfile } from "./matrix/actions/profile.js";
+import { updateMatrixAccountConfig, resolveMatrixConfigPath } from "./matrix/config-update.js";
+import { getMatrixRuntime } from "./runtime.js";
+import type { CoreConfig } from "./types.js";
+
+export type MatrixProfileUpdateResult = {
+  accountId: string;
+  displayName: string | null;
+  avatarUrl: string | null;
+  profile: {
+    displayNameUpdated: boolean;
+    avatarUpdated: boolean;
+    resolvedAvatarUrl: string | null;
+    uploadedAvatarSource: "http" | "path" | null;
+    convertedAvatarFromHttp: boolean;
+  };
+  configPath: string;
+};
+
+export async function applyMatrixProfileUpdate(params: {
+  cfg?: CoreConfig;
+  account?: string;
+  displayName?: string;
+  avatarUrl?: string;
+  avatarPath?: string;
+  mediaLocalRoots?: readonly string[];
+}): Promise<MatrixProfileUpdateResult> {
+  const runtime = getMatrixRuntime();
+  const persistedCfg = runtime.config.loadConfig() as CoreConfig;
+  const accountId = normalizeAccountId(params.account);
+  const displayName = params.displayName?.trim() || null;
+  const avatarUrl = params.avatarUrl?.trim() || null;
+  const avatarPath = params.avatarPath?.trim() || null;
+  if (!displayName && !avatarUrl && !avatarPath) {
+    throw new Error("Provide name/displayName and/or avatarUrl/avatarPath.");
+  }
+
+  const synced = await updateMatrixOwnProfile({
+    cfg: params.cfg,
+    accountId,
+    displayName: displayName ?? undefined,
+    avatarUrl: avatarUrl ?? undefined,
+    avatarPath: avatarPath ?? undefined,
+    mediaLocalRoots: params.mediaLocalRoots,
+  });
+  const persistedAvatarUrl =
+    synced.uploadedAvatarSource && synced.resolvedAvatarUrl ? synced.resolvedAvatarUrl : avatarUrl;
+  const updated = updateMatrixAccountConfig(persistedCfg, accountId, {
+    name: displayName ?? undefined,
+    avatarUrl: persistedAvatarUrl ?? undefined,
+  });
+  await runtime.config.writeConfigFile(updated as never);
+
+  return {
+    accountId,
+    displayName,
+    avatarUrl: persistedAvatarUrl ?? null,
+    profile: {
+      displayNameUpdated: synced.displayNameUpdated,
+      avatarUpdated: synced.avatarUpdated,
+      resolvedAvatarUrl: synced.resolvedAvatarUrl,
+      uploadedAvatarSource: synced.uploadedAvatarSource,
+      convertedAvatarFromHttp: synced.convertedAvatarFromHttp,
+    },
+    configPath: resolveMatrixConfigPath(updated, accountId),
+  };
+}

package/src/record-shared.ts

@@ -0,0 +1,3 @@
+import { isRecord } from "openclaw/plugin-sdk/text-runtime";
+
+export { isRecord };