openclaw-heychat 2026.2.25

package/src/config-schema.ts

@@ -0,0 +1,38 @@
+import { z } from "zod";
+export { z };
+
+const DmPolicySchema = z.enum(["pairing", "open", "allowlist"]);
+const GroupPolicySchema = z.enum(["open", "allowlist", "disabled"]);
+
+/**
+ * Per-account configuration.
+ * All fields are optional - missing fields inherit from top-level config.
+ */
+export const HeychatAccountConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    name: z.string().optional(), // Display name for this account
+    token: z.string().optional(),
+    tokenFile: z.string().optional(),
+    dmPolicy: DmPolicySchema.optional(),
+    groupPolicy: GroupPolicySchema.optional(),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groups: z.record(z.string(), z.object({ requireMention: z.boolean().optional() }).optional()).optional(),
+  })
+  .strict();
+
+export const HeychatConfigSchema = z
+  .object({
+    enabled: z.boolean().optional(),
+    // Top-level credentials (backward compatible for single-account mode)
+    token: z.string().optional(),
+    tokenFile: z.string().optional(),
+    name: z.string().optional(),
+    dmPolicy: DmPolicySchema.optional().default("pairing"),
+    groupPolicy: GroupPolicySchema.optional().default("open"),
+    allowFrom: z.array(z.union([z.string(), z.number()])).optional(),
+    groups: z.record(z.string(), z.object({ requireMention: z.boolean().optional() }).optional()).optional(),
+    // Multi-account configuration
+    accounts: z.record(z.string(), HeychatAccountConfigSchema.optional()).optional(),
+  })
+  .strict();

package/src/policy.ts

@@ -0,0 +1,99 @@
+import type { AllowlistMatch, ChannelGroupContext, GroupToolPolicyConfig } from "openclaw/plugin-sdk";
+import type { HeychatConfig } from "./types.js";
+
+export type HeychatAllowlistMatch = AllowlistMatch<"wildcard" | "id">;
+
+function normalizeHeychatAllowEntry(raw: string): string {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    return "";
+  }
+  if (trimmed === "*") {
+    return "*";
+  }
+  // Remove heychat: or hc: prefix
+  const withoutProviderPrefix = trimmed.replace(/^(heychat|hc):/i, "");
+  return withoutProviderPrefix.trim().toLowerCase();
+}
+
+export function resolveHeychatAllowlistMatch(params: {
+  allowFrom: Array<string | number>;
+  senderId: string;
+  senderIds?: Array<string | null | undefined>;
+  senderName?: string | null;
+}): HeychatAllowlistMatch {
+  const allowFrom = params.allowFrom
+    .map((entry) => normalizeHeychatAllowEntry(String(entry)))
+    .filter(Boolean);
+  if (allowFrom.length === 0) {
+    return { allowed: false };
+  }
+  if (allowFrom.includes("*")) {
+    return { allowed: true, matchKey: "*", matchSource: "wildcard" };
+  }
+
+  const senderCandidates = [params.senderId, ...(params.senderIds ?? [])]
+    .map((entry) => normalizeHeychatAllowEntry(String(entry ?? "")))
+    .filter(Boolean);
+
+  for (const senderId of senderCandidates) {
+    if (allowFrom.includes(senderId)) {
+      return { allowed: true, matchKey: senderId, matchSource: "id" };
+    }
+  }
+
+  return { allowed: false };
+}
+
+export function resolveHeychatGroupConfig(params: {
+  cfg?: HeychatConfig;
+  groupId?: string | null;
+}): Record<string, { requireMention?: boolean }> | undefined {
+  const groups = params.cfg?.groups ?? {};
+  const groupId = params.groupId?.trim();
+  if (!groupId) {
+    return undefined;
+  }
+
+  const direct = groups[groupId];
+  if (direct) {
+    return direct;
+  }
+
+  const lowered = groupId.toLowerCase();
+  const matchKey = Object.keys(groups).find((key) => key.toLowerCase() === lowered);
+  return matchKey ? groups[matchKey] : undefined;
+}
+
+export function resolveHeychatGroupToolPolicy(
+  params: ChannelGroupContext,
+): GroupToolPolicyConfig | undefined {
+  const cfg = params.cfg.channels?.heychat as HeychatConfig | undefined;
+  if (!cfg) {
+    return undefined;
+  }
+
+  const groupConfig = resolveHeychatGroupConfig({
+    cfg,
+    groupId: params.groupId,
+  });
+
+  return undefined; // Heychat doesn't support tool policies yet
+}
+
+export function isHeychatGroupAllowed(params: {
+  groupPolicy: "open" | "allowlist" | "disabled";
+  allowFrom: Array<string | number>;
+  senderId: string;
+  senderIds?: Array<string | null | undefined>;
+  senderName?: string | null;
+}): boolean {
+  const { groupPolicy } = params;
+  if (groupPolicy === "disabled") {
+    return false;
+  }
+  if (groupPolicy === "open") {
+    return true;
+  }
+  return resolveHeychatAllowlistMatch(params).allowed;
+}

package/src/runtime.ts

@@ -0,0 +1,14 @@
+import type { PluginRuntime } from "openclaw/plugin-sdk";
+
+let runtime: PluginRuntime | null = null;
+
+export function setHeychatRuntime(next: PluginRuntime) {
+  runtime = next;
+}
+
+export function getHeychatRuntime(): PluginRuntime {
+  if (!runtime) {
+    throw new Error("Heychat runtime not initialized");
+  }
+  return runtime;
+}

package/src/types.ts

@@ -0,0 +1,28 @@
+import type { BaseProbeResult } from "openclaw/plugin-sdk";
+import type { HeychatConfigSchema, HeychatAccountConfigSchema, z } from "./config-schema.js";
+
+export type HeychatConfig = z.infer<typeof HeychatConfigSchema>;
+export type HeychatAccountConfig = z.infer<typeof HeychatAccountConfigSchema>;
+
+export type ResolvedHeychatAccount = {
+  accountId: string;
+  enabled: boolean;
+  configured: boolean;
+  name?: string;
+  token?: string;
+  tokenSource: "config" | "file" | "env" | "none";
+  /** Merged config (top-level defaults + account-specific overrides) */
+  config: {
+    dmPolicy?: "pairing" | "open" | "allowlist";
+    groupPolicy?: "open" | "allowlist" | "disabled";
+    allowFrom?: string[];
+    groups?: Record<string, { requireMention?: boolean }>;
+  };
+};
+
+export type HeychatProbeResult = BaseProbeResult<string> & {
+  bot?: {
+    id: string;
+    name: string;
+  };
+};