test(contracts): localize surface and session binding helpers

src/channels/plugins/contracts/surfaces-only.registry-backed.contract.test.ts

@@ -1,6 +1,6 @@
 import { describe } from "vitest";
+import { installChannelSurfaceContractSuite } from "../../../../test/helpers/channels/surface-contract-suite.js";
 import { getSurfaceContractRegistry } from "./registry.js";
-import { installChannelSurfaceContractSuite } from "./suites.js";
 
 for (const entry of getSurfaceContractRegistry()) {
   for (const surface of entry.surfaces) {

test/helpers/channels/session-binding-registry-backed-contract.ts

@@ -1,13 +1,16 @@
-import { afterEach, beforeEach, describe } from "vitest";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
 import { sessionBindingContractChannelIds } from "../../../src/channels/plugins/contracts/manifest.js";
 import { getSessionBindingContractRegistry } from "../../../src/channels/plugins/contracts/registry-session-binding.js";
-import { installSessionBindingContractSuite } from "../../../src/channels/plugins/contracts/suites.js";
 import { setChannelPluginRegistryForTests } from "../../../src/commands/channel-test-registry.js";
 import {
   clearRuntimeConfigSnapshot,
   setRuntimeConfigSnapshot,
 } from "../../../src/config/config.js";
-import { __testing as sessionBindingTesting } from "../../../src/infra/outbound/session-binding-service.js";
+import {
+  __testing as sessionBindingTesting,
+  type SessionBindingCapabilities,
+  type SessionBindingRecord,
+} from "../../../src/infra/outbound/session-binding-service.js";
 import { resetPluginRuntimeStateForTest } from "../../../src/plugins/runtime.js";
 import { loadBundledPluginTestApiSync } from "../../../src/test-utils/bundled-plugin-public-surface.js";
 
@@ -67,6 +70,41 @@ function resolveSessionBindingContractRuntimeConfig(id: string) {
   };
 }
 
+function installSessionBindingContractSuite(params: {
+  getCapabilities: () => SessionBindingCapabilities | Promise<SessionBindingCapabilities>;
+  bindAndResolve: () => Promise<SessionBindingRecord>;
+  unbindAndVerify: (binding: SessionBindingRecord) => Promise<void>;
+  cleanup: () => Promise<void> | void;
+  expectedCapabilities: SessionBindingCapabilities;
+}) {
+  it("registers the expected session binding capabilities", async () => {
+    expect(await Promise.resolve(params.getCapabilities())).toEqual(params.expectedCapabilities);
+  });
+
+  it("binds and resolves a session binding through the shared service", async () => {
+    const binding = await params.bindAndResolve();
+    expect(typeof binding.bindingId).toBe("string");
+    expect(binding.bindingId.trim()).not.toBe("");
+    expect(typeof binding.targetSessionKey).toBe("string");
+    expect(binding.targetSessionKey.trim()).not.toBe("");
+    expect(["session", "subagent"]).toContain(binding.targetKind);
+    expect(typeof binding.conversation.channel).toBe("string");
+    expect(typeof binding.conversation.accountId).toBe("string");
+    expect(typeof binding.conversation.conversationId).toBe("string");
+    expect(["active", "ending", "ended"]).toContain(binding.status);
+    expect(typeof binding.boundAt).toBe("number");
+  });
+
+  it("unbinds a registered binding through the shared service", async () => {
+    const binding = await params.bindAndResolve();
+    await params.unbindAndVerify(binding);
+  });
+
+  it("cleans up registered bindings", async () => {
+    await params.cleanup();
+  });
+}
+
 export function describeSessionBindingRegistryBackedContract(id: string) {
   const entry = getSessionBindingContractRegistry().find((item) => item.id === id);
   if (!entry) {

test/helpers/channels/surface-contract-suite.ts

@@ -0,0 +1,138 @@
+import { expect, it } from "vitest";
+import type { ChannelPlugin } from "../../../src/channels/plugins/types.js";
+
+export function installChannelSurfaceContractSuite(params: {
+  plugin: Pick<
+    ChannelPlugin,
+    | "id"
+    | "actions"
+    | "setup"
+    | "status"
+    | "outbound"
+    | "messaging"
+    | "threading"
+    | "directory"
+    | "gateway"
+  >;
+  surface:
+    | "actions"
+    | "setup"
+    | "status"
+    | "outbound"
+    | "messaging"
+    | "threading"
+    | "directory"
+    | "gateway";
+}) {
+  const { plugin, surface } = params;
+
+  it(`exposes the ${surface} surface contract`, () => {
+    if (surface === "actions") {
+      expect(plugin.actions).toBeDefined();
+      expect(typeof plugin.actions?.describeMessageTool).toBe("function");
+      return;
+    }
+
+    if (surface === "setup") {
+      expect(plugin.setup).toBeDefined();
+      expect(typeof plugin.setup?.applyAccountConfig).toBe("function");
+      return;
+    }
+
+    if (surface === "status") {
+      expect(plugin.status).toBeDefined();
+      expect(typeof plugin.status?.buildAccountSnapshot).toBe("function");
+      return;
+    }
+
+    if (surface === "outbound") {
+      const outbound = plugin.outbound;
+      expect(outbound).toBeDefined();
+      expect(["direct", "gateway", "hybrid"]).toContain(outbound?.deliveryMode);
+      expect(
+        [
+          outbound?.sendPayload,
+          outbound?.sendFormattedText,
+          outbound?.sendFormattedMedia,
+          outbound?.sendText,
+          outbound?.sendMedia,
+          outbound?.sendPoll,
+        ].some((value) => typeof value === "function"),
+      ).toBe(true);
+      return;
+    }
+
+    if (surface === "messaging") {
+      const messaging = plugin.messaging;
+      expect(messaging).toBeDefined();
+      expect(
+        [
+          messaging?.normalizeTarget,
+          messaging?.parseExplicitTarget,
+          messaging?.inferTargetChatType,
+          messaging?.buildCrossContextComponents,
+          messaging?.enableInteractiveReplies,
+          messaging?.hasStructuredReplyPayload,
+          messaging?.formatTargetDisplay,
+          messaging?.resolveOutboundSessionRoute,
+        ].some((value) => typeof value === "function"),
+      ).toBe(true);
+      if (messaging?.targetResolver) {
+        if (messaging.targetResolver.looksLikeId) {
+          expect(typeof messaging.targetResolver.looksLikeId).toBe("function");
+        }
+        if (messaging.targetResolver.hint !== undefined) {
+          expect(typeof messaging.targetResolver.hint).toBe("string");
+          expect(messaging.targetResolver.hint.trim()).not.toBe("");
+        }
+        if (messaging.targetResolver.resolveTarget) {
+          expect(typeof messaging.targetResolver.resolveTarget).toBe("function");
+        }
+      }
+      return;
+    }
+
+    if (surface === "threading") {
+      const threading = plugin.threading;
+      expect(threading).toBeDefined();
+      expect(
+        [
+          threading?.resolveReplyToMode,
+          threading?.buildToolContext,
+          threading?.resolveAutoThreadId,
+          threading?.resolveReplyTransport,
+          threading?.resolveFocusedBinding,
+        ].some((value) => typeof value === "function"),
+      ).toBe(true);
+      return;
+    }
+
+    if (surface === "directory") {
+      const directory = plugin.directory;
+      expect(directory).toBeDefined();
+      expect(
+        [
+          directory?.self,
+          directory?.listPeers,
+          directory?.listPeersLive,
+          directory?.listGroups,
+          directory?.listGroupsLive,
+          directory?.listGroupMembers,
+        ].some((value) => typeof value === "function"),
+      ).toBe(true);
+      return;
+    }
+
+    const gateway = plugin.gateway;
+    expect(gateway).toBeDefined();
+    expect(
+      [
+        gateway?.startAccount,
+        gateway?.stopAccount,
+        gateway?.loginWithQrStart,
+        gateway?.loginWithQrWait,
+        gateway?.logoutAccount,
+      ].some((value) => typeof value === "function"),
+    ).toBe(true);
+  });
+}