@archipelagolab/lobi 1.0.0

package/src/matrix/monitor/route.test.ts

@@ -0,0 +1,255 @@
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { matrixPlugin } from "../../channel.js";
+import {
+  __testing as sessionBindingTesting,
+  createTestRegistry,
+  registerSessionBindingAdapter,
+  resolveAgentRoute,
+  setActivePluginRegistry,
+  type OpenClawConfig,
+} from "../../test-support/monitor-route-test-support.js";
+import { resolveMatrixInboundRoute } from "./route.js";
+
+const baseCfg = {
+  session: { mainKey: "main" },
+  agents: {
+    list: [{ id: "main" }, { id: "sender-agent" }, { id: "room-agent" }, { id: "acp-agent" }],
+  },
+} satisfies OpenClawConfig;
+
+type RouteBinding = NonNullable<OpenClawConfig["bindings"]>[number];
+type RoutePeer = NonNullable<RouteBinding["match"]["peer"]>;
+
+function matrixBinding(
+  agentId: string,
+  peer?: RoutePeer,
+  type?: RouteBinding["type"],
+): RouteBinding {
+  return {
+    ...(type ? { type } : {}),
+    agentId,
+    match: {
+      channel: "matrix",
+      accountId: "ops",
+      ...(peer ? { peer } : {}),
+    },
+  } as RouteBinding;
+}
+
+function senderPeer(id = "@alice:example.org"): RoutePeer {
+  return { kind: "direct", id };
+}
+
+function dmRoomPeer(id = "!dm:example.org"): RoutePeer {
+  return { kind: "channel", id };
+}
+
+function resolveDmRoute(
+  cfg: OpenClawConfig,
+  opts: {
+    dmSessionScope?: "per-user" | "per-room";
+  } = {},
+) {
+  return resolveMatrixInboundRoute({
+    cfg,
+    accountId: "ops",
+    roomId: "!dm:example.org",
+    senderId: "@alice:example.org",
+    isDirectMessage: true,
+    dmSessionScope: opts.dmSessionScope,
+    resolveAgentRoute,
+  });
+}
+
+describe("resolveMatrixInboundRoute", () => {
+  beforeEach(() => {
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+    setActivePluginRegistry(
+      createTestRegistry([{ pluginId: "matrix", source: "test", plugin: matrixPlugin }]),
+    );
+  });
+
+  it("prefers sender-bound DM routing over DM room fallback bindings", () => {
+    const cfg = {
+      ...baseCfg,
+      bindings: [
+        matrixBinding("room-agent", dmRoomPeer()),
+        matrixBinding("sender-agent", senderPeer()),
+      ],
+    } satisfies OpenClawConfig;
+
+    const { route, configuredBinding } = resolveDmRoute(cfg);
+
+    expect(configuredBinding).toBeNull();
+    expect(route.agentId).toBe("sender-agent");
+    expect(route.matchedBy).toBe("binding.peer");
+    expect(route.sessionKey).toBe("agent:sender-agent:main");
+  });
+
+  it("uses the DM room as a parent-peer fallback before account-level bindings", () => {
+    const cfg = {
+      ...baseCfg,
+      bindings: [matrixBinding("acp-agent"), matrixBinding("room-agent", dmRoomPeer())],
+    } satisfies OpenClawConfig;
+
+    const { route, configuredBinding } = resolveDmRoute(cfg);
+
+    expect(configuredBinding).toBeNull();
+    expect(route.agentId).toBe("room-agent");
+    expect(route.matchedBy).toBe("binding.peer.parent");
+    expect(route.sessionKey).toBe("agent:room-agent:main");
+  });
+
+  it("can isolate Matrix DMs per room without changing agent selection", () => {
+    const cfg = {
+      ...baseCfg,
+      bindings: [matrixBinding("sender-agent", senderPeer())],
+    } satisfies OpenClawConfig;
+
+    const { route, configuredBinding } = resolveDmRoute(cfg, {
+      dmSessionScope: "per-room",
+    });
+
+    expect(configuredBinding).toBeNull();
+    expect(route.agentId).toBe("sender-agent");
+    expect(route.matchedBy).toBe("binding.peer");
+    expect(route.sessionKey).toBe("agent:sender-agent:matrix:channel:!dm:example.org");
+    expect(route.mainSessionKey).toBe("agent:sender-agent:main");
+    expect(route.lastRoutePolicy).toBe("session");
+  });
+
+  it("lets configured ACP room bindings override DM parent-peer routing", () => {
+    const cfg = {
+      ...baseCfg,
+      bindings: [
+        matrixBinding("room-agent", dmRoomPeer()),
+        matrixBinding("acp-agent", dmRoomPeer(), "acp"),
+      ],
+    } satisfies OpenClawConfig;
+
+    const { route, configuredBinding } = resolveDmRoute(cfg);
+
+    expect(configuredBinding?.spec.agentId).toBe("acp-agent");
+    expect(route.agentId).toBe("acp-agent");
+    expect(route.matchedBy).toBe("binding.channel");
+    expect(route.sessionKey).toContain("agent:acp-agent:acp:binding:matrix:ops:");
+    expect(route.lastRoutePolicy).toBe("session");
+  });
+
+  it("keeps configured ACP room bindings ahead of per-room DM session scope", () => {
+    const cfg = {
+      ...baseCfg,
+      bindings: [
+        matrixBinding("room-agent", dmRoomPeer()),
+        matrixBinding("acp-agent", dmRoomPeer(), "acp"),
+      ],
+    } satisfies OpenClawConfig;
+
+    const { route, configuredBinding } = resolveDmRoute(cfg, {
+      dmSessionScope: "per-room",
+    });
+
+    expect(configuredBinding?.spec.agentId).toBe("acp-agent");
+    expect(route.agentId).toBe("acp-agent");
+    expect(route.matchedBy).toBe("binding.channel");
+    expect(route.sessionKey).toContain("agent:acp-agent:acp:binding:matrix:ops:");
+    expect(route.sessionKey).not.toBe("agent:acp-agent:matrix:channel:!dm:example.org");
+    expect(route.lastRoutePolicy).toBe("session");
+  });
+
+  it("lets runtime conversation bindings override both sender and room route matches", () => {
+    const touch = vi.fn();
+    registerSessionBindingAdapter({
+      channel: "matrix",
+      accountId: "ops",
+      listBySession: () => [],
+      resolveByConversation: (ref) =>
+        ref.conversationId === "!dm:example.org"
+          ? {
+              bindingId: "ops:!dm:example.org",
+              targetSessionKey: "agent:bound:session-1",
+              targetKind: "session",
+              conversation: {
+                channel: "matrix",
+                accountId: "ops",
+                conversationId: "!dm:example.org",
+              },
+              status: "active",
+              boundAt: Date.now(),
+              metadata: { boundBy: "user-1" },
+            }
+          : null,
+      touch,
+    });
+
+    const cfg = {
+      ...baseCfg,
+      bindings: [
+        matrixBinding("sender-agent", senderPeer()),
+        matrixBinding("room-agent", dmRoomPeer()),
+      ],
+    } satisfies OpenClawConfig;
+
+    const { route, configuredBinding, runtimeBindingId } = resolveDmRoute(cfg);
+
+    expect(configuredBinding).toBeNull();
+    expect(runtimeBindingId).toBe("ops:!dm:example.org");
+    expect(route.agentId).toBe("bound");
+    expect(route.matchedBy).toBe("binding.channel");
+    expect(route.sessionKey).toBe("agent:bound:session-1");
+    expect(route.lastRoutePolicy).toBe("session");
+    expect(touch).not.toHaveBeenCalled();
+  });
+});
+
+describe("resolveMatrixInboundRoute thread-isolated sessions", () => {
+  beforeEach(() => {
+    sessionBindingTesting.resetSessionBindingAdaptersForTests();
+    setActivePluginRegistry(
+      createTestRegistry([{ pluginId: "matrix", source: "test", plugin: matrixPlugin }]),
+    );
+  });
+
+  it("scopes session key to thread when a thread id is provided", () => {
+    const { route } = resolveMatrixInboundRoute({
+      cfg: baseCfg as never,
+      accountId: "ops",
+      roomId: "!room:example.org",
+      senderId: "@alice:example.org",
+      isDirectMessage: false,
+      threadId: "$thread-root",
+      resolveAgentRoute,
+    });
+
+    expect(route.sessionKey).toContain(":thread:$thread-root");
+    expect(route.mainSessionKey).not.toContain(":thread:");
+    expect(route.lastRoutePolicy).toBe("session");
+  });
+
+  it("preserves mixed-case matrix thread ids in session keys", () => {
+    const { route } = resolveMatrixInboundRoute({
+      cfg: baseCfg as never,
+      accountId: "ops",
+      roomId: "!room:example.org",
+      senderId: "@alice:example.org",
+      isDirectMessage: false,
+      threadId: "$AbC123:example.org",
+      resolveAgentRoute,
+    });
+
+    expect(route.sessionKey).toContain(":thread:$AbC123:example.org");
+  });
+
+  it("does not scope session key when thread id is absent", () => {
+    const { route } = resolveMatrixInboundRoute({
+      cfg: baseCfg as never,
+      accountId: "ops",
+      roomId: "!room:example.org",
+      senderId: "@alice:example.org",
+      isDirectMessage: false,
+      resolveAgentRoute,
+    });
+
+    expect(route.sessionKey).not.toContain(":thread:");
+  });
+});

package/src/matrix/monitor/route.ts

@@ -0,0 +1,178 @@
+import { buildAgentSessionKey, deriveLastRoutePolicy } from "openclaw/plugin-sdk/routing";
+import {
+  getSessionBindingService,
+  resolveAgentIdFromSessionKey,
+  resolveConfiguredAcpBindingRecord,
+  type PluginRuntime,
+} from "../../runtime-api.js";
+import type { CoreConfig } from "../../types.js";
+import { resolveMatrixThreadSessionKeys } from "./threads.js";
+
+type MatrixResolvedRoute = ReturnType<PluginRuntime["channel"]["routing"]["resolveAgentRoute"]>;
+
+function resolveMatrixDmSessionKey(params: {
+  accountId: string;
+  agentId: string;
+  roomId: string;
+  dmSessionScope?: "per-user" | "per-room";
+  fallbackSessionKey: string;
+}): string {
+  if (params.dmSessionScope !== "per-room") {
+    return params.fallbackSessionKey;
+  }
+  return buildAgentSessionKey({
+    agentId: params.agentId,
+    channel: "matrix",
+    accountId: params.accountId,
+    peer: {
+      kind: "channel",
+      id: params.roomId,
+    },
+  });
+}
+
+function shouldApplyMatrixPerRoomDmSessionScope(params: {
+  isDirectMessage: boolean;
+  configuredSessionKey?: string;
+}): boolean {
+  return params.isDirectMessage && !params.configuredSessionKey;
+}
+
+export function resolveMatrixInboundRoute(params: {
+  cfg: CoreConfig;
+  accountId: string;
+  roomId: string;
+  senderId: string;
+  isDirectMessage: boolean;
+  dmSessionScope?: "per-user" | "per-room";
+  threadId?: string;
+  eventTs?: number;
+  resolveAgentRoute: PluginRuntime["channel"]["routing"]["resolveAgentRoute"];
+}): {
+  route: MatrixResolvedRoute;
+  configuredBinding: ReturnType<typeof resolveConfiguredAcpBindingRecord>;
+  runtimeBindingId: string | null;
+} {
+  const baseRoute = params.resolveAgentRoute({
+    cfg: params.cfg,
+    channel: "matrix",
+    accountId: params.accountId,
+    peer: {
+      kind: params.isDirectMessage ? "direct" : "channel",
+      id: params.isDirectMessage ? params.senderId : params.roomId,
+    },
+    // Matrix DMs are still sender-addressed first, but the room ID remains a
+    // useful fallback binding key for generic route matching.
+    parentPeer: params.isDirectMessage
+      ? {
+          kind: "channel",
+          id: params.roomId,
+        }
+      : undefined,
+  });
+  const bindingConversationId = params.threadId ?? params.roomId;
+  const bindingParentConversationId = params.threadId ? params.roomId : undefined;
+  const sessionBindingService = getSessionBindingService();
+  const runtimeBinding = sessionBindingService.resolveByConversation({
+    channel: "matrix",
+    accountId: params.accountId,
+    conversationId: bindingConversationId,
+    parentConversationId: bindingParentConversationId,
+  });
+  const boundSessionKey = runtimeBinding?.targetSessionKey?.trim();
+
+  if (runtimeBinding && boundSessionKey) {
+    return {
+      route: {
+        ...baseRoute,
+        sessionKey: boundSessionKey,
+        agentId: resolveAgentIdFromSessionKey(boundSessionKey) || baseRoute.agentId,
+        lastRoutePolicy: deriveLastRoutePolicy({
+          sessionKey: boundSessionKey,
+          mainSessionKey: baseRoute.mainSessionKey,
+        }),
+        matchedBy: "binding.channel",
+      },
+      configuredBinding: null,
+      runtimeBindingId: runtimeBinding.bindingId,
+    };
+  }
+
+  const configuredBinding =
+    runtimeBinding == null
+      ? resolveConfiguredAcpBindingRecord({
+          cfg: params.cfg,
+          channel: "matrix",
+          accountId: params.accountId,
+          conversationId: bindingConversationId,
+          parentConversationId: bindingParentConversationId,
+        })
+      : null;
+  const configuredSessionKey = configuredBinding?.record.targetSessionKey?.trim();
+
+  const effectiveRoute =
+    configuredBinding && configuredSessionKey
+      ? {
+          ...baseRoute,
+          sessionKey: configuredSessionKey,
+          agentId:
+            resolveAgentIdFromSessionKey(configuredSessionKey) ||
+            configuredBinding.spec.agentId ||
+            baseRoute.agentId,
+          lastRoutePolicy: deriveLastRoutePolicy({
+            sessionKey: configuredSessionKey,
+            mainSessionKey: baseRoute.mainSessionKey,
+          }),
+          matchedBy: "binding.channel" as const,
+        }
+      : baseRoute;
+
+  const dmSessionKey = shouldApplyMatrixPerRoomDmSessionScope({
+    isDirectMessage: params.isDirectMessage,
+    configuredSessionKey,
+  })
+    ? resolveMatrixDmSessionKey({
+        accountId: params.accountId,
+        agentId: effectiveRoute.agentId,
+        roomId: params.roomId,
+        dmSessionScope: params.dmSessionScope,
+        fallbackSessionKey: effectiveRoute.sessionKey,
+      })
+    : effectiveRoute.sessionKey;
+  const routeWithDmScope =
+    dmSessionKey === effectiveRoute.sessionKey
+      ? effectiveRoute
+      : {
+          ...effectiveRoute,
+          sessionKey: dmSessionKey,
+          lastRoutePolicy: "session" as const,
+        };
+
+  // When no binding overrides the session key, isolate threads into their own sessions.
+  if (!configuredBinding && !configuredSessionKey && params.threadId) {
+    const threadKeys = resolveMatrixThreadSessionKeys({
+      baseSessionKey: routeWithDmScope.sessionKey,
+      threadId: params.threadId,
+      parentSessionKey: routeWithDmScope.sessionKey,
+    });
+    return {
+      route: {
+        ...routeWithDmScope,
+        sessionKey: threadKeys.sessionKey,
+        mainSessionKey: threadKeys.parentSessionKey ?? routeWithDmScope.sessionKey,
+        lastRoutePolicy: deriveLastRoutePolicy({
+          sessionKey: threadKeys.sessionKey,
+          mainSessionKey: threadKeys.parentSessionKey ?? routeWithDmScope.sessionKey,
+        }),
+      },
+      configuredBinding,
+      runtimeBindingId: null,
+    };
+  }
+
+  return {
+    route: routeWithDmScope,
+    configuredBinding,
+    runtimeBindingId: null,
+  };
+}

package/src/matrix/monitor/runtime-api.ts

@@ -0,0 +1,31 @@
+// Narrow Matrix monitor helper seam.
+// Keep monitor internals off the broad package runtime-api barrel so monitor
+// tests and shared workers do not pull unrelated Matrix helper surfaces.
+
+export { ensureConfiguredAcpBindingReady } from "openclaw/plugin-sdk/acp-binding-runtime";
+export type { NormalizedLocation } from "openclaw/plugin-sdk/channel-inbound";
+export type { PluginRuntime, RuntimeLogger } from "openclaw/plugin-sdk/plugin-runtime";
+export type { BlockReplyContext, ReplyPayload } from "openclaw/plugin-sdk/reply-runtime";
+export type { MarkdownTableMode, OpenClawConfig } from "openclaw/plugin-sdk/config-runtime";
+export type { RuntimeEnv } from "openclaw/plugin-sdk/runtime";
+export {
+  addAllowlistUserEntriesFromConfigEntry,
+  buildAllowlistResolutionSummary,
+  canonicalizeAllowlistWithResolvedIds,
+  formatAllowlistMatchMeta,
+  patchAllowlistUsersInConfigEntries,
+  summarizeMapping,
+} from "openclaw/plugin-sdk/allow-from";
+export { createReplyPrefixOptions } from "openclaw/plugin-sdk/channel-reply-pipeline";
+export { createTypingCallbacks } from "openclaw/plugin-sdk/channel-reply-pipeline";
+export {
+  formatLocationText,
+  logInboundDrop,
+  toLocationContext,
+} from "openclaw/plugin-sdk/channel-inbound";
+export { getAgentScopedMediaLocalRoots } from "openclaw/plugin-sdk/agent-media-payload";
+export { logTypingFailure, resolveAckReaction } from "openclaw/plugin-sdk/channel-feedback";
+export {
+  buildChannelKeyCandidates,
+  resolveChannelEntryMatch,
+} from "openclaw/plugin-sdk/channel-targets";