@xmoxmo/bncr 0.3.5 → 0.3.7

package/src/plugin/diagnostics-handlers.ts

@@ -0,0 +1,211 @@
+import type { GatewayRequestHandlerOptions } from 'openclaw/plugin-sdk/core';
+import { BNCR_DEFAULT_ACCOUNT_ID, normalizeAccountId } from '../core/accounts.ts';
+import {
+  parseDeadLetterLimit,
+  parseDeadLetterOffset,
+  parseDeadLetterOlderThan,
+  summarizeDeadLetterEntry,
+} from '../core/dead-letter-diagnostics.ts';
+import { buildDiagnosticsPayload } from '../core/diagnostics.ts';
+import type { BncrExtendedDiagnostics } from '../core/extended-diagnostics.ts';
+import type {
+  BncrAccountRuntimeSnapshot,
+  buildIntegratedDiagnostics as buildIntegratedDiagnosticsFromRuntime,
+} from '../core/status.ts';
+import type {
+  BncrDeadLetterDiagnosticsSummary,
+  BncrDownlinkHealthSummary,
+  OutboxEntry,
+} from '../core/types.ts';
+import { getOpenClawRuntimeConfig } from '../openclaw/config-runtime.ts';
+import type { BncrRuntimeFlags } from '../runtime/outbound-flags.ts';
+
+type RuntimeStatusInput = Parameters<typeof buildIntegratedDiagnosticsFromRuntime>[0];
+type IntegratedDiagnostics = ReturnType<typeof buildIntegratedDiagnosticsFromRuntime>;
+type DiagnosticsRuntimeStatusOverrides = {
+  running: boolean;
+  invalidOutboxSessionKeys?: number;
+  legacyAccountResidue?: number;
+};
+type DiagnosticsRuntimeStatusInput = RuntimeStatusInput & {
+  running: boolean | undefined;
+  channelRoot: string;
+};
+
+type RuntimeApiHolder = {
+  runtime?: {
+    config?: unknown;
+    [key: string]: unknown;
+  };
+  [key: string]: unknown;
+};
+
+export type BncrDiagnosticsHandlerRuntime = {
+  getApi: () => RuntimeApiHolder;
+  channelId: string;
+  asString: (value: unknown, fallback?: string) => string;
+  now: () => number;
+  countInvalidOutboxSessionKeys: (accountId: string) => number;
+  countLegacyAccountResidue: (accountId: string) => number;
+  buildRuntimeStatusInput: (
+    accountId: string,
+    overrides: DiagnosticsRuntimeStatusOverrides,
+  ) => DiagnosticsRuntimeStatusInput;
+  getAccountRuntimeSnapshot: (
+    accountId: string,
+    runtimeStatusInput: DiagnosticsRuntimeStatusInput,
+  ) => BncrAccountRuntimeSnapshot;
+  buildIntegratedDiagnostics: (
+    accountId: string,
+    runtimeStatusInput: DiagnosticsRuntimeStatusInput,
+  ) => IntegratedDiagnostics;
+  buildExtendedDiagnostics: (
+    accountId: string,
+    args: {
+      runtimeStatusInput: DiagnosticsRuntimeStatusInput;
+      integratedDiagnostics: IntegratedDiagnostics;
+    },
+  ) => BncrExtendedDiagnostics;
+  buildDownlinkHealth: (accountId: string) => BncrDownlinkHealthSummary;
+  buildRuntimeFlags: (accountId: string) => BncrRuntimeFlags;
+  activeConnectionCount: (accountId: string) => number;
+  getMessageAckWaiterCount: () => number;
+  getFileAckWaiterCount: () => number;
+  filterDeadLetterEntries: (args: {
+    accountId: string;
+    reason: string | null;
+    olderThan: number | null;
+  }) => OutboxEntry[];
+  listDeadLetterEntries: () => OutboxEntry[];
+  buildDeadLetterDiagnostics: (accountId: string) => BncrDeadLetterDiagnosticsSummary;
+  replaceDeadLetterEntries: (nextEntries: OutboxEntry[]) => void;
+  scheduleSave: () => void;
+  logDeadLetterSummary: (accountId: string, args: { force: boolean; source: string }) => void;
+};
+
+export function createBncrDiagnosticsHandlers(runtime: BncrDiagnosticsHandlerRuntime) {
+  return {
+    handleDiagnostics: async ({ params, respond }: GatewayRequestHandlerOptions) => {
+      const accountId = normalizeAccountId(runtime.asString(params?.accountId || ''));
+      const cfg = getOpenClawRuntimeConfig(runtime.getApi());
+      const invalidOutboxSessionKeys = runtime.countInvalidOutboxSessionKeys(accountId);
+      const legacyAccountResidue = runtime.countLegacyAccountResidue(accountId);
+      const runtimeStatusInput = runtime.buildRuntimeStatusInput(accountId, {
+        running: true,
+        invalidOutboxSessionKeys,
+        legacyAccountResidue,
+      });
+      const runtimeSnapshot = runtime.getAccountRuntimeSnapshot(accountId, runtimeStatusInput);
+      const integratedDiagnostics = runtime.buildIntegratedDiagnostics(
+        accountId,
+        runtimeStatusInput,
+      );
+      const diagnostics = runtime.buildExtendedDiagnostics(accountId, {
+        runtimeStatusInput,
+        integratedDiagnostics,
+      });
+
+      respond(
+        true,
+        buildDiagnosticsPayload({
+          cfg,
+          channelId: runtime.channelId,
+          accountId,
+          runtime: runtimeSnapshot,
+          diagnostics,
+          downlinkHealth: runtime.buildDownlinkHealth(accountId),
+          runtimeFlags: runtime.buildRuntimeFlags(accountId),
+          waiters: {
+            messageAck: runtime.getMessageAckWaiterCount(),
+            fileAck: runtime.getFileAckWaiterCount(),
+          },
+          activeConnections: runtime.activeConnectionCount(accountId),
+          invalidOutboxSessionKeys,
+          legacyAccountResidue,
+          now: runtime.now(),
+        }),
+      );
+    },
+
+    handleDeadLetterInspect: async ({ params, respond }: GatewayRequestHandlerOptions) => {
+      const accountId = normalizeAccountId(
+        runtime.asString(params?.accountId || BNCR_DEFAULT_ACCOUNT_ID),
+      );
+      const reason = runtime.asString(params?.reason || '').trim() || null;
+      const olderThan = parseDeadLetterOlderThan(params?.olderThan);
+      const limit = parseDeadLetterLimit(params?.limit, 20);
+      const offset = parseDeadLetterOffset(params?.offset, 0);
+      const matches = runtime
+        .filterDeadLetterEntries({ accountId, reason, olderThan })
+        .slice()
+        .sort((a, b) => Number(b.createdAt || 0) - Number(a.createdAt || 0));
+
+      respond(true, {
+        ok: true,
+        accountId,
+        filters: { reason, olderThan },
+        total: matches.length,
+        offset,
+        limit,
+        entries: matches
+          .slice(offset, offset + limit)
+          .map((entry) => summarizeDeadLetterEntry(entry)),
+        summary: runtime.buildDeadLetterDiagnostics(accountId),
+        now: runtime.now(),
+      });
+    },
+
+    handleDeadLetterPrune: async ({ params, respond }: GatewayRequestHandlerOptions) => {
+      const accountId = normalizeAccountId(
+        runtime.asString(params?.accountId || BNCR_DEFAULT_ACCOUNT_ID),
+      );
+      const reason = runtime.asString(params?.reason || '').trim() || null;
+      const olderThan = parseDeadLetterOlderThan(params?.olderThan);
+      const limit = parseDeadLetterLimit(params?.limit, 100);
+      const dryRun = params?.dryRun !== false;
+      const hasDestructiveFilter = Boolean(reason || olderThan !== null);
+      if (!dryRun && !hasDestructiveFilter) {
+        respond(false, {
+          ok: false,
+          error: 'deadLetter-prune-requires-filter',
+          message: 'dryRun=false requires at least one destructive filter: reason or olderThan',
+          dryRun,
+          accountId,
+          filters: { reason, olderThan },
+          summary: runtime.buildDeadLetterDiagnostics(accountId),
+          now: runtime.now(),
+        });
+        return;
+      }
+      const matches = runtime
+        .filterDeadLetterEntries({ accountId, reason, olderThan })
+        .slice()
+        .sort((a, b) => Number(a.createdAt || 0) - Number(b.createdAt || 0));
+      const selected = matches.slice(0, limit);
+      const selectedEntries = new Set(selected);
+
+      if (!dryRun && selectedEntries.size > 0) {
+        const nextEntries = runtime
+          .listDeadLetterEntries()
+          .filter((entry) => !selectedEntries.has(entry));
+        runtime.replaceDeadLetterEntries(nextEntries);
+        runtime.scheduleSave();
+        runtime.logDeadLetterSummary(accountId, { force: true, source: 'prune' });
+      }
+
+      respond(true, {
+        ok: true,
+        dryRun,
+        accountId,
+        filters: { reason, olderThan },
+        matched: matches.length,
+        pruned: dryRun ? 0 : selected.length,
+        wouldPrune: selected.length,
+        limit,
+        entries: selected.map((entry) => summarizeDeadLetterEntry(entry)),
+        summary: runtime.buildDeadLetterDiagnostics(accountId),
+        now: runtime.now(),
+      });
+    },
+  };
+}

package/src/plugin/error-message.ts

@@ -0,0 +1,15 @@
+export function getErrorMessage(error: unknown, fallback: string): string {
+  if (typeof error === 'object' && error && 'message' in error) {
+    const message = (error as { message?: unknown }).message;
+    if (typeof message === 'string' && message.trim()) return message;
+  }
+
+  if (typeof error === 'string' && error.trim()) return error;
+
+  if (error != null) {
+    const rendered = String(error).trim();
+    if (rendered) return rendered;
+  }
+
+  return fallback;
+}

package/src/plugin/file-ack-runtime.ts

@@ -0,0 +1,284 @@
+import { buildFileAckKey } from '../core/file-ack.ts';
+import { OUTBOUND_TERMINAL_REASON } from '../messaging/outbound/reasons.ts';
+
+export type FileAckPayloadState = {
+  payload: Record<string, unknown>;
+  ok: boolean;
+  at: number;
+};
+
+export type FileAckWaiter = {
+  promise: Promise<Record<string, unknown>>;
+  resolve: (payload: Record<string, unknown>) => void;
+  reject: (err: Error) => void;
+  timer: NodeJS.Timeout;
+};
+
+export function createBncrFileAckRuntime(runtime: {
+  bridgeId: string;
+  now: () => number;
+  asString: (value: unknown, fallback?: string) => string;
+  clampFiniteNumber: (value: unknown, fallback: number, min?: number, max?: number) => number;
+  fileAckTimeoutMs: number;
+  maxEarlyFileAcks: number;
+  fileAckWaiters: Map<string, FileAckWaiter>;
+  earlyFileAcks: Map<string, FileAckPayloadState>;
+  getFileAckOwnerInfo: (transferId: string) => Record<string, unknown>;
+  logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  logWarn: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+}) {
+  function rememberEarlyFileAck(key: string, state: FileAckPayloadState) {
+    runtime.earlyFileAcks.set(key, state);
+    while (runtime.earlyFileAcks.size > runtime.maxEarlyFileAcks) {
+      const oldestKey = runtime.earlyFileAcks.keys().next().value;
+      if (!oldestKey) break;
+      runtime.earlyFileAcks.delete(oldestKey);
+    }
+  }
+
+  function fileAckKey(transferId: string, stage: string, chunkIndex?: number): string {
+    return buildFileAckKey({ transferId, stage, chunkIndex });
+  }
+
+  function buildFileAckWaitContext(params: {
+    transferId: string;
+    stage: string;
+    chunkIndex?: number;
+    timeoutMs?: number;
+  }) {
+    const transferId = runtime.asString(params.transferId).trim();
+    const stage = runtime.asString(params.stage).trim();
+    const chunkIndex = Number.isFinite(Number(params.chunkIndex))
+      ? Number(params.chunkIndex)
+      : undefined;
+    return {
+      transferId,
+      stage,
+      chunkIndex,
+      key: fileAckKey(transferId, stage, params.chunkIndex),
+      timeoutMs: runtime.clampFiniteNumber(
+        params.timeoutMs,
+        runtime.fileAckTimeoutMs,
+        1_000,
+        120_000,
+      ),
+      ownerInfo: runtime.getFileAckOwnerInfo(transferId),
+    };
+  }
+
+  function settleFileAckWaiter(
+    waiter: {
+      resolve: (payload: Record<string, unknown>) => void;
+      reject: (err: Error) => void;
+    },
+    payload: Record<string, unknown>,
+    ok: boolean,
+  ) {
+    if (ok) {
+      waiter.resolve(payload);
+      return;
+    }
+    waiter.reject(
+      new Error(runtime.asString(payload?.errorMessage || payload?.error || 'file ack failed')),
+    );
+  }
+
+  function consumeEarlyFileAck(ack: {
+    transferId: string;
+    stage: string;
+    chunkIndex?: number;
+    key: string;
+    ownerInfo: Record<string, unknown>;
+  }): Promise<Record<string, unknown>> | null {
+    const cached = runtime.earlyFileAcks.get(ack.key);
+    if (!cached) return null;
+    runtime.earlyFileAcks.delete(ack.key);
+    runtime.logInfo(
+      'file-ack-cache-hit',
+      JSON.stringify({
+        bridge: runtime.bridgeId,
+        transferId: ack.transferId,
+        stage: ack.stage,
+        ackStage: ack.stage,
+        ackOutcome: cached.ok ? 'acked' : 'failed',
+        waiterReused: false,
+        chunkIndex: ack.chunkIndex,
+        key: ack.key,
+        ...ack.ownerInfo,
+        ok: cached.ok,
+        payload: cached.payload,
+      }),
+      { debugOnly: true },
+    );
+    if (cached.ok) return Promise.resolve(cached.payload);
+    return Promise.reject(
+      new Error(
+        runtime.asString(
+          cached.payload?.errorMessage || cached.payload?.error || 'file ack failed',
+        ),
+      ),
+    );
+  }
+
+  function waitForFileAck(params: {
+    transferId: string;
+    stage: string;
+    chunkIndex?: number;
+    timeoutMs?: number;
+  }) {
+    const ack = buildFileAckWaitContext(params);
+
+    const cached = consumeEarlyFileAck(ack);
+    if (cached) return cached;
+
+    const existing = runtime.fileAckWaiters.get(ack.key);
+    if (existing) {
+      runtime.logWarn(
+        'file-ack-waiter-reuse',
+        JSON.stringify({
+          bridge: runtime.bridgeId,
+          transferId: ack.transferId,
+          stage: ack.stage,
+          ackStage: ack.stage,
+          ackOutcome: 'waiter-reused',
+          waiterReused: true,
+          chunkIndex: ack.chunkIndex,
+          key: ack.key,
+          ...ack.ownerInfo,
+        }),
+        { debugOnly: true },
+      );
+      return existing.promise;
+    }
+
+    runtime.logInfo(
+      'file-ack-wait',
+      JSON.stringify({
+        bridge: runtime.bridgeId,
+        transferId: ack.transferId,
+        stage: ack.stage,
+        ackStage: ack.stage,
+        ackOutcome: 'waiting',
+        waiterReused: false,
+        chunkIndex: ack.chunkIndex,
+        key: ack.key,
+        ...ack.ownerInfo,
+        timeoutMs: ack.timeoutMs,
+      }),
+      { debugOnly: true },
+    );
+
+    let timer: NodeJS.Timeout;
+    let resolveWaiter!: (payload: Record<string, unknown>) => void;
+    let rejectWaiter!: (err: Error) => void;
+    const promise = new Promise<Record<string, unknown>>((resolve, reject) => {
+      resolveWaiter = resolve;
+      rejectWaiter = reject;
+      timer = setTimeout(() => {
+        runtime.fileAckWaiters.delete(ack.key);
+        runtime.logWarn(
+          OUTBOUND_TERMINAL_REASON.FILE_ACK_TIMEOUT,
+          JSON.stringify({
+            bridge: runtime.bridgeId,
+            transferId: ack.transferId,
+            stage: ack.stage,
+            ackStage: ack.stage,
+            ackOutcome: 'timeout',
+            waiterReused: false,
+            chunkIndex: ack.chunkIndex,
+            key: ack.key,
+            ...ack.ownerInfo,
+            timeoutMs: ack.timeoutMs,
+          }),
+          { debugOnly: true },
+        );
+        reject(new Error(`file ack timeout: ${ack.key}`));
+      }, ack.timeoutMs);
+    });
+    runtime.fileAckWaiters.set(ack.key, {
+      promise,
+      resolve: resolveWaiter,
+      reject: rejectWaiter,
+      timer: timer!,
+    });
+    return promise;
+  }
+
+  function resolveFileAck(params: {
+    transferId: string;
+    stage: string;
+    chunkIndex?: number;
+    payload: Record<string, unknown>;
+    ok: boolean;
+  }) {
+    const ack = buildFileAckWaitContext(params);
+    const waiter = runtime.fileAckWaiters.get(ack.key);
+    if (!waiter) {
+      rememberEarlyFileAck(ack.key, {
+        payload: params.payload,
+        ok: params.ok,
+        at: runtime.now(),
+      });
+      runtime.logInfo(
+        'file-ack-early-cache',
+        JSON.stringify({
+          bridge: runtime.bridgeId,
+          transferId: ack.transferId,
+          stage: ack.stage,
+          ackStage: ack.stage,
+          ackOutcome: params.ok ? 'early-acked' : 'early-failed',
+          waiterReused: false,
+          chunkIndex: ack.chunkIndex,
+          key: ack.key,
+          ...ack.ownerInfo,
+          ok: params.ok,
+          payload: params.payload,
+          cached: true,
+        }),
+        { debugOnly: true },
+      );
+      return false;
+    }
+    runtime.fileAckWaiters.delete(ack.key);
+    clearTimeout(waiter.timer);
+    runtime.logInfo(
+      'file-ack-resolve',
+      JSON.stringify({
+        bridge: runtime.bridgeId,
+        transferId: ack.transferId,
+        stage: ack.stage,
+        ackStage: ack.stage,
+        ackOutcome: params.ok ? 'acked' : 'failed',
+        waiterReused: false,
+        chunkIndex: ack.chunkIndex,
+        key: ack.key,
+        ...ack.ownerInfo,
+        ok: params.ok,
+        payload: params.payload,
+      }),
+      { debugOnly: true },
+    );
+    settleFileAckWaiter(waiter, params.payload, params.ok);
+    return true;
+  }
+
+  function clearAllFileAckWaiters(reason: string) {
+    for (const waiter of runtime.fileAckWaiters.values()) {
+      clearTimeout(waiter.timer);
+      waiter.reject(new Error(reason));
+    }
+    runtime.fileAckWaiters.clear();
+    runtime.earlyFileAcks.clear();
+  }
+
+  return {
+    rememberEarlyFileAck,
+    fileAckKey,
+    buildFileAckWaitContext,
+    consumeEarlyFileAck,
+    settleFileAckWaiter,
+    waitForFileAck,
+    resolveFileAck,
+    clearAllFileAckWaiters,
+  };
+}

package/src/plugin/file-inbound-abort.ts

@@ -0,0 +1,112 @@
+import type { GatewayRequestHandlerOptions } from 'openclaw/plugin-sdk/core';
+import type { BncrFileInboundRuntime } from './file-inbound-runtime.ts';
+import {
+  isAbortedInboundTransfer,
+  isCompletedInboundTransfer,
+  markInboundTransferAborted,
+} from './file-inbound-state.ts';
+import { buildBncrGatewayEventContext } from './gateway-event-context.ts';
+
+export function createBncrFileInboundAbortHandler(runtime: BncrFileInboundRuntime) {
+  return async function handleFileAbort({
+    params,
+    respond,
+    client,
+    context,
+  }: GatewayRequestHandlerOptions) {
+    const gatewayContext = buildBncrGatewayEventContext({
+      params,
+      client,
+      context,
+      asString: runtime.asString,
+      normalizeAccountId: runtime.normalizeAccountId,
+      now: runtime.now,
+    });
+    const { accountId, connId, clientId } = gatewayContext;
+
+    const transferId = runtime.asString(params?.transferId || '').trim();
+    if (!transferId) {
+      respond(false, { error: 'transferId required' });
+      return;
+    }
+
+    const st = runtime.fileRecvTransfers.get(transferId);
+    if (!st) {
+      respond(true, { ok: true, transferId, message: 'not-found' });
+      return;
+    }
+    if (isCompletedInboundTransfer(st)) {
+      respond(true, {
+        ok: true,
+        transferId,
+        status: 'completed',
+        path: st.completedPath,
+        ignored: true,
+        terminal: true,
+      });
+      return;
+    }
+    if (isAbortedInboundTransfer(st)) {
+      respond(true, {
+        ok: true,
+        transferId,
+        status: 'aborted',
+        error: st.error,
+        ignored: true,
+        terminal: true,
+      });
+      return;
+    }
+
+    const staleObserved = runtime.observeLease('file.abort', params ?? {});
+    if (staleObserved.stale) {
+      if (
+        !runtime.matchesTransferOwner({
+          ownerConnId: st.ownerConnId,
+          ownerClientId: st.ownerClientId,
+          connId,
+          clientId,
+        })
+      ) {
+        runtime.logWarn(
+          'stale',
+          `ignore kind=file.abort accountId=${accountId} connId=${connId} clientId=${clientId || '-'} transferId=${transferId} reason=owner-mismatch ownerConnId=${st.ownerConnId || '-'} ownerClientId=${st.ownerClientId || '-'}`,
+          { debugOnly: true },
+        );
+        respond(true, { ok: true, stale: true, ignored: true });
+        return;
+      }
+    } else {
+      runtime.refreshAcceptedFileTransferLiveState({
+        accountId,
+        connId,
+        clientId,
+        context: gatewayContext.context,
+      });
+    }
+
+    const abortedState = markInboundTransferAborted(
+      st,
+      runtime.asString(params?.reason || 'aborted'),
+      runtime.now(),
+    );
+    runtime.fileRecvTransfers.set(transferId, abortedState);
+
+    respond(
+      true,
+      staleObserved.stale
+        ? {
+            ok: true,
+            transferId,
+            status: 'aborted',
+            stale: true,
+            staleAccepted: true,
+          }
+        : {
+            ok: true,
+            transferId,
+            status: 'aborted',
+          },
+    );
+  };
+}