zapry-openclaw-plugin 0.0.1

package/src/monitor.ts

@@ -0,0 +1,144 @@
+import { ZapryApiClient } from "./api-client.js";
+import { processZapryInboundUpdate, tryHandleZapryInboundQuickPaths } from "./inbound.js";
+import type { ResolvedZapryAccount } from "./types.js";
+
+export type MonitorContext = {
+  account: ResolvedZapryAccount;
+  cfg?: any;
+  runtime?: any;
+  abortSignal?: AbortSignal;
+  statusSink?: (patch: { lastInboundAt?: number; lastOutboundAt?: number }) => void;
+  log?: {
+    info: (...args: any[]) => void;
+    warn: (...args: any[]) => void;
+    error?: (...args: any[]) => void;
+    debug?: (...args: any[]) => void;
+  };
+};
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  if (!value || typeof value !== "object") {
+    return null;
+  }
+  return value as Record<string, unknown>;
+}
+
+function summarizeUnhandledInboundUpdate(update: unknown): string {
+  const record = asRecord(update);
+  if (!record) {
+    return "non-object update payload";
+  }
+  const topKeys = Object.keys(record);
+  const messageLike =
+    asRecord(record.message) ??
+    asRecord(record.channel_post) ??
+    asRecord(record.edited_message) ??
+    asRecord(record.edited_channel_post) ??
+    asRecord((record.callback_query as any)?.message) ??
+    asRecord(record.msg) ??
+    asRecord(record.Message);
+  const messageKeys = messageLike ? Object.keys(messageLike) : [];
+  return `top_keys=${JSON.stringify(topKeys.slice(0, 20))} message_keys=${JSON.stringify(messageKeys.slice(0, 24))}`;
+}
+
+export async function monitorZapryProvider(ctx: MonitorContext): Promise<void> {
+  const { account } = ctx;
+  if (account.config.mode === "webhook") {
+    await startWebhookMode(ctx);
+  } else {
+    await startPollingMode(ctx);
+  }
+}
+
+async function dispatchInboundUpdate(ctx: MonitorContext, update: any): Promise<boolean> {
+  const { statusSink, log } = ctx;
+
+  // Priority quick paths: handle deterministic moderation actions before any host callback mode.
+  const handledByQuickPath = await tryHandleZapryInboundQuickPaths({
+    account: ctx.account,
+    update,
+    statusSink,
+    log,
+  });
+  if (handledByQuickPath) {
+    return true;
+  }
+
+  return processZapryInboundUpdate({
+    account: ctx.account,
+    cfg: ctx.cfg,
+    runtime: ctx.runtime,
+    update,
+    statusSink,
+    log,
+  });
+}
+
+async function startPollingMode(ctx: MonitorContext): Promise<void> {
+  const { account, abortSignal, log } = ctx;
+  const client = new ZapryApiClient(account.config.apiBaseUrl, account.botToken);
+
+  await client.deleteWebhook();
+  log?.info(`[${account.accountId}] polling mode started`);
+
+  let offset = 0;
+  let warnedMissingInboundHandler = false;
+  let loggedUnhandledSample = false;
+  let lastPollingApiError = "";
+  while (!abortSignal?.aborted) {
+    try {
+      const resp = await client.getUpdates(offset, 100, 30);
+      if (!resp.ok) {
+        const errorSig = `${resp.error_code ?? "unknown"}:${resp.description ?? "unknown"}`;
+        if (errorSig !== lastPollingApiError) {
+          lastPollingApiError = errorSig;
+          log?.warn(`[${account.accountId}] getUpdates failed: ${errorSig}`);
+        }
+        await sleep(3000);
+        continue;
+      }
+
+      lastPollingApiError = "";
+      if (!Array.isArray(resp.result)) {
+        continue;
+      }
+
+      for (const update of resp.result) {
+        const handled = await dispatchInboundUpdate(ctx, update);
+        if (!handled && !warnedMissingInboundHandler) {
+          warnedMissingInboundHandler = true;
+          log?.warn(
+            `[${account.accountId}] inbound update received but no compatible handler is available`,
+          );
+        }
+        if (!handled && !loggedUnhandledSample) {
+          loggedUnhandledSample = true;
+          log?.warn(
+            `[${account.accountId}] unhandled inbound update sample: ${summarizeUnhandledInboundUpdate(update)}`,
+          );
+        }
+        const updateId = (update as any).update_id;
+        if (typeof updateId === "number" && updateId >= offset) {
+          offset = updateId + 1;
+        }
+      }
+    } catch (err) {
+      if (abortSignal?.aborted) break;
+      log?.warn(`[${account.accountId}] polling error: ${String(err)}`);
+      await sleep(3000);
+    }
+  }
+  log?.info(`[${account.accountId}] polling stopped`);
+}
+
+async function startWebhookMode(ctx: MonitorContext): Promise<void> {
+  const { account, log } = ctx;
+  log?.warn(
+    `[${account.accountId}] webhook inbound mode has been removed from the plugin runtime, falling back to polling`,
+  );
+  return startPollingMode(ctx);
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/src/profile-sync.ts

@@ -0,0 +1,195 @@
+import { createHash } from "node:crypto";
+import { readFile, readdir } from "node:fs/promises";
+import { join, relative, basename } from "node:path";
+import { ZapryApiClient } from "./api-client.js";
+import type {
+  ProfileSource,
+  ProfileSourceSkill,
+  ResolvedZapryAccount,
+} from "./types.js";
+
+const SKILL_KEY_RE = /^\s*skillKey:\s*["']?([^"'\n]+)["']?\s*$/m;
+const SKILL_VERSION_RE = /^\s*skillVersion:\s*["']?([^"'\n]+)["']?\s*$/m;
+const GENERIC_VERSION_RE = /^\s*version:\s*["']?([^"'\n]+)["']?\s*$/m;
+
+// ── Public entry ──
+
+export async function syncProfileToZapry(
+  account: ResolvedZapryAccount,
+  opts?: { projectRoot?: string; log?: any },
+): Promise<void> {
+  const log = opts?.log;
+  const projectRoot = opts?.projectRoot || process.cwd();
+
+  const soulPath = join(projectRoot, "SOUL.md");
+  const soulRaw = await readFileSafe(soulPath);
+  if (!soulRaw) {
+    log?.debug?.(`[profile-sync] No SOUL.md found at ${soulPath}, skipping`);
+    return;
+  }
+
+  const skills = await collectSkills(join(projectRoot, "skills"), projectRoot);
+  if (skills.length === 0) {
+    log?.debug?.(`[profile-sync] No skills found under ${join(projectRoot, "skills")}, skipping`);
+    return;
+  }
+
+  const agentKey = basename(projectRoot);
+  const snapshotId = computeSnapshotId(soulRaw, skills);
+
+  const profileSource: ProfileSource = {
+    version: "v1",
+    source: "openclaw-plugin",
+    agentKey,
+    snapshotId,
+    soulMd: soulRaw,
+    skills,
+  };
+
+  const client = new ZapryApiClient(account.config.apiBaseUrl, account.botToken);
+
+  log?.info?.(
+    `[profile-sync] Registering profile: agent=${agentKey} skills=${skills.map((s) => s.skillKey).join(",")} snapshot=${snapshotId.slice(0, 12)}…`,
+  );
+
+  const resp = await client.setMyProfile({ profileSource });
+
+  if (resp.ok) {
+    const derived = (resp.result as any)?.derived ?? (resp as any).derived;
+    const derivedName = derived?.profile?.name ?? "";
+    const derivedSkills = derived?.profile?.skills?.length ?? 0;
+    log?.info?.(
+      `[profile-sync] Profile registered: name=${derivedName} derivedSkills=${derivedSkills} snapshot=${derived?.snapshotId?.slice(0, 12) ?? "?"}`,
+    );
+
+    const soulName = deriveNameFromSoul(soulRaw);
+    if (soulName) {
+      try {
+        await client.setMyName(soulName);
+        log?.info?.(`[profile-sync] Name synced: ${soulName}`);
+      } catch (err) {
+        log?.warn?.(
+          `[profile-sync] setMyName fallback failed: ${err instanceof Error ? err.message : String(err)}`,
+        );
+      }
+    }
+  } else {
+    log?.warn?.(
+      `[profile-sync] setMyProfile failed: ${resp.error_code ?? "?"} ${resp.description ?? "unknown"}`,
+    );
+  }
+}
+
+// ── File discovery ──
+
+async function readFileSafe(path: string): Promise<string | null> {
+  try {
+    return await readFile(path, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+async function collectSkills(
+  skillsRoot: string,
+  projectRoot: string,
+): Promise<ProfileSourceSkill[]> {
+  let entries: string[];
+  try {
+    entries = await readdir(skillsRoot);
+  } catch {
+    return [];
+  }
+
+  const skills: ProfileSourceSkill[] = [];
+
+  for (const entry of entries.sort()) {
+    const skillMdPath = join(skillsRoot, entry, "SKILL.md");
+    const raw = await readFileSafe(skillMdPath);
+    if (!raw) continue;
+
+    const frontmatter = extractFrontmatter(raw);
+    const relPath = relative(projectRoot, skillMdPath).replace(/\\/g, "/");
+    const skillKey = extractField(SKILL_KEY_RE, frontmatter) || entry;
+    const skillVersion =
+      extractField(SKILL_VERSION_RE, frontmatter) ||
+      extractField(GENERIC_VERSION_RE, frontmatter) ||
+      "1.0.0";
+
+    skills.push({
+      skillKey,
+      skillVersion,
+      source: "local",
+      path: relPath,
+      content: raw,
+      sha256: sha256Hex(raw),
+      bytes: Buffer.byteLength(raw, "utf-8"),
+    });
+  }
+
+  return skills;
+}
+
+// ── Name extraction (mirrors Go SDK deriveNameFromSoul) ──
+
+function deriveNameFromSoul(soul: string): string {
+  const lines = soul.replace(/\r\n/g, "\n").split("\n");
+  for (const line of lines) {
+    const text = line.trim();
+    if (text.startsWith("#")) {
+      let title = text.replace(/^#+\s*/, "");
+      title = title.replace(/^SOUL\.md\s*-\s*/i, "").trim();
+      return title;
+    }
+  }
+  return "";
+}
+
+// ── Frontmatter / field extraction ──
+
+function extractFrontmatter(content: string): string {
+  const normalized = content.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  if (!normalized.startsWith("---\n")) return "";
+  const lines = normalized.split("\n");
+  for (let i = 1; i < lines.length; i++) {
+    if (lines[i].trim() === "---") {
+      return lines.slice(1, i).join("\n");
+    }
+  }
+  return "";
+}
+
+function extractField(re: RegExp, text: string): string {
+  const m = re.exec(text);
+  return m?.[1]?.trim() ?? "";
+}
+
+// ── Snapshot ID (matches Go SDK algorithm) ──
+
+function computeSnapshotId(soulMd: string, skills: ProfileSourceSkill[]): string {
+  const normalizedSoul = normalizeSoulMarkdown(soulMd);
+  const normalizedIndex = normalizeSkillsIndex(skills);
+  return sha256Hex(normalizedSoul + "\n" + normalizedIndex);
+}
+
+function normalizeSoulMarkdown(content: string): string {
+  let c = content.replace(/^\uFEFF/, "");
+  c = c.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
+  c = c
+    .split("\n")
+    .map((line) => line.replace(/[ \t]+$/, ""))
+    .join("\n");
+  return c.replace(/[ \t\n]+$/, "");
+}
+
+function normalizeSkillsIndex(skills: ProfileSourceSkill[]): string {
+  const sorted = [...skills].sort((a, b) => {
+    if (a.skillKey === b.skillKey) return a.skillVersion < b.skillVersion ? -1 : 1;
+    return a.skillKey < b.skillKey ? -1 : 1;
+  });
+  return sorted.map((s) => `${s.skillKey}|${s.skillVersion || "1.0.0"}|${s.sha256}`).join("\n");
+}
+
+function sha256Hex(data: string): string {
+  return createHash("sha256").update(data, "utf-8").digest("hex");
+}

package/src/runtime.ts

@@ -0,0 +1,66 @@
+import { AsyncLocalStorage } from "node:async_hooks";
+
+type PluginRuntime = any;
+
+export type ZaprySkillInvocationContext = {
+  senderId: string;
+  messageSid?: string;
+  sessionKey?: string;
+  accountId?: string;
+  chatId?: string;
+};
+
+let _runtime: PluginRuntime | null = null;
+const _skillInvocationContext = new AsyncLocalStorage<ZaprySkillInvocationContext>();
+
+export function setZapryRuntime(runtime: PluginRuntime): void {
+  _runtime = runtime;
+}
+
+export function getZapryRuntime(): PluginRuntime {
+  if (!_runtime) {
+    throw new Error("Zapry plugin runtime not initialized");
+  }
+  return _runtime;
+}
+
+export function runWithZaprySkillInvocationContext<T>(
+  ctx: ZaprySkillInvocationContext,
+  fn: () => T,
+): T {
+  return _skillInvocationContext.run(ctx, fn);
+}
+
+export function getZaprySkillInvocationContext(): ZaprySkillInvocationContext | null {
+  return _skillInvocationContext.getStore() ?? null;
+}
+
+export function buildZaprySkillRequestHeaders(input: {
+  senderId?: string;
+  messageSid?: string;
+}): Record<string, string> {
+  const senderId = String(input.senderId ?? "").trim();
+  if (!senderId) {
+    throw new Error("Zapry skill invocation requires trusted inbound sender context");
+  }
+
+  const headers: Record<string, string> = {
+    "X-Zapry-Invocation-Source": "skill",
+    "X-Zapry-Request-Sender-Id": senderId,
+  };
+
+  const messageSid = String(input.messageSid ?? "").trim();
+  if (messageSid) {
+    headers["X-Zapry-Message-Sid"] = messageSid;
+  }
+
+  return headers;
+}
+
+export function resolveZaprySkillRequestHeaders(): Record<string, string> {
+  const invocationCtx = getZaprySkillInvocationContext();
+  return buildZaprySkillRequestHeaders({
+    senderId: invocationCtx?.senderId,
+    messageSid: invocationCtx?.messageSid,
+  });
+}

package/src/send.ts

@@ -0,0 +1,257 @@
+import { ZapryApiClient } from "./api-client.js";
+import type { ResolvedZapryAccount, ZaprySendResult } from "./types.js";
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+
+const MIME_MAP: Record<string, string> = {
+  ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png",
+  ".webp": "image/webp", ".gif": "image/gif", ".bmp": "image/bmp",
+  ".heic": "image/heic", ".heif": "image/heif",
+  ".mp4": "video/mp4", ".mov": "video/quicktime", ".avi": "video/x-msvideo", ".webm": "video/webm",
+  ".mp3": "audio/mpeg", ".wav": "audio/wav", ".aac": "audio/aac",
+  ".ogg": "audio/ogg", ".opus": "audio/opus", ".m4a": "audio/mp4", ".amr": "audio/amr",
+  ".flac": "audio/flac",
+};
+
+const IMAGE_EXTS = new Set(["jpg", "jpeg", "png", "webp", "bmp", "heic", "heif"]);
+const ANIMATION_EXTS = new Set(["gif"]);
+const VIDEO_EXTS = new Set(["mp4", "mov", "avi", "webm"]);
+const VOICE_EXTS = new Set(["opus", "ogg", "oga", "amr", "m4a"]);
+const AUDIO_EXTS = new Set(["mp3", "wav", "aac", "flac", "m4b"]);
+const EXTERNAL_IMAGE_FETCH_TIMEOUT_MS = 15_000;
+const MAX_EXTERNAL_IMAGE_BYTES = 10 * 1024 * 1024;
+
+async function toDataUri(localPath: string): Promise<string> {
+  const buf = await readFile(localPath);
+  const ext = extname(localPath).toLowerCase();
+  const mime = MIME_MAP[ext] || "application/octet-stream";
+  return `data:${mime};base64,${buf.toString("base64")}`;
+}
+
+function isLocalPath(url: string): boolean {
+  return /^(\/|~\/|\.\/|\.\.\/)/.test(url) || /^[a-zA-Z]:\\/.test(url);
+}
+
+function isHttpUrl(url: string): boolean {
+  return /^https?:\/\//i.test(url);
+}
+
+function extractDataUriMime(source: string): string | null {
+  const match = /^data:([^;,]+)[;,]/i.exec(source.trim());
+  if (!match) {
+    return null;
+  }
+  return String(match[1]).trim().toLowerCase();
+}
+
+function mediaKindFromMime(mime: string): "animation" | "photo" | "video" | "voice" | "audio" | "document" {
+  const normalized = mime.toLowerCase();
+  if (normalized === "image/gif") {
+    return "animation";
+  }
+  if (normalized.startsWith("image/")) {
+    return "photo";
+  }
+  if (normalized.startsWith("video/")) {
+    return "video";
+  }
+  if (normalized.startsWith("audio/")) {
+    if (/(ogg|opus|amr|x-m4a|mp4)/i.test(normalized)) {
+      return "voice";
+    }
+    return "audio";
+  }
+  return "document";
+}
+
+function inferMimeFromPath(pathLike: string): string {
+  const clean = pathLike.split("?")[0]?.split("#")[0] ?? pathLike;
+  const ext = extname(clean).toLowerCase();
+  return MIME_MAP[ext] || "application/octet-stream";
+}
+
+function detectMediaKind(mediaRef: string, originalSource: string): "animation" | "photo" | "video" | "voice" | "audio" | "document" {
+  const dataUriMime = extractDataUriMime(mediaRef);
+  if (dataUriMime) {
+    return mediaKindFromMime(dataUriMime);
+  }
+
+  const clean = (originalSource || mediaRef).split("?")[0]?.split("#")[0] ?? (originalSource || mediaRef);
+  const ext = clean.split(".").pop()?.toLowerCase() ?? "";
+  if (ANIMATION_EXTS.has(ext)) {
+    return "animation";
+  }
+  if (IMAGE_EXTS.has(ext)) {
+    return "photo";
+  }
+  if (VIDEO_EXTS.has(ext)) {
+    return "video";
+  }
+  if (VOICE_EXTS.has(ext)) {
+    return "voice";
+  }
+  if (AUDIO_EXTS.has(ext)) {
+    return "audio";
+  }
+  return "document";
+}
+
+function normalizeContentType(contentType: string | null): string {
+  return String(contentType ?? "")
+    .split(";")[0]
+    .trim()
+    .toLowerCase();
+}
+
+function isGifBinary(binary: Buffer): boolean {
+  if (binary.length < 6) {
+    return false;
+  }
+  const header = binary.subarray(0, 6).toString("ascii");
+  return header === "GIF87a" || header === "GIF89a";
+}
+
+async function readResponseBodyWithSizeLimit(response: Response, maxBytes: number): Promise<Buffer> {
+  const contentLength = Number.parseInt(response.headers.get("content-length") ?? "", 10);
+  if (Number.isFinite(contentLength) && contentLength > maxBytes) {
+    throw new Error(`file is too large (${contentLength} bytes), max ${maxBytes} bytes`);
+  }
+  if (!response.body) {
+    throw new Error("empty response body");
+  }
+
+  const reader = response.body.getReader();
+  const chunks: Buffer[] = [];
+  let total = 0;
+  while (true) {
+    const { done, value } = await reader.read();
+    if (done) {
+      break;
+    }
+    if (!value || value.byteLength === 0) {
+      continue;
+    }
+    total += value.byteLength;
+    if (total > maxBytes) {
+      throw new Error(`file is too large (${total} bytes), max ${maxBytes} bytes`);
+    }
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks, total);
+}
+
+function isAbortError(err: unknown): boolean {
+  if (!err || typeof err !== "object") {
+    return false;
+  }
+  const maybeError = err as { name?: string; code?: string };
+  return maybeError.name === "AbortError" || maybeError.code === "ABORT_ERR";
+}
+
+async function downloadGifAsDataUri(source: string): Promise<string> {
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort(), EXTERNAL_IMAGE_FETCH_TIMEOUT_MS);
+  try {
+    const response = await fetch(source, {
+      method: "GET",
+      signal: controller.signal,
+      redirect: "follow",
+    });
+    if (!response.ok) {
+      throw new Error(`HTTP ${response.status}`);
+    }
+
+    const declaredMime = normalizeContentType(response.headers.get("content-type"));
+    const binary = await readResponseBodyWithSizeLimit(response, MAX_EXTERNAL_IMAGE_BYTES);
+    const inferredMime = inferMimeFromPath(source);
+    const mime = declaredMime || inferredMime;
+    if (mime !== "image/gif" && !isGifBinary(binary)) {
+      throw new Error(
+        `sendAnimation requires GIF source, but got ${JSON.stringify(mime || "unknown")} (tip: use the direct .gif URL)`,
+      );
+    }
+    return `data:image/gif;base64,${binary.toString("base64")}`;
+  } catch (err) {
+    if (isAbortError(err)) {
+      throw new Error(`animation download timed out after ${EXTERNAL_IMAGE_FETCH_TIMEOUT_MS}ms`);
+    }
+    if (err instanceof Error) {
+      throw new Error(`animation download failed: ${err.message}`);
+    }
+    throw new Error("animation download failed");
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function sendMessageZapry(
+  account: ResolvedZapryAccount,
+  to: string,
+  text: string,
+  opts?: {
+    mediaUrl?: string;
+    replyTo?: string;
+    accountId?: string;
+  },
+): Promise<ZaprySendResult> {
+  const client = new ZapryApiClient(account.config.apiBaseUrl, account.botToken);
+  const chatId = normalizeTarget(to);
+
+  if (opts?.mediaUrl) {
+    const originalMediaUrl = opts.mediaUrl.trim();
+    let mediaRef = originalMediaUrl;
+    if (isLocalPath(mediaRef)) {
+      const resolved = mediaRef.replace(/^~/, process.env.HOME || "");
+      mediaRef = await toDataUri(resolved);
+    }
+
+    const initialKind = detectMediaKind(mediaRef, originalMediaUrl);
+    if (initialKind === "animation" && isHttpUrl(mediaRef)) {
+      mediaRef = await downloadGifAsDataUri(mediaRef);
+    }
+
+    const mediaKind = detectMediaKind(mediaRef, originalMediaUrl);
+
+    let resp;
+    switch (mediaKind) {
+      case "animation":
+        resp = await client.sendAnimation(chatId, mediaRef);
+        break;
+      case "photo":
+        resp = await client.sendPhoto(chatId, mediaRef);
+        break;
+      case "video":
+        resp = await client.sendVideo(chatId, mediaRef);
+        break;
+      case "voice":
+        resp = await client.sendVoice(chatId, mediaRef);
+        break;
+      case "audio":
+        resp = await client.sendAudio(chatId, mediaRef);
+        break;
+      default:
+        resp = await client.sendDocument(chatId, mediaRef);
+        break;
+    }
+
+    if (!resp.ok) {
+      return { ok: false, error: resp.description ?? "send media failed" };
+    }
+    const result = resp.result as any;
+    return { ok: true, messageId: result?.message_id };
+  }
+
+  const resp = await client.sendMessage(chatId, text, {
+    replyToMessageId: opts?.replyTo,
+  });
+
+  if (!resp.ok) {
+    return { ok: false, error: resp.description ?? "send message failed" };
+  }
+  const result = resp.result as any;
+  return { ok: true, messageId: result?.message_id };
+}
+
+function normalizeTarget(to: string): string {
+  return to.replace(/^(chat|zapry):/i, "").trim();
+}