@loggie-ai/openclaw-plugin 0.1.0

package/src/account.ts

@@ -0,0 +1,265 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
+import {
+  DEFAULT_LOGGIE_ACCOUNT_ID,
+  DEFAULT_LOGGIE_AGENT_ID,
+  DEFAULT_LOGGIE_BASE_URL_ENV,
+  DEFAULT_LOGGIE_HEARTBEAT_TIMEOUT_MS,
+  DEFAULT_LOGGIE_SOCKET_PATH,
+  DEFAULT_LOGGIE_TOKEN_ENV,
+} from "./config-schema.js";
+import { isRecord, readBoolean, readInteger, readString } from "./object.js";
+
+export type LoggieAuthHeader = "authorization" | "x-api-key";
+
+export type LoggieSecretStatus =
+  | { status: "available"; source: string; value: string }
+  | { status: "configured_unavailable"; source: string; value?: undefined }
+  | { status: "missing"; source: "missing"; value?: undefined };
+
+export type ResolvedLoggieAccount = {
+  accountId: string;
+  name?: string;
+  enabled: boolean;
+  configured: boolean;
+  baseUrl: string;
+  socketPath: string;
+  agentId: string;
+  agentProfileId: string;
+  authHeader: LoggieAuthHeader;
+  tokenStatus: LoggieSecretStatus;
+  reconnect: {
+    minMs: number;
+    maxMs: number;
+  };
+  heartbeat: {
+    timeoutMs: number;
+  };
+  transcript: {
+    activation: "final-only";
+    debounceMs: number;
+  };
+};
+
+type RawLoggieAccountConfig = Record<string, unknown>;
+
+function getLoggieSection(cfg: OpenClawConfig): Record<string, unknown> {
+  const channels = isRecord((cfg as Record<string, unknown>).channels)
+    ? ((cfg as Record<string, unknown>).channels as Record<string, unknown>)
+    : {};
+  return isRecord(channels.loggie) ? channels.loggie : {};
+}
+
+function getAccounts(section: Record<string, unknown>): Record<string, RawLoggieAccountConfig> {
+  if (!isRecord(section.accounts)) {
+    return {};
+  }
+  const entries: Record<string, RawLoggieAccountConfig> = {};
+  for (const [id, raw] of Object.entries(section.accounts)) {
+    if (isRecord(raw)) {
+      entries[id] = raw;
+    }
+  }
+  return entries;
+}
+
+function mergeAccountConfig(
+  section: Record<string, unknown>,
+  accountId: string,
+): RawLoggieAccountConfig {
+  const { accounts: _accounts, ...topLevel } = section;
+  return {
+    ...topLevel,
+    ...(getAccounts(section)[accountId] ?? {}),
+  };
+}
+
+function normalizeAuthHeader(value: unknown): LoggieAuthHeader {
+  return value === "x-api-key" ? "x-api-key" : "authorization";
+}
+
+function readEnvSecretRefName(value: unknown): string | undefined {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (trimmed.length === 0) {
+      return undefined;
+    }
+    const envName = trimmed.startsWith("$")
+      ? trimmed.replace(/^\$\{?([^}]+)\}?$/, "$1")
+      : undefined;
+    return envName && /^[A-Z][A-Z0-9_]{0,127}$/.test(envName) ? envName : undefined;
+  }
+  if (
+    isRecord(value) &&
+    value.source === "env" &&
+    typeof value.id === "string" &&
+    value.id.trim().length > 0
+  ) {
+    return value.id.trim();
+  }
+  return undefined;
+}
+
+function readSecretRefLabel(value: unknown): string | undefined {
+  if (
+    isRecord(value) &&
+    typeof value.source === "string" &&
+    typeof value.provider === "string" &&
+    typeof value.id === "string"
+  ) {
+    return `${value.source}:${value.provider}:${value.id}`;
+  }
+  return undefined;
+}
+
+function resolveToken(params: {
+  raw: RawLoggieAccountConfig;
+  env: NodeJS.ProcessEnv;
+}): LoggieSecretStatus {
+  const literalToken = readString(params.raw.token);
+  if (literalToken) {
+    return { status: "available", source: "literal", value: literalToken };
+  }
+
+  if (params.raw.credentialRef === undefined) {
+    const value = readString(params.env[DEFAULT_LOGGIE_TOKEN_ENV]);
+    return value
+      ? { status: "available", source: `env:${DEFAULT_LOGGIE_TOKEN_ENV}`, value }
+      : { status: "configured_unavailable", source: `env:${DEFAULT_LOGGIE_TOKEN_ENV}` };
+  }
+
+  const credentialRef = params.raw.credentialRef;
+  const envName = readEnvSecretRefName(credentialRef);
+  if (envName) {
+    const value = readString(params.env[envName]);
+    return value
+      ? { status: "available", source: `env:${envName}`, value }
+      : { status: "configured_unavailable", source: `env:${envName}` };
+  }
+
+  if (typeof credentialRef === "string") {
+    const resolvedSecretValue = readString(credentialRef);
+    return resolvedSecretValue
+      ? { status: "available", source: "credentialRef", value: resolvedSecretValue }
+      : { status: "missing", source: "missing" };
+  }
+
+  const secretRefLabel = readSecretRefLabel(credentialRef);
+  if (!secretRefLabel) {
+    return { status: "missing", source: "missing" };
+  }
+  return { status: "configured_unavailable", source: secretRefLabel };
+}
+
+function normalizeReconnect(raw: RawLoggieAccountConfig) {
+  const reconnect = isRecord(raw.reconnect) ? raw.reconnect : {};
+  const minMs = Math.max(100, readInteger(reconnect.minMs, 1000));
+  const maxMs = Math.max(minMs, readInteger(reconnect.maxMs, 60_000));
+  return { minMs, maxMs };
+}
+
+function normalizeHeartbeat(raw: RawLoggieAccountConfig) {
+  const heartbeat = isRecord(raw.heartbeat) ? raw.heartbeat : {};
+  return {
+    timeoutMs: Math.max(
+      1000,
+      readInteger(heartbeat.timeoutMs, DEFAULT_LOGGIE_HEARTBEAT_TIMEOUT_MS),
+    ),
+  };
+}
+
+function normalizeTranscript(raw: RawLoggieAccountConfig) {
+  const transcript = isRecord(raw.transcript) ? raw.transcript : {};
+  return {
+    activation: "final-only" as const,
+    debounceMs: Math.max(0, readInteger(transcript.debounceMs, 5000)),
+  };
+}
+
+export function listLoggieAccountIds(cfg: OpenClawConfig): string[] {
+  const section = getLoggieSection(cfg);
+  const accounts = Object.keys(getAccounts(section));
+  if (accounts.length > 0) {
+    return accounts;
+  }
+  return [readString(section.accountId) ?? DEFAULT_LOGGIE_ACCOUNT_ID];
+}
+
+export function resolveDefaultLoggieAccountId(cfg: OpenClawConfig): string {
+  const section = getLoggieSection(cfg);
+  return readString(section.accountId) ?? DEFAULT_LOGGIE_ACCOUNT_ID;
+}
+
+export function resolveLoggieAccount(
+  cfg: OpenClawConfig,
+  accountId?: string | null,
+  env: NodeJS.ProcessEnv = process.env,
+): ResolvedLoggieAccount {
+  const section = getLoggieSection(cfg);
+  const resolvedAccountId = accountId?.trim() || resolveDefaultLoggieAccountId(cfg);
+  const raw = mergeAccountConfig(section, resolvedAccountId);
+  const baseUrl =
+    readString(raw.baseUrl) ?? readString(env[DEFAULT_LOGGIE_BASE_URL_ENV]) ?? "http://127.0.0.1:8787";
+  const agentProfileId = readString(raw.agentProfileId) ?? "";
+  const tokenStatus = resolveToken({ raw, env });
+  const enabled = readBoolean(raw.enabled, true);
+  const configured = Boolean(baseUrl && agentProfileId && tokenStatus.status === "available");
+
+  return {
+    accountId: resolvedAccountId,
+    name: readString(raw.name),
+    enabled,
+    configured,
+    baseUrl,
+    socketPath: readString(raw.socketPath) ?? DEFAULT_LOGGIE_SOCKET_PATH,
+    agentId: readString(raw.agentId) ?? DEFAULT_LOGGIE_AGENT_ID,
+    agentProfileId,
+    authHeader: normalizeAuthHeader(raw.authHeader),
+    tokenStatus,
+    reconnect: normalizeReconnect(raw),
+    heartbeat: normalizeHeartbeat(raw),
+    transcript: normalizeTranscript(raw),
+  };
+}
+
+export function inspectLoggieAccount(cfg: OpenClawConfig, accountId?: string | null) {
+  const account = resolveLoggieAccount(cfg, accountId);
+  return {
+    accountId: account.accountId,
+    name: account.name,
+    enabled: account.enabled,
+    configured: account.configured,
+    baseUrl: account.baseUrl,
+    socketPath: account.socketPath,
+    agentId: account.agentId,
+    agentProfileId: account.agentProfileId,
+    authHeader: account.authHeader,
+    tokenStatus: account.tokenStatus.status,
+    tokenSource: account.tokenStatus.source,
+    reconnect: account.reconnect,
+    heartbeat: account.heartbeat,
+    transcript: account.transcript,
+  };
+}
+
+export function applyLoggieAccountConfig(params: {
+  cfg: OpenClawConfig;
+  accountId: string;
+  input: Record<string, unknown>;
+}): OpenClawConfig {
+  const next = structuredClone(params.cfg) as Record<string, unknown>;
+  const channels = isRecord(next.channels) ? next.channels : {};
+  const loggie = isRecord(channels.loggie) ? channels.loggie : {};
+  channels.loggie = {
+    ...loggie,
+    accountId: params.accountId,
+    accounts: {
+      ...(isRecord(loggie.accounts) ? loggie.accounts : {}),
+      [params.accountId]: {
+        enabled: true,
+        ...params.input,
+      },
+    },
+  };
+  next.channels = channels;
+  return next as OpenClawConfig;
+}

package/src/channel.ts

@@ -0,0 +1,148 @@
+import {
+  createChannelPluginBase,
+  type ChannelPlugin,
+  type OpenClawConfig,
+} from "openclaw/plugin-sdk/channel-core";
+import {
+  applyLoggieAccountConfig,
+  inspectLoggieAccount,
+  listLoggieAccountIds,
+  resolveDefaultLoggieAccountId,
+  resolveLoggieAccount,
+  type ResolvedLoggieAccount,
+} from "./account.js";
+import { loggieChannelConfigSchema } from "./config-schema.js";
+import { loggieDoctor } from "./doctor.js";
+import {
+  buildLoggieAccountStatusSnapshot,
+  defaultLoggieRuntimeState,
+} from "./status.js";
+
+const base = createChannelPluginBase<ResolvedLoggieAccount>({
+  id: "loggie",
+  meta: {
+    label: "Loggie",
+    selectionLabel: "Loggie",
+    blurb: "Receives durable Loggie meeting transcript events over WebSocket.",
+    docsPath: "/plugins/loggie",
+  },
+  capabilities: {
+    chatTypes: ["group"],
+    threads: false,
+    media: false,
+    reply: false,
+  },
+  configSchema: loggieChannelConfigSchema,
+  setup: {
+    resolveAccountId: ({ accountId }: { accountId?: string }) => accountId ?? "default",
+    applyAccountConfig: ({
+      cfg,
+      accountId,
+      input,
+    }: {
+      cfg: OpenClawConfig;
+      accountId: string;
+      input: unknown;
+    }) =>
+      applyLoggieAccountConfig({
+        cfg,
+        accountId,
+        input: input as Record<string, unknown>,
+      }),
+  },
+  config: {
+    listAccountIds: listLoggieAccountIds,
+    resolveAccount: (cfg: OpenClawConfig, accountId?: string | null) =>
+      resolveLoggieAccount(cfg, accountId),
+    inspectAccount: inspectLoggieAccount,
+    defaultAccountId: resolveDefaultLoggieAccountId,
+    isEnabled: (account: ResolvedLoggieAccount) => account.enabled,
+    isConfigured: (account: ResolvedLoggieAccount) => account.configured,
+    unconfiguredReason: (account: ResolvedLoggieAccount) =>
+      account.tokenStatus.status !== "available"
+        ? `Loggie token ${account.tokenStatus.status}`
+        : "Loggie baseUrl and agentProfileId are required",
+    describeAccount: (account: ResolvedLoggieAccount) => ({
+      accountId: account.accountId,
+      name: account.name,
+      enabled: account.enabled,
+      configured: account.configured,
+      tokenStatus: account.tokenStatus.status,
+      tokenSource: account.tokenStatus.source,
+      extra: {
+        baseUrl: account.baseUrl,
+        agentId: account.agentId,
+        agentProfileId: account.agentProfileId,
+      },
+    }),
+  },
+});
+
+export const loggiePlugin = {
+  ...base,
+  status: {
+    defaultRuntime: defaultLoggieRuntimeState,
+    buildAccountSnapshot: ({
+      account,
+      runtime,
+    }: {
+      account: ResolvedLoggieAccount;
+      runtime?: Record<string, unknown> | null;
+    }) =>
+      buildLoggieAccountStatusSnapshot({
+        account,
+        runtime: runtime as Record<string, unknown> | null | undefined,
+      }),
+  },
+  doctor: loggieDoctor,
+  secrets: {
+    secretTargetRegistryEntries: [
+      {
+        id: "channels.loggie.credentialRef",
+        targetType: "channels.loggie.credentialRef",
+        configFile: "openclaw.json",
+        pathPattern: "channels.loggie.credentialRef",
+        secretShape: "secret_input",
+        expectedResolvedValue: "string",
+        includeInPlan: true,
+        includeInConfigure: true,
+        includeInAudit: true,
+      },
+      {
+        id: "channels.loggie.accounts.*.credentialRef",
+        targetType: "channels.loggie.accounts.*.credentialRef",
+        configFile: "openclaw.json",
+        pathPattern: "channels.loggie.accounts.*.credentialRef",
+        secretShape: "secret_input",
+        expectedResolvedValue: "string",
+        includeInPlan: true,
+        includeInConfigure: true,
+        includeInAudit: true,
+      },
+    ],
+  },
+  gateway: {
+    startAccount: async (ctx: {
+      account: ResolvedLoggieAccount;
+      cfg: OpenClawConfig;
+      runtime: unknown;
+      channelRuntime?: unknown;
+      abortSignal?: AbortSignal;
+      setStatus: (next: unknown) => void;
+      getStatus: () => unknown;
+      log?: { info?: (message: string) => void; warn?: (message: string) => void };
+    }) => {
+      const { monitorLoggieAccount } = await import("./monitor/connection.js");
+      return monitorLoggieAccount({
+        account: ctx.account,
+        cfg: ctx.cfg,
+        runtime: ctx.runtime as Parameters<typeof monitorLoggieAccount>[0]["runtime"],
+        channelRuntime: ctx.channelRuntime as Parameters<typeof monitorLoggieAccount>[0]["channelRuntime"],
+        abortSignal: ctx.abortSignal,
+        setStatus: ctx.setStatus as (next: Record<string, unknown>) => void,
+        getStatus: ctx.getStatus as () => Record<string, unknown>,
+        log: ctx.log,
+      });
+    },
+  },
+} satisfies ChannelPlugin<ResolvedLoggieAccount>;

package/src/config-schema.ts

@@ -0,0 +1,57 @@
+export const LOGGIE_CHANNEL_ID = "loggie";
+export const DEFAULT_LOGGIE_ACCOUNT_ID = "default";
+export const DEFAULT_LOGGIE_AGENT_ID = "main";
+export const DEFAULT_LOGGIE_SOCKET_PATH = "/api/events/socket";
+export const DEFAULT_LOGGIE_TOKEN_ENV = "LOGGIE_AGENT_TOKEN";
+export const DEFAULT_LOGGIE_BASE_URL_ENV = "LOGGIE_BASE_URL";
+export const DEFAULT_LOGGIE_HEARTBEAT_TIMEOUT_MS = 120_000;
+
+export const loggieEntryConfigSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {},
+} as const;
+
+export const loggieChannelConfigSchema = {
+  type: "object",
+  additionalProperties: true,
+  properties: {
+    enabled: { type: "boolean", default: true },
+    baseUrl: { type: "string" },
+    socketPath: { type: "string", default: DEFAULT_LOGGIE_SOCKET_PATH },
+    accountId: { type: "string", default: DEFAULT_LOGGIE_ACCOUNT_ID },
+    agentId: { type: "string", default: DEFAULT_LOGGIE_AGENT_ID },
+    agentProfileId: { type: "string" },
+    credentialRef: {},
+    token: { type: "string" },
+    authHeader: { type: "string", enum: ["authorization", "x-api-key"], default: "authorization" },
+    accounts: { type: "object", additionalProperties: { type: "object" } },
+    reconnect: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        minMs: { type: "integer", minimum: 100, default: 1000 },
+        maxMs: { type: "integer", minimum: 1000, default: 60000 },
+      },
+    },
+    heartbeat: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        timeoutMs: {
+          type: "integer",
+          minimum: 1000,
+          default: DEFAULT_LOGGIE_HEARTBEAT_TIMEOUT_MS,
+        },
+      },
+    },
+    transcript: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        activation: { type: "string", enum: ["final-only"], default: "final-only" },
+        debounceMs: { type: "integer", minimum: 0, default: 5000 },
+      },
+    },
+  },
+} as const;

package/src/cursor-store.ts

@@ -0,0 +1,233 @@
+import type { LoggieEventEnvelope } from "./event-types.js";
+
+export type LoggieCursorRecord = {
+  accountId: string;
+  agentProfileId: string;
+  lastEventId?: string;
+  lastCursor?: string;
+  lastSequence?: number;
+  lastConnectedAt?: number;
+  lastCaughtUpAt?: number;
+  lastError?: string;
+  failedEvents?: LoggieFailedEvent[];
+  deadLetteredEvents?: LoggieDeadLetteredEvent[];
+  seenEventIds: string[];
+  updatedAt: string;
+};
+
+export type LoggieFailedEvent = {
+  eventId: string;
+  cursor?: string;
+  eventType: string;
+  attempts: number;
+  firstFailedAt: string;
+  lastFailedAt: string;
+  lastReason: string;
+};
+
+export type LoggieDeadLetteredEvent = {
+  eventId: string;
+  cursor?: string;
+  eventType: string;
+  attempts: number;
+  reason: string;
+  deadLetteredAt: string;
+};
+
+export type LoggieCursorDecision =
+  | { action: "process" }
+  | { action: "skip"; reason: "duplicate_event" | "cursor_regression" };
+
+export type LoggieCursorStore = {
+  load(accountId: string, agentProfileId: string): Promise<LoggieCursorRecord | undefined>;
+  save(record: LoggieCursorRecord): Promise<void>;
+};
+
+const MAX_SEEN_EVENT_IDS = 500;
+const MAX_FAILED_EVENTS = 50;
+const MAX_DEAD_LETTERED_EVENTS = 100;
+
+export function createEmptyCursorRecord(params: {
+  accountId: string;
+  agentProfileId: string;
+}): LoggieCursorRecord {
+  return {
+    accountId: params.accountId,
+    agentProfileId: params.agentProfileId,
+    seenEventIds: [],
+    updatedAt: new Date(0).toISOString(),
+  };
+}
+
+export function decideCursor(record: LoggieCursorRecord | undefined, event: LoggieEventEnvelope): LoggieCursorDecision {
+  if (record?.seenEventIds.includes(event.eventId)) {
+    return { action: "skip", reason: "duplicate_event" };
+  }
+  const eventCursor = parseCursor(event.cursor);
+  const recordCursor = parseCursor(readStoredCursor(record));
+  if (eventCursor !== undefined && recordCursor !== undefined && eventCursor < recordCursor) {
+    return { action: "skip", reason: "cursor_regression" };
+  }
+  return { action: "process" };
+}
+
+export function advanceCursor(params: {
+  record: LoggieCursorRecord | undefined;
+  event: LoggieEventEnvelope;
+  accountId: string;
+  agentProfileId: string;
+  now?: Date;
+}): LoggieCursorRecord {
+  const base =
+    params.record ??
+    createEmptyCursorRecord({
+      accountId: params.accountId,
+      agentProfileId: params.agentProfileId,
+    });
+  const seen = [params.event.eventId, ...base.seenEventIds.filter((id) => id !== params.event.eventId)].slice(
+    0,
+    MAX_SEEN_EVENT_IDS,
+  );
+  const failedEvents = base.failedEvents?.filter((entry) => entry.eventId !== params.event.eventId);
+  return {
+    ...base,
+    lastEventId: params.event.eventId,
+    lastCursor: params.event.cursor ?? base.lastCursor,
+    lastSequence:
+      typeof params.event.sequence === "number"
+        ? params.event.sequence
+        : base.lastSequence,
+    lastCaughtUpAt: (params.now ?? new Date()).getTime(),
+    lastError: undefined,
+    failedEvents: failedEvents?.length ? failedEvents : undefined,
+    seenEventIds: seen,
+    updatedAt: (params.now ?? new Date()).toISOString(),
+  };
+}
+
+export function recordEventFailure(params: {
+  record: LoggieCursorRecord | undefined;
+  event: LoggieEventEnvelope;
+  accountId: string;
+  agentProfileId: string;
+  reason: string;
+  now?: Date;
+}): { record: LoggieCursorRecord; attempts: number } {
+  const now = (params.now ?? new Date()).toISOString();
+  const base =
+    params.record ??
+    createEmptyCursorRecord({
+      accountId: params.accountId,
+      agentProfileId: params.agentProfileId,
+    });
+  const existing = base.failedEvents?.find((entry) => entry.eventId === params.event.eventId);
+  const nextFailure: LoggieFailedEvent = {
+    eventId: params.event.eventId,
+    cursor: params.event.cursor,
+    eventType: params.event.eventType,
+    attempts: (existing?.attempts ?? 0) + 1,
+    firstFailedAt: existing?.firstFailedAt ?? now,
+    lastFailedAt: now,
+    lastReason: params.reason,
+  };
+  const failedEvents = [
+    nextFailure,
+    ...(base.failedEvents ?? []).filter((entry) => entry.eventId !== params.event.eventId),
+  ].slice(0, MAX_FAILED_EVENTS);
+  return {
+    attempts: nextFailure.attempts,
+    record: {
+      ...base,
+      lastError: params.reason,
+      failedEvents,
+      updatedAt: now,
+    },
+  };
+}
+
+export function deadLetterEvent(params: {
+  record: LoggieCursorRecord | undefined;
+  event: LoggieEventEnvelope;
+  accountId: string;
+  agentProfileId: string;
+  reason: string;
+  attempts: number;
+  now?: Date;
+}): LoggieCursorRecord {
+  const now = params.now ?? new Date();
+  const advanced = advanceCursor({
+    record: params.record,
+    event: params.event,
+    accountId: params.accountId,
+    agentProfileId: params.agentProfileId,
+    now,
+  });
+  return {
+    ...advanced,
+    deadLetteredEvents: [
+      {
+        eventId: params.event.eventId,
+        cursor: params.event.cursor,
+        eventType: params.event.eventType,
+        attempts: params.attempts,
+        reason: params.reason,
+        deadLetteredAt: now.toISOString(),
+      },
+      ...(advanced.deadLetteredEvents ?? []),
+    ].slice(0, MAX_DEAD_LETTERED_EVENTS),
+  };
+}
+
+export function createMemoryCursorStore(initial?: LoggieCursorRecord[]): LoggieCursorStore {
+  const records = new Map<string, LoggieCursorRecord>();
+  for (const record of initial ?? []) {
+    records.set(cursorKey(record.accountId, record.agentProfileId), record);
+  }
+  return {
+    async load(accountId, agentProfileId) {
+      return records.get(cursorKey(accountId, agentProfileId));
+    },
+    async save(record) {
+      records.set(cursorKey(record.accountId, record.agentProfileId), record);
+    },
+  };
+}
+
+export function createRuntimeCursorStore(runtime: {
+  state?: {
+    openKeyedStore?: <T>(opts: { namespace: string; maxEntries: number }) => {
+      lookup(key: string): Promise<T | undefined>;
+      register(key: string, value: T): Promise<void>;
+    };
+  };
+}): LoggieCursorStore {
+  const store = runtime.state?.openKeyedStore?.<LoggieCursorRecord>({
+    namespace: "loggie-cursors",
+    maxEntries: 1000,
+  });
+  if (!store) {
+    throw new Error("Loggie durable cursor store is unavailable");
+  }
+  return {
+    load: (accountId, agentProfileId) => store.lookup(cursorKey(accountId, agentProfileId)),
+    save: (record) => store.register(cursorKey(record.accountId, record.agentProfileId), record),
+  };
+}
+
+function cursorKey(accountId: string, agentProfileId: string): string {
+  return `${accountId}:${agentProfileId}`;
+}
+
+function parseCursor(value: string | undefined): bigint | undefined {
+  if (!value || !/^\d+$/.test(value)) {
+    return undefined;
+  }
+  return BigInt(value);
+}
+
+function readStoredCursor(record: LoggieCursorRecord | undefined): string | undefined {
+  if (!record) {
+    return undefined;
+  }
+  return record.lastCursor ?? (typeof record.lastSequence === "number" ? String(record.lastSequence) : undefined);
+}