@loggie-ai/openclaw-plugin 0.1.0

package/src/doctor.ts

@@ -0,0 +1,39 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
+import { listLoggieAccountIds, resolveLoggieAccount } from "./account.js";
+
+export function collectLoggieDoctorWarnings(params: {
+  cfg: OpenClawConfig;
+  env?: NodeJS.ProcessEnv;
+}): string[] {
+  const warnings: string[] = [];
+  const accountIds = listLoggieAccountIds(params.cfg);
+  if (accountIds.length === 0) {
+    return ["channels.loggie has no configured accounts."];
+  }
+
+  for (const accountId of accountIds) {
+    const account = resolveLoggieAccount(params.cfg, accountId, params.env);
+    const prefix = `channels.loggie account ${account.accountId}`;
+    if (!account.enabled) {
+      warnings.push(`${prefix} is disabled.`);
+      continue;
+    }
+    if (!account.baseUrl) {
+      warnings.push(`${prefix} is missing baseUrl or LOGGIE_BASE_URL.`);
+    }
+    if (!account.agentProfileId) {
+      warnings.push(`${prefix} is missing agentProfileId.`);
+    }
+    if (account.tokenStatus.status !== "available") {
+      warnings.push(`${prefix} token is ${account.tokenStatus.status} (${account.tokenStatus.source}).`);
+    }
+  }
+  return warnings;
+}
+
+export const loggieDoctor = {
+  collectPreviewWarnings: (params: {
+    cfg: OpenClawConfig;
+    env?: NodeJS.ProcessEnv;
+  }) => collectLoggieDoctorWarnings(params),
+};

package/src/event-types.ts

@@ -0,0 +1,105 @@
+import { z } from "zod";
+
+export const LOGGIE_TRANSCRIPT_READY_EVENT = "meeting.transcript.ready";
+
+const transcriptPayloadSchema = z
+  .object({
+    eventId: z.string().optional(),
+    cursor: z.string().optional(),
+    type: z.string().optional(),
+    workspaceId: z.string().optional(),
+    meetingId: z.string().optional(),
+    meetingScheduleId: z.string().optional(),
+    title: z.string().optional(),
+    source: z.string().nullable().optional(),
+    externalId: z.string().nullable().optional(),
+    meetingDate: z.string().datetime().optional(),
+    hasTranscript: z.boolean().optional(),
+    detailPath: z.string().optional(),
+  })
+  .passthrough();
+
+export const loggieEventEnvelopeSchema = z
+  .object({
+    eventId: z.string().min(1),
+    cursor: z.string().min(1).optional(),
+    workspaceId: z.string().min(1),
+    agentProfileId: z.string().min(1).optional(),
+    meetingId: z.string().min(1).optional(),
+    meetingScheduleId: z.string().min(1).optional(),
+    eventType: z.string().min(1),
+    occurredAt: z.string().datetime(),
+    sequence: z.number().int().nonnegative().optional(),
+    payload: z.record(z.unknown()).default({}),
+  })
+  .passthrough()
+  .refine((event) => Boolean(event.meetingId ?? event.meetingScheduleId), {
+    message: "meetingId or meetingScheduleId is required",
+  });
+
+export type LoggieEventEnvelope = z.infer<typeof loggieEventEnvelopeSchema>;
+export type LoggieTranscriptReadyEvent = LoggieEventEnvelope & {
+  eventType: typeof LOGGIE_TRANSCRIPT_READY_EVENT;
+  payload: z.infer<typeof transcriptPayloadSchema>;
+};
+
+export type ParseLoggieEventResult =
+  | { ok: true; event: LoggieEventEnvelope }
+  | { ok: false; reason: string };
+
+export function parseLoggieEventEnvelope(raw: unknown): ParseLoggieEventResult {
+  const candidate =
+    raw && typeof raw === "object" && "event" in raw && (raw as { event?: unknown }).event
+      ? (raw as { event: unknown }).event
+      : raw;
+  const result = loggieEventEnvelopeSchema.safeParse(normalizeLoggieEventCandidate(candidate));
+  if (!result.success) {
+    return { ok: false, reason: result.error.issues.map((issue) => issue.message).join("; ") };
+  }
+  return { ok: true, event: result.data };
+}
+
+export function isTranscriptReadyEvent(event: LoggieEventEnvelope): event is LoggieTranscriptReadyEvent {
+  if (event.eventType !== LOGGIE_TRANSCRIPT_READY_EVENT) {
+    return false;
+  }
+  return transcriptPayloadSchema.safeParse(event.payload).success;
+}
+
+function normalizeLoggieEventCandidate(candidate: unknown): unknown {
+  if (!candidate || typeof candidate !== "object" || Array.isArray(candidate)) {
+    return candidate;
+  }
+  const record = candidate as Record<string, unknown>;
+  const payload = record.payload && typeof record.payload === "object" && !Array.isArray(record.payload)
+    ? (record.payload as Record<string, unknown>)
+    : {};
+  const eventType = readString(record.eventType) ?? readString(record.type);
+  const cursor = readString(record.cursor) ?? readString(payload.cursor);
+  const sequence = typeof record.sequence === "number" ? record.sequence : undefined;
+  const eventId =
+    readString(record.eventId) ??
+    readString(payload.eventId) ??
+    cursor;
+  return {
+    ...record,
+    eventId,
+    cursor,
+    workspaceId: readString(record.workspaceId) ?? readString(payload.workspaceId),
+    agentProfileId: readString(record.agentProfileId) ?? readString(payload.agentProfileId),
+    meetingId: readString(record.meetingId) ?? readString(payload.meetingId),
+    meetingScheduleId: readString(record.meetingScheduleId) ?? readString(payload.meetingScheduleId),
+    eventType,
+    occurredAt: readString(record.occurredAt) ?? readString(record.createdAt),
+    sequence,
+    payload,
+  };
+}
+
+function readString(value: unknown): string | undefined {
+  if (typeof value !== "string") {
+    return undefined;
+  }
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}

package/src/loggie-client.ts

@@ -0,0 +1,111 @@
+import WebSocket, { type ClientOptions, type RawData } from "ws";
+import type { ResolvedLoggieAccount } from "./account.js";
+import type { LoggieCursorRecord } from "./cursor-store.js";
+
+export type LoggieSocket = {
+  readyState: number;
+  send(data: string): void;
+  close(code?: number, reason?: string): void;
+  on(event: "open", listener: () => void): unknown;
+  on(event: "message", listener: (data: RawData | string) => void): unknown;
+  on(event: "error", listener: (error: Error) => void): unknown;
+  on(event: "close", listener: (code: number, reason: Buffer) => void): unknown;
+};
+
+export type LoggieSocketFactory = (params: {
+  url: string;
+  headers: Record<string, string>;
+}) => LoggieSocket;
+
+export function buildLoggieWebSocketUrl(
+  account: Pick<ResolvedLoggieAccount, "baseUrl" | "socketPath">,
+  cursor?: LoggieCursorRecord,
+): string {
+  const url = new URL(account.baseUrl);
+  url.protocol = url.protocol === "https:" ? "wss:" : url.protocol === "http:" ? "ws:" : url.protocol;
+  if (!url.protocol.startsWith("ws")) {
+    throw new Error(`Unsupported Loggie baseUrl protocol: ${url.protocol}`);
+  }
+  url.pathname = account.socketPath.startsWith("/") ? account.socketPath : `/${account.socketPath}`;
+  url.search = "";
+  const replayCursor = readReplayCursor(cursor);
+  if (replayCursor) {
+    url.searchParams.set("cursor", replayCursor);
+  }
+  return url.toString();
+}
+
+export function buildLoggieAuthHeaders(account: Pick<ResolvedLoggieAccount, "authHeader" | "tokenStatus">): Record<string, string> {
+  if (account.tokenStatus.status !== "available") {
+    throw new Error(`Loggie token is not available (${account.tokenStatus.status})`);
+  }
+  return account.authHeader === "x-api-key"
+    ? { "x-api-key": account.tokenStatus.value }
+    : { authorization: `Bearer ${account.tokenStatus.value}` };
+}
+
+export function buildLoggieDetailUrl(
+  account: Pick<ResolvedLoggieAccount, "baseUrl">,
+  detailPath: string,
+): string {
+  const base = new URL(account.baseUrl);
+  const url = new URL(detailPath, base);
+  if (url.origin !== base.origin) {
+    throw new Error("Loggie transcript detail URL must stay on the configured Loggie origin");
+  }
+  return url.toString();
+}
+
+export async function fetchLoggieTranscriptDetail(params: {
+  account: Pick<ResolvedLoggieAccount, "baseUrl" | "authHeader" | "tokenStatus">;
+  detailPath: string;
+  fetchImpl?: typeof fetch;
+}): Promise<unknown> {
+  const fetchImpl = params.fetchImpl ?? fetch;
+  const response = await fetchImpl(buildLoggieDetailUrl(params.account, params.detailPath), {
+    headers: buildLoggieAuthHeaders(params.account),
+  });
+  if (!response.ok) {
+    throw new Error(`Loggie transcript detail fetch failed with HTTP ${response.status}`);
+  }
+  const contentType = response.headers.get("content-type") ?? "";
+  if (contentType.includes("application/json")) {
+    return response.json();
+  }
+  return response.text();
+}
+
+export const defaultLoggieSocketFactory: LoggieSocketFactory = ({ url, headers }) => {
+  const options: ClientOptions = { headers };
+  return new WebSocket(url, options);
+};
+
+export function buildLoggiePingMessage(): { type: "ping" } {
+  return { type: "ping" };
+}
+
+export function buildLoggieResumeMessage(cursor: string): { type: "resume"; cursor: string } {
+  return { type: "resume", cursor };
+}
+
+export function decodeLoggieSocketMessage(data: RawData | string): unknown {
+  const text =
+    typeof data === "string"
+      ? data
+      : Buffer.isBuffer(data)
+        ? data.toString("utf8")
+        : Array.isArray(data)
+          ? Buffer.concat(data).toString("utf8")
+          : Buffer.from(data).toString("utf8");
+  return JSON.parse(text);
+}
+
+function readReplayCursor(cursor: LoggieCursorRecord | undefined): string | undefined {
+  if (!cursor) {
+    return undefined;
+  }
+  if (cursor.lastCursor) {
+    return cursor.lastCursor;
+  }
+  return typeof cursor.lastSequence === "number" ? String(cursor.lastSequence) : undefined;
+}

package/src/monitor/connection.ts

@@ -0,0 +1,349 @@
+import type { OpenClawConfig, PluginRuntime } from "openclaw/plugin-sdk/channel-core";
+import type { ResolvedLoggieAccount } from "../account.js";
+import { createRuntimeCursorStore, type LoggieCursorStore } from "../cursor-store.js";
+import {
+  buildLoggieAuthHeaders,
+  buildLoggiePingMessage,
+  buildLoggieResumeMessage,
+  buildLoggieWebSocketUrl,
+  decodeLoggieSocketMessage,
+  defaultLoggieSocketFactory,
+  type LoggieSocketFactory,
+} from "../loggie-client.js";
+import { createOpenClawTranscriptDispatcher, type TranscriptDispatcher } from "./transcript-dispatch.js";
+import { handleLoggieEvent } from "./event-handler.js";
+
+type ChannelRuntime = PluginRuntime["channel"];
+
+export type MonitorLoggieAccountParams = {
+  account: ResolvedLoggieAccount;
+  cfg: OpenClawConfig;
+  runtime: PluginRuntime;
+  channelRuntime?: ChannelRuntime;
+  abortSignal?: AbortSignal;
+  setStatus?: (next: Record<string, unknown>) => void;
+  getStatus?: () => Record<string, unknown>;
+  log?: {
+    info?: (message: string) => void;
+    warn?: (message: string) => void;
+  };
+  cursorStore?: LoggieCursorStore;
+  dispatcher?: TranscriptDispatcher;
+  socketFactory?: LoggieSocketFactory;
+  sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+};
+
+export async function monitorLoggieAccount(params: MonitorLoggieAccountParams): Promise<void> {
+  if (!params.account.enabled) {
+    params.log?.info?.(`[${params.account.accountId}] Loggie account disabled`);
+    return;
+  }
+  if (!params.account.configured) {
+    throw new Error(`Loggie account ${params.account.accountId} is not configured`);
+  }
+  if (!params.channelRuntime && !params.dispatcher) {
+    throw new Error("Loggie channelRuntime is required for transcript dispatch");
+  }
+
+  const cursorStore = params.cursorStore ?? createRuntimeCursorStore(params.runtime);
+  const dispatcher =
+    params.dispatcher ??
+    createOpenClawTranscriptDispatcher({
+      account: params.account,
+      cfg: params.cfg,
+      runtime: params.runtime,
+      channelRuntime: params.channelRuntime!,
+      abortSignal: params.abortSignal,
+    });
+  const sleep = params.sleep ?? defaultSleep;
+  let attempts = 0;
+
+  while (!params.abortSignal?.aborted) {
+    try {
+      await runLoggieSocketOnce({
+        ...params,
+        cursorStore,
+        dispatcher,
+        socketFactory: params.socketFactory ?? defaultLoggieSocketFactory,
+      });
+      attempts = 0;
+    } catch (error) {
+      if (params.abortSignal?.aborted) {
+        return;
+      }
+      attempts += 1;
+      const delayMs = Math.min(
+        params.account.reconnect.maxMs,
+        params.account.reconnect.minMs * 2 ** Math.max(0, attempts - 1),
+      );
+      params.setStatus?.({
+        ...(params.getStatus?.() ?? { accountId: params.account.accountId }),
+        running: true,
+        connected: false,
+        authenticated: false,
+        reconnectAttempts: attempts,
+        lastError: error instanceof Error ? error.message : String(error),
+      });
+      params.log?.warn?.(
+        `[${params.account.accountId}] Loggie socket failed; reconnecting in ${delayMs}ms`,
+      );
+      await sleep(delayMs, params.abortSignal);
+    }
+  }
+}
+
+export async function runLoggieSocketOnce(params: MonitorLoggieAccountParams & {
+  cursorStore: LoggieCursorStore;
+  dispatcher: TranscriptDispatcher;
+  socketFactory: LoggieSocketFactory;
+}): Promise<void> {
+  const cursor = await params.cursorStore.load(params.account.accountId, params.account.agentProfileId);
+  const ws = params.socketFactory({
+    url: buildLoggieWebSocketUrl(params.account, cursor),
+    headers: buildLoggieAuthHeaders(params.account),
+  });
+  params.setStatus?.({
+    ...(params.getStatus?.() ?? { accountId: params.account.accountId }),
+    running: true,
+    connected: false,
+    authenticated: false,
+    lastStartAt: Date.now(),
+  });
+
+  await new Promise<void>((resolve, reject) => {
+    let settled = false;
+    let stoppedByAbort = false;
+    let heartbeatTimeout: NodeJS.Timeout | undefined;
+    let pingInterval: NodeJS.Timeout | undefined;
+    let eventQueue = Promise.resolve();
+    const pendingMessages = new Set<Promise<void>>();
+    const clearHeartbeat = () => {
+      if (heartbeatTimeout) {
+        clearTimeout(heartbeatTimeout);
+        heartbeatTimeout = undefined;
+      }
+    };
+    const clearPing = () => {
+      if (pingInterval) {
+        clearInterval(pingInterval);
+        pingInterval = undefined;
+      }
+    };
+    const finish = (fn: () => void) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearHeartbeat();
+      clearPing();
+      params.abortSignal?.removeEventListener("abort", closeOnAbort);
+      fn();
+    };
+    const failSocket = (error: Error, options?: { waitForPending?: boolean }) => {
+      clearPing();
+      try {
+        ws.close(1011, error.message);
+      } catch {
+        // Ignore close errors and report the original failure.
+      }
+      if (options?.waitForPending) {
+        void Promise.allSettled([...pendingMessages]).then(() => finish(() => reject(error)));
+        return;
+      }
+      finish(() => reject(error));
+    };
+    const resetHeartbeat = () => {
+      clearHeartbeat();
+      heartbeatTimeout = setTimeout(() => {
+        failSocket(new Error("Loggie heartbeat timeout"), { waitForPending: true });
+      }, params.account.heartbeat.timeoutMs);
+      heartbeatTimeout.unref?.();
+    };
+    const startPing = () => {
+      clearPing();
+      const intervalMs = Math.max(250, Math.floor(params.account.heartbeat.timeoutMs / 2));
+      pingInterval = setInterval(() => {
+        try {
+          ws.send(JSON.stringify(buildLoggiePingMessage()));
+        } catch (error) {
+          failSocket(error instanceof Error ? error : new Error(String(error)), { waitForPending: true });
+        }
+      }, intervalMs);
+      pingInterval.unref?.();
+    };
+    const closeOnAbort = () => {
+      stoppedByAbort = true;
+      ws.close(1000, "OpenClaw Loggie monitor stopped");
+    };
+    params.abortSignal?.addEventListener("abort", closeOnAbort, { once: true });
+    ws.on("open", () => {
+      resetHeartbeat();
+      startPing();
+      void (async () => {
+        const connectedAt = Date.now();
+        params.setStatus?.({
+          ...(params.getStatus?.() ?? { accountId: params.account.accountId }),
+          running: true,
+          connected: true,
+          authenticated: true,
+          reconnectAttempts: 0,
+          lastConnectedAt: connectedAt,
+          lastError: null,
+        });
+        await params.cursorStore.save({
+          ...(cursor ?? {
+            accountId: params.account.accountId,
+            agentProfileId: params.account.agentProfileId,
+            seenEventIds: [],
+            updatedAt: new Date(connectedAt).toISOString(),
+          }),
+          lastConnectedAt: connectedAt,
+          updatedAt: new Date(connectedAt).toISOString(),
+        });
+      })().catch((error) => {
+        ws.close(1011, error instanceof Error ? error.message : "Loggie open initialization failed");
+        finish(() => reject(error));
+      });
+    });
+    ws.on("message", (data) => {
+      resetHeartbeat();
+      let decoded: unknown;
+      try {
+        decoded = decodeLoggieSocketMessage(data);
+      } catch (error) {
+        failSocket(error instanceof Error ? error : new Error(String(error)));
+        return;
+      }
+      const control = parseControlMessage(decoded);
+      if (control.type === "ignore") {
+        return;
+      }
+      if (control.type === "resume") {
+        try {
+          ws.send(JSON.stringify(buildLoggieResumeMessage(control.cursor)));
+        } catch (error) {
+          failSocket(error instanceof Error ? error : new Error(String(error)), { waitForPending: true });
+        }
+        return;
+      }
+      if (control.type === "error") {
+        failSocket(new Error(control.error), { waitForPending: true });
+        return;
+      }
+      const task = eventQueue.then(async () => {
+        const result = await handleLoggieEvent({
+          raw: decoded,
+          account: params.account,
+          cursorStore: params.cursorStore,
+          dispatcher: params.dispatcher,
+        });
+        if (result.status === "failed") {
+          throw new Error(result.reason);
+        }
+        const eventAt = Date.now();
+        const deadLettered = result.status === "skipped" ? result.deadLettered : undefined;
+        if (deadLettered && result.event) {
+          params.log?.warn?.(
+            `[${params.account.accountId}] Loggie event ${result.event.eventId} dead-lettered after ${deadLettered.attempts} attempts: ${deadLettered.reason}`,
+          );
+        }
+        params.setStatus?.({
+          ...(params.getStatus?.() ?? { accountId: params.account.accountId }),
+          running: true,
+          connected: true,
+          authenticated: true,
+          caughtUp: true,
+          lastEventAt: eventAt,
+          ...(result.status === "dispatched" ? { lastDispatchAt: eventAt } : {}),
+          ...(deadLettered && result.event
+            ? {
+                lastDeadLetterAt: eventAt,
+                lastDeadLetteredEventId: result.event.eventId,
+                lastDeadLetteredCursor: result.event.cursor ?? null,
+                lastDeadLetterReason: deadLettered.reason,
+                lastDeadLetterAttempts: deadLettered.attempts,
+              }
+            : {}),
+          lastEventId: result.event?.eventId ?? null,
+          lastCursor: result.event?.cursor ?? null,
+          lastSequence: result.event?.sequence ?? null,
+        });
+      });
+      eventQueue = task.catch(() => undefined);
+      pendingMessages.add(task);
+      void task
+        .catch((error) => {
+          ws.close(1011, error instanceof Error ? error.message : "Loggie event handling failed");
+          finish(() => reject(error));
+        })
+        .finally(() => {
+          pendingMessages.delete(task);
+        });
+    });
+    ws.on("error", (error) => finish(() => reject(error)));
+    ws.on("close", (code, reason) => {
+      clearHeartbeat();
+      clearPing();
+      const reasonText = reason.toString("utf8");
+      void Promise.allSettled([...pendingMessages]).then(() => {
+        if (stoppedByAbort || params.abortSignal?.aborted) {
+          finish(resolve);
+          return;
+        }
+        finish(() =>
+          reject(
+            new Error(
+              `Loggie socket closed unexpectedly (${code}${reasonText ? `: ${reasonText}` : ""})`,
+            ),
+          ),
+        );
+      });
+    });
+  });
+}
+
+type ControlMessageDecision =
+  | { type: "none" }
+  | { type: "ignore" }
+  | { type: "resume"; cursor: string }
+  | { type: "error"; error: string };
+
+function parseControlMessage(value: unknown): ControlMessageDecision {
+  if (value === null || typeof value !== "object" || !("type" in value)) {
+    return { type: "none" };
+  }
+  const record = value as { type?: unknown; cursor?: unknown; error?: unknown };
+  if (record.type === "hello" || record.type === "pong" || record.type === "ack") {
+    return { type: "ignore" };
+  }
+  if (record.type === "loggie.events.more_available") {
+    return typeof record.cursor === "string" && record.cursor.trim().length > 0
+      ? { type: "resume", cursor: record.cursor.trim() }
+      : { type: "error", error: "Loggie replay cursor missing from more_available message" };
+  }
+  if (record.type === "error") {
+    return {
+      type: "error",
+      error: typeof record.error === "string" ? record.error : "Loggie socket returned an error",
+    };
+  }
+  return { type: "none" };
+}
+
+function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> {
+  return new Promise((resolve) => {
+    if (signal?.aborted) {
+      resolve();
+      return;
+    }
+    const timeout = setTimeout(resolve, ms);
+    signal?.addEventListener(
+      "abort",
+      () => {
+        clearTimeout(timeout);
+        resolve();
+      },
+      { once: true },
+    );
+  });
+}