@loggie-ai/openclaw-plugin 0.1.0

package/README.md

@@ -0,0 +1,205 @@
+# Loggie OpenClaw Plugin
+
+OpenClaw channel plugin for Loggie meeting transcript events.
+
+The plugin opens an outbound authenticated WebSocket to Loggie, replays from the
+last durable cursor, and turns each `meeting.transcript.ready` event into one
+OpenClaw inbound channel turn for the configured agent.
+
+## How It Works
+
+1. OpenClaw loads the setup-safe entrypoint for discovery, config inspection,
+   status, doctor checks, and SecretRef target discovery.
+2. When the configured channel account starts, the full runtime entrypoint lazy
+   loads the WebSocket monitor.
+3. The monitor opens a WebSocket to `baseUrl + socketPath`, authenticating with
+   either `Authorization: Bearer <token>` or `x-api-key: <token>`.
+4. Before opening the socket, the plugin loads the durable cursor from OpenClaw
+   runtime state and appends it to the URL as `?cursor=<lastCursor>`.
+5. Loggie sends event envelopes. The plugin validates the envelope, skips
+   duplicates or cursor regressions, and processes `meeting.transcript.ready`.
+6. If the event includes `payload.detailPath`, the plugin fetches that detail
+   from the same Loggie origin with the same auth header. Cross-origin detail
+   URLs are rejected before auth headers are attached.
+7. The plugin builds a deterministic OpenClaw session key from the agent,
+   account, and meeting id, records the inbound route, and runs the configured
+   OpenClaw agent with the transcript prompt.
+8. The cursor advances only after dispatch succeeds, or after an unsupported
+   event is intentionally skipped.
+
+## Loggie Server Contract
+
+Minimum server-side behavior expected by this plugin:
+
+- Authenticated WebSocket endpoint at `/api/events/socket` by default.
+- WebSocket auth using the configured agent profile token.
+- Initial replay from the WebSocket URL query: `?cursor=<cursor>`.
+- Durable event ordering using `eventId` and monotonic string `cursor`.
+- Client messages `{ "type": "ping" }` and `{ "type": "resume", "cursor": "..." }`.
+- Replay pagination control messages:
+  `{ "type": "loggie.events.more_available", "cursor": "..." }`.
+- `meeting.transcript.ready` event envelopes.
+- Optional HTTP detail endpoint referenced by `payload.detailPath`.
+- Control messages with `type: "hello"`, `"ack"`, or `"pong"` are accepted and
+  treated as connection/control traffic.
+
+Example event:
+
+```json
+{
+  "cursor": "123",
+  "type": "meeting.transcript.ready",
+  "payload": {
+    "eventId": "evt_1",
+    "cursor": "123",
+    "type": "meeting.transcript.ready",
+    "workspaceId": "ws_1",
+    "meetingId": "mtg_1",
+    "meetingScheduleId": "sched_1",
+    "title": "Weekly Standup",
+    "source": "recall_ai",
+    "externalId": "tr_1",
+    "meetingDate": "2026-06-26T11:30:00.000Z",
+    "hasTranscript": true,
+    "detailPath": "/api/proxy/meetings/sched_1"
+  },
+  "createdAt": "2026-06-26T12:00:00.000Z"
+}
+```
+
+The plugin also accepts the older internal envelope shape and `{ "event": { ... } }`
+wrappers for compatibility, but the server socket shape above is the primary
+contract.
+
+## Configuration
+
+Configure the channel under `channels.loggie`.
+
+```json
+{
+  "channels": {
+    "loggie": {
+      "enabled": true,
+      "baseUrl": "https://loggie.example.com",
+      "agentProfileId": "ap_123",
+      "credentialRef": "$LOGGIE_AGENT_TOKEN",
+      "agentId": "main"
+    }
+  }
+}
+```
+
+Important fields:
+
+- `baseUrl`: Loggie HTTP origin. Defaults to `LOGGIE_BASE_URL`, then
+  `http://127.0.0.1:8787`.
+- `socketPath`: WebSocket path. Defaults to `/api/events/socket`.
+- `agentProfileId`: Loggie agent profile used for socket auth and OpenClaw
+  sender/account identity. Server events are workspace-scoped and do not need to
+  include this field.
+- `credentialRef`: Token input. Use `$ENV_VAR` for env-backed credentials or a
+  structured SecretRef. If OpenClaw materializes a SecretRef before runtime, the
+  resulting string is treated as token material.
+- `token`: Literal token fallback for local development.
+- `authHeader`: `authorization` by default, or `x-api-key`.
+- `agentId`: OpenClaw agent id that should receive transcript turns. Defaults to
+  `main`.
+- `reconnect.minMs` and `reconnect.maxMs`: exponential reconnect backoff bounds.
+- `heartbeat.timeoutMs`: stale socket timeout. Defaults to `120000`.
+
+Environment defaults:
+
+```bash
+export LOGGIE_BASE_URL="https://loggie.example.com"
+export LOGGIE_AGENT_TOKEN="..."
+```
+
+For multiple accounts, put account-specific settings under
+`channels.loggie.accounts`:
+
+```json
+{
+  "channels": {
+    "loggie": {
+      "accountId": "prod",
+      "accounts": {
+        "prod": {
+          "baseUrl": "https://loggie.example.com",
+          "agentProfileId": "ap_prod",
+          "credentialRef": "$LOGGIE_AGENT_TOKEN",
+          "agentId": "main"
+        }
+      }
+    }
+  }
+}
+```
+
+## Sessions And Cursoring
+
+Session identity is deterministic:
+
+- Route session key:
+  `agent:<agentId>:loggie:<accountId>:meeting:<meetingScheduleId|meetingId|eventId>`
+- Embedded run session id:
+  `loggie-<accountId>-<meetingScheduleId|meetingId|eventId>`
+
+The cursor store is required to be durable. Runtime startup fails if OpenClaw
+does not provide a keyed runtime state store. This prevents silent in-memory
+cursor loss and duplicate transcript dispatch after restart.
+
+The plugin keeps a bounded set of recently seen event ids and skips:
+
+- duplicate `eventId`
+- lower numeric `cursor` values than the stored cursor
+
+If transcript dispatch fails for the same event, the plugin records the failure
+in the durable cursor state and retries it on replay. After 3 failed dispatch
+attempts, the event is recorded in `deadLetteredEvents`, the cursor advances,
+and later events can continue processing. The latest dead-letter is also
+reported in channel status as `lastDeadLetterAt`, `lastDeadLetteredEventId`,
+`lastDeadLetteredCursor`, `lastDeadLetterReason`, and
+`lastDeadLetterAttempts`, and the monitor emits a warning log.
+
+## Reconnect And Heartbeat Behavior
+
+Unexpected socket errors or closes reconnect with exponential backoff. The
+next socket URL includes the last persisted cursor so Loggie can replay missed
+events. If Loggie reports `loggie.events.more_available`, the plugin sends
+`{ "type": "resume", "cursor": "..." }` to request the next replay page.
+
+The plugin sends periodic `{ "type": "ping" }` messages. The heartbeat timeout is
+based on any received socket message, including `pong` and other control
+messages. When the heartbeat expires, the plugin closes the socket and waits for
+in-flight event handling to finish before reconnecting. That avoids dispatching
+the same transcript twice while an earlier turn is still advancing the cursor.
+
+## Security Notes
+
+- Tokens are used only for outbound Loggie auth headers.
+- Status and inspect output report token availability/source, not token values.
+- Detail fetches are restricted to the configured Loggie origin.
+- `credentialRef` should be `$ENV_VAR` or a structured SecretRef for config.
+  Plain strings are treated as materialized token values.
+
+## Development
+
+```bash
+npm install
+npm run check
+npm test
+npm run build
+npm run preflight
+```
+
+Useful targeted commands:
+
+```bash
+npm run plugin:inspect
+npm run plugin:inspect:runtime
+npx tsc -p tsconfig.json --noEmit --noUnusedLocals --noUnusedParameters
+npm pack --dry-run
+```
+
+`npm run preflight` runs typecheck, tests, build, and both plugin-inspector
+passes.

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+declare const _default: {
+    id: string;
+    name: string;
+    description: string;
+    channelPlugin: unknown;
+    register(api: Record<string, unknown>): void;
+};
+export default _default;

package/dist/index.js

@@ -0,0 +1,12 @@
+import { defineChannelPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { loggiePlugin } from "./src/channel.js";
+import { loggieEntryConfigSchema } from "./src/config-schema.js";
+import { setLoggieRuntime } from "./src/runtime.js";
+export default defineChannelPluginEntry({
+    id: "loggie",
+    name: "Loggie",
+    description: "Receives durable Loggie meeting transcript events over WebSocket.",
+    plugin: loggiePlugin,
+    configSchema: loggieEntryConfigSchema,
+    setRuntime: setLoggieRuntime,
+});

package/dist/setup-entry.d.ts

@@ -0,0 +1,73 @@
+declare const _default: {
+    plugin: {
+        status: {
+            defaultRuntime: {
+                accountId: string;
+                running: false;
+                lastStartAt: null;
+                lastStopAt: null;
+                lastError: null;
+            } & import("./src/status.js").LoggieRuntimeExtra;
+            buildAccountSnapshot: ({ account, runtime, }: {
+                account: import("./src/account.js").ResolvedLoggieAccount;
+                runtime?: Record<string, unknown> | null;
+            }) => Record<string, unknown> & {
+                mode: string;
+                baseUrl: string;
+                agentId: string;
+                agentProfileId: string;
+                tokenStatus: "available" | "configured_unavailable" | "missing";
+                tokenSource: string;
+                connected: {};
+                authenticated: {};
+                caughtUp: {};
+                lastEventId: {} | null;
+                lastCursor: {} | null;
+                lastSequence: {} | null;
+                lastDispatchAt: {} | null;
+                lastDeadLetterAt: {} | null;
+                lastDeadLetteredEventId: {} | null;
+                lastDeadLetteredCursor: {} | null;
+                lastDeadLetterReason: {} | null;
+                lastDeadLetterAttempts: {} | null;
+            };
+        };
+        doctor: {
+            collectPreviewWarnings: (params: {
+                cfg: import("openclaw/plugin-sdk/channel-core").OpenClawConfig;
+                env?: NodeJS.ProcessEnv;
+            }) => string[];
+        };
+        secrets: {
+            secretTargetRegistryEntries: {
+                id: string;
+                targetType: string;
+                configFile: string;
+                pathPattern: string;
+                secretShape: string;
+                expectedResolvedValue: string;
+                includeInPlan: boolean;
+                includeInConfigure: boolean;
+                includeInAudit: boolean;
+            }[];
+        };
+        gateway: {
+            startAccount: (ctx: {
+                account: import("./src/account.js").ResolvedLoggieAccount;
+                cfg: import("openclaw/plugin-sdk/channel-core").OpenClawConfig;
+                runtime: unknown;
+                channelRuntime?: unknown;
+                abortSignal?: AbortSignal;
+                setStatus: (next: unknown) => void;
+                getStatus: () => unknown;
+                log?: {
+                    info?: (message: string) => void;
+                    warn?: (message: string) => void;
+                };
+            }) => Promise<void>;
+        };
+        id: string;
+        config?: Record<string, unknown>;
+    };
+};
+export default _default;

package/dist/setup-entry.js

@@ -0,0 +1,3 @@
+import { defineSetupPluginEntry } from "openclaw/plugin-sdk/channel-core";
+import { loggiePlugin } from "./src/channel.js";
+export default defineSetupPluginEntry(loggiePlugin);

package/dist/src/account.d.ts

@@ -0,0 +1,70 @@
+import type { OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
+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;
+    };
+};
+export declare function listLoggieAccountIds(cfg: OpenClawConfig): string[];
+export declare function resolveDefaultLoggieAccountId(cfg: OpenClawConfig): string;
+export declare function resolveLoggieAccount(cfg: OpenClawConfig, accountId?: string | null, env?: NodeJS.ProcessEnv): ResolvedLoggieAccount;
+export declare function inspectLoggieAccount(cfg: OpenClawConfig, accountId?: string | null): {
+    accountId: string;
+    name: string | undefined;
+    enabled: boolean;
+    configured: boolean;
+    baseUrl: string;
+    socketPath: string;
+    agentId: string;
+    agentProfileId: string;
+    authHeader: LoggieAuthHeader;
+    tokenStatus: "available" | "configured_unavailable" | "missing";
+    tokenSource: string;
+    reconnect: {
+        minMs: number;
+        maxMs: number;
+    };
+    heartbeat: {
+        timeoutMs: number;
+    };
+    transcript: {
+        activation: "final-only";
+        debounceMs: number;
+    };
+};
+export declare function applyLoggieAccountConfig(params: {
+    cfg: OpenClawConfig;
+    accountId: string;
+    input: Record<string, unknown>;
+}): OpenClawConfig;

package/dist/src/account.js

@@ -0,0 +1,182 @@
+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";
+function getLoggieSection(cfg) {
+    const channels = isRecord(cfg.channels)
+        ? cfg.channels
+        : {};
+    return isRecord(channels.loggie) ? channels.loggie : {};
+}
+function getAccounts(section) {
+    if (!isRecord(section.accounts)) {
+        return {};
+    }
+    const entries = {};
+    for (const [id, raw] of Object.entries(section.accounts)) {
+        if (isRecord(raw)) {
+            entries[id] = raw;
+        }
+    }
+    return entries;
+}
+function mergeAccountConfig(section, accountId) {
+    const { accounts: _accounts, ...topLevel } = section;
+    return {
+        ...topLevel,
+        ...(getAccounts(section)[accountId] ?? {}),
+    };
+}
+function normalizeAuthHeader(value) {
+    return value === "x-api-key" ? "x-api-key" : "authorization";
+}
+function readEnvSecretRefName(value) {
+    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) {
+    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) {
+    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) {
+    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) {
+    const heartbeat = isRecord(raw.heartbeat) ? raw.heartbeat : {};
+    return {
+        timeoutMs: Math.max(1000, readInteger(heartbeat.timeoutMs, DEFAULT_LOGGIE_HEARTBEAT_TIMEOUT_MS)),
+    };
+}
+function normalizeTranscript(raw) {
+    const transcript = isRecord(raw.transcript) ? raw.transcript : {};
+    return {
+        activation: "final-only",
+        debounceMs: Math.max(0, readInteger(transcript.debounceMs, 5000)),
+    };
+}
+export function listLoggieAccountIds(cfg) {
+    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) {
+    const section = getLoggieSection(cfg);
+    return readString(section.accountId) ?? DEFAULT_LOGGIE_ACCOUNT_ID;
+}
+export function resolveLoggieAccount(cfg, accountId, env = process.env) {
+    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, accountId) {
+    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) {
+    const next = structuredClone(params.cfg);
+    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;
+}

package/dist/src/channel.d.ts

@@ -0,0 +1,72 @@
+import { type OpenClawConfig } from "openclaw/plugin-sdk/channel-core";
+import { type ResolvedLoggieAccount } from "./account.js";
+export declare const loggiePlugin: {
+    status: {
+        defaultRuntime: {
+            accountId: string;
+            running: false;
+            lastStartAt: null;
+            lastStopAt: null;
+            lastError: null;
+        } & import("./status.js").LoggieRuntimeExtra;
+        buildAccountSnapshot: ({ account, runtime, }: {
+            account: ResolvedLoggieAccount;
+            runtime?: Record<string, unknown> | null;
+        }) => Record<string, unknown> & {
+            mode: string;
+            baseUrl: string;
+            agentId: string;
+            agentProfileId: string;
+            tokenStatus: "available" | "configured_unavailable" | "missing";
+            tokenSource: string;
+            connected: {};
+            authenticated: {};
+            caughtUp: {};
+            lastEventId: {} | null;
+            lastCursor: {} | null;
+            lastSequence: {} | null;
+            lastDispatchAt: {} | null;
+            lastDeadLetterAt: {} | null;
+            lastDeadLetteredEventId: {} | null;
+            lastDeadLetteredCursor: {} | null;
+            lastDeadLetterReason: {} | null;
+            lastDeadLetterAttempts: {} | null;
+        };
+    };
+    doctor: {
+        collectPreviewWarnings: (params: {
+            cfg: OpenClawConfig;
+            env?: NodeJS.ProcessEnv;
+        }) => string[];
+    };
+    secrets: {
+        secretTargetRegistryEntries: {
+            id: string;
+            targetType: string;
+            configFile: string;
+            pathPattern: string;
+            secretShape: string;
+            expectedResolvedValue: string;
+            includeInPlan: boolean;
+            includeInConfigure: boolean;
+            includeInAudit: boolean;
+        }[];
+    };
+    gateway: {
+        startAccount: (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;
+            };
+        }) => Promise<void>;
+    };
+    id: string;
+    config?: Record<string, unknown>;
+};