@xmoxmo/bncr 0.3.6 → 0.3.8

package/src/plugin/media-orchestrators-runtime-group.ts

@@ -0,0 +1,316 @@
+import type { BncrRoute, FileSendTransferState, OutboxEntry } from '../core/types.ts';
+import { normalizeMessageText } from '../messaging/outbound/media-dedupe.ts';
+import type {
+  NormalizedReplyPayload,
+  OutboundReplyTargetPolicy,
+  ReplyMediaEntriesParams,
+  ReplyPayloadInput,
+} from '../messaging/outbound/reply-enqueue.ts';
+import {
+  enqueueNormalizedReplyPayload,
+  enqueueReplyTextEntry,
+  normalizeReplyPayload,
+} from '../messaging/outbound/reply-enqueue.ts';
+import {
+  enqueueReplyMediaFallbackTextEntry,
+  enqueueReplyMediaFileTransferEntry,
+  enqueueSingleReplyMediaEntry,
+} from '../messaging/outbound/reply-enqueue-media.ts';
+import type { createBncrFileAckRuntime } from './file-ack-runtime.ts';
+import { createBncrFileTransferOrchestrator } from './file-transfer-orchestrator.ts';
+import type { createBncrFileTransferSetup } from './file-transfer-setup.ts';
+
+type PreparedOutboundTransfer = Awaited<
+  ReturnType<ReturnType<typeof createBncrFileTransferSetup>['prepareOutboundTransfer']>
+>;
+type FileAckPayload = Awaited<
+  ReturnType<ReturnType<typeof createBncrFileAckRuntime>['waitForFileAck']>
+>;
+
+function buildReplyMediaEntryHelpers(runtime: {
+  logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  enqueueOutbound: (entry: OutboxEntry) => void;
+  buildTextOutboxEntry: (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    text: string;
+    kind?: 'tool' | 'block' | 'final';
+    replyToId?: string;
+    replyTargetPolicy?: OutboundReplyTargetPolicy;
+  }) => OutboxEntry;
+  buildFileTransferOutboxEntry: (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    mediaUrl: string;
+    mediaLocalRoots?: readonly string[];
+    text: string;
+    asVoice: boolean;
+    audioAsVoice: boolean;
+    type?: string;
+    kind?: 'tool' | 'block' | 'final';
+    replyToId?: string;
+    replyTargetPolicy?: OutboundReplyTargetPolicy;
+  }) => OutboxEntry;
+  rememberRecentMediaSend: (args: {
+    sessionKey: string;
+    mediaUrl: string;
+    text: string;
+    replyToId: string;
+    createdAt: number;
+  }) => void;
+}) {
+  return {
+    enqueueReplyMediaFallbackTextEntry: (
+      params: Parameters<typeof enqueueReplyMediaFallbackTextEntry>[0],
+    ) =>
+      enqueueReplyMediaFallbackTextEntry(params, {
+        logInfo: runtime.logInfo,
+        enqueueOutbound: runtime.enqueueOutbound,
+        buildTextOutboxEntry: runtime.buildTextOutboxEntry,
+      }),
+    enqueueReplyMediaFileTransferEntry: (
+      params: Parameters<typeof enqueueReplyMediaFileTransferEntry>[0],
+    ) =>
+      enqueueReplyMediaFileTransferEntry(params, {
+        enqueueOutbound: runtime.enqueueOutbound,
+        buildFileTransferOutboxEntry: runtime.buildFileTransferOutboxEntry,
+        rememberRecentMediaSend: runtime.rememberRecentMediaSend,
+      }),
+  };
+}
+
+function buildReplyTextEntryHelper(runtime: {
+  enqueueOutbound: (entry: OutboxEntry) => void;
+  buildTextOutboxEntry: (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    text: string;
+    kind?: 'tool' | 'block' | 'final';
+    replyToId?: string;
+    replyTargetPolicy?: OutboundReplyTargetPolicy;
+  }) => OutboxEntry;
+}) {
+  return (params: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    payload: NormalizedReplyPayload;
+  }) =>
+    enqueueReplyTextEntry(params, {
+      enqueueOutbound: runtime.enqueueOutbound,
+      buildTextOutboxEntry: runtime.buildTextOutboxEntry,
+    });
+}
+
+function normalizeReplyOrchestratorPayload(args: {
+  payload: ReplyPayloadInput;
+  asString: (value: unknown, fallback?: string) => string;
+  replyTargetPolicy?: OutboundReplyTargetPolicy;
+}) {
+  return normalizeReplyPayload(
+    args.payload,
+    { asString: args.asString },
+    {
+      replyTargetPolicy: args.replyTargetPolicy,
+    },
+  );
+}
+
+export function createBncrMediaOrchestratorsRuntimeGroup(runtime: {
+  now: () => number;
+  asString: (value: unknown, fallback?: string) => string;
+  fileSendTransfers: Map<string, FileSendTransferState>;
+  getGatewayContext: () => {
+    broadcastToConnIds: (event: string, payload: unknown, connIds: ReadonlySet<string>) => void;
+  } | null;
+  fileInitEvent: string;
+  fileAbortEvent: string;
+  prepareOutboundTransfer: (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    mediaUrl: string;
+    mediaLocalRoots?: readonly string[];
+    hasGatewayContext: boolean;
+  }) => Promise<PreparedOutboundTransfer>;
+  sendChunk: (args: {
+    transferId: string;
+    accountId: string;
+    chunkIndex: number;
+    attempt: number;
+    offset: number;
+    size: number;
+    chunkSha256: string;
+    base64: string;
+    connIds: ReadonlySet<string>;
+  }) => void;
+  sendComplete: (args: {
+    transferId: string;
+    accountId: string;
+    connIds: ReadonlySet<string>;
+  }) => void;
+  waitForFileAck: (params: {
+    transferId: string;
+    stage: string;
+    chunkIndex?: number;
+    timeoutMs: number;
+  }) => Promise<FileAckPayload>;
+  logFileTransferChunkAck: (args: {
+    transferId: string;
+    accountId: string;
+    chunkIndex: number;
+    attempt: number;
+  }) => void;
+  logFileTransferChunkAckFail: (args: {
+    transferId: string;
+    accountId: string;
+    chunkIndex: number;
+    attempt: number;
+    error: unknown;
+  }) => void;
+  logFileTransferCompleteAck: (args: {
+    transferId: string;
+    accountId: string;
+    payload: { path: string };
+  }) => void;
+  logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  logEnqueueFromReply: (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    payload: NormalizedReplyPayload;
+  }) => void;
+  enqueueOutbound: (entry: OutboxEntry) => void;
+  buildTextOutboxEntry: (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    text: string;
+    kind?: 'tool' | 'block' | 'final';
+    replyToId?: string;
+    replyTargetPolicy?: OutboundReplyTargetPolicy;
+  }) => OutboxEntry;
+  buildFileTransferOutboxEntry: (args: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    mediaUrl: string;
+    mediaLocalRoots?: readonly string[];
+    text: string;
+    asVoice: boolean;
+    audioAsVoice: boolean;
+    type?: string;
+    kind?: 'tool' | 'block' | 'final';
+    replyToId?: string;
+    replyTargetPolicy?: OutboundReplyTargetPolicy;
+  }) => OutboxEntry;
+  rememberRecentMediaSend: (args: {
+    sessionKey: string;
+    mediaUrl: string;
+    text: string;
+    replyToId: string;
+    createdAt: number;
+  }) => void;
+  tryBuildMediaDedupeFallback: (args: {
+    sessionKey: string;
+    mediaUrl: string;
+    text: string;
+    replyToId: string;
+    currentTime: number;
+  }) => {
+    text: string;
+    reason: 'same-text-sent-checkmark' | 'text-changed-downgrade';
+  } | null;
+}) {
+  const fileTransferOrchestrator = createBncrFileTransferOrchestrator({
+    now: runtime.now,
+    fileSendTransfers: runtime.fileSendTransfers,
+    getGatewayContext: runtime.getGatewayContext,
+    fileInitEvent: runtime.fileInitEvent,
+    fileAbortEvent: runtime.fileAbortEvent,
+    prepareOutboundTransfer: runtime.prepareOutboundTransfer,
+    sendChunk: runtime.sendChunk,
+    sendComplete: runtime.sendComplete,
+    waitForFileAck: runtime.waitForFileAck,
+    logFileTransferChunkAck: runtime.logFileTransferChunkAck,
+    logFileTransferChunkAckFail: runtime.logFileTransferChunkAckFail,
+    logFileTransferCompleteAck: runtime.logFileTransferCompleteAck,
+  });
+
+  const replyMediaEntryHelpers = buildReplyMediaEntryHelpers(runtime);
+  const replyTextEntryHelper = buildReplyTextEntryHelper(runtime);
+
+  const enqueueReplyMediaEntries = (params: ReplyMediaEntriesParams) => {
+    let first = true;
+    const currentTime = runtime.now();
+
+    for (const mediaUrl of params.payload.mediaList) {
+      const normalizedText = normalizeMessageText(first ? params.payload.text : '');
+      const fallback = runtime.tryBuildMediaDedupeFallback({
+        sessionKey: params.sessionKey,
+        mediaUrl,
+        text: normalizedText,
+        replyToId: params.payload.replyToId,
+        currentTime,
+      });
+
+      enqueueSingleReplyMediaEntry(
+        {
+          params,
+          mediaUrl,
+          normalizedText,
+          text: first ? params.payload.text : '',
+          fallback,
+          currentTime,
+        },
+        replyMediaEntryHelpers,
+      );
+
+      first = false;
+    }
+  };
+
+  const enqueueFromReply = (params: {
+    accountId: string;
+    sessionKey: string;
+    route: BncrRoute;
+    payload: ReplyPayloadInput;
+    mediaLocalRoots?: readonly string[];
+    replyTargetPolicy?: OutboundReplyTargetPolicy;
+  }) => {
+    const { accountId, sessionKey, route, payload, mediaLocalRoots, replyTargetPolicy } = params;
+    const normalized = normalizeReplyOrchestratorPayload({
+      payload,
+      asString: runtime.asString,
+      replyTargetPolicy,
+    });
+
+    enqueueNormalizedReplyPayload(
+      {
+        accountId,
+        sessionKey,
+        route,
+        payload: normalized,
+        mediaLocalRoots,
+      },
+      {
+        logEnqueueFromReply: runtime.logEnqueueFromReply,
+        enqueueReplyMediaEntries,
+        enqueueReplyTextEntry: replyTextEntryHelper,
+      },
+    );
+  };
+
+  const replyMediaOrchestrator = {
+    enqueueFromReply,
+    enqueueReplyMediaEntries,
+  };
+
+  return {
+    fileTransferOrchestrator,
+    replyMediaOrchestrator,
+  };
+}

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

@@ -0,0 +1,284 @@
+import type { GatewayRequestHandlerOptions } from 'openclaw/plugin-sdk/core';
+import type { OutboxEntry } from '../core/types.ts';
+import { buildBncrGatewayEventContext } from './gateway-event-context.ts';
+
+export type MessageAckWaitResult = 'acked' | 'timeout';
+
+export type MessageAckWaiter = {
+  promise: Promise<MessageAckWaitResult>;
+  resolve: (result: MessageAckWaitResult) => void;
+  timer: NodeJS.Timeout;
+};
+
+export function createBncrMessageAckRuntime(runtime: {
+  asString: (value: unknown, fallback?: string) => string;
+  now: () => number;
+  clampFiniteNumber: (value: unknown, fallback: number, min: number, max: number) => number;
+  normalizeAccountId: (accountId: string) => string;
+  recommendedAckTimeoutMaxMs: number;
+  messageAckWaiters: Map<string, MessageAckWaiter>;
+  stopped: () => boolean;
+  outbox: Map<string, OutboxEntry>;
+  observeLease: (
+    kind:
+      | 'connect'
+      | 'inbound'
+      | 'activity'
+      | 'ack'
+      | 'file.init'
+      | 'file.chunk'
+      | 'file.complete'
+      | 'file.abort',
+    payload: Record<string, unknown>,
+  ) => { stale: boolean };
+  rememberGatewayContext: (context: GatewayRequestHandlerOptions['context']) => void;
+  markSeen: (accountId: string, connId: string, clientId?: string) => void;
+  logInfo: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  logWarn: (scope: string | undefined, message: string, options?: { debugOnly?: boolean }) => void;
+  handleAckOk: (args: {
+    accountId: string;
+    messageId: string;
+    connId: string;
+    clientId?: string;
+    stale: boolean;
+    entry: OutboxEntry;
+  }) => void;
+  handleAckFatal: (args: {
+    entry: OutboxEntry;
+    messageId: string;
+    connId: string;
+    clientId?: string;
+    error: string;
+  }) => void;
+  handleAckRetry: (args: {
+    entry: OutboxEntry;
+    messageId: string;
+    connId: string;
+    clientId?: string;
+    error: string;
+  }) => void;
+  flushPushQueueBestEffort: (args?: {
+    accountId?: string;
+    trigger?: string;
+    reason?: string;
+  }) => void;
+  outboundFlushTriggerAckOk: string;
+  outboundFlushReasonMessageAcked: string;
+}) {
+  function clearAllMessageAckWaiters(result: MessageAckWaitResult = 'timeout') {
+    for (const waiter of runtime.messageAckWaiters.values()) {
+      clearTimeout(waiter.timer);
+      waiter.resolve(result);
+    }
+    runtime.messageAckWaiters.clear();
+  }
+
+  function resolveMessageAck(messageId: string, result: MessageAckWaitResult = 'acked') {
+    const key = runtime.asString(messageId).trim();
+    if (!key) return false;
+    const waiter = runtime.messageAckWaiters.get(key);
+    if (!waiter) return false;
+    runtime.messageAckWaiters.delete(key);
+    clearTimeout(waiter.timer);
+    waiter.resolve(result);
+    return true;
+  }
+
+  async function waitForMessageAck(
+    messageId: string,
+    waitMs: number,
+  ): Promise<MessageAckWaitResult> {
+    const key = runtime.asString(messageId).trim();
+    const timeoutMs = runtime.clampFiniteNumber(waitMs, 0, 0, runtime.recommendedAckTimeoutMaxMs);
+    if (!key || !timeoutMs) return 'timeout';
+
+    const existing = runtime.messageAckWaiters.get(key);
+    if (existing) {
+      runtime.logWarn('outbox', `message-ack-waiter-reuse ${JSON.stringify({ messageId: key })}`, {
+        debugOnly: true,
+      });
+      return await existing.promise;
+    }
+
+    let timer: NodeJS.Timeout;
+    let resolveWaiter!: (result: MessageAckWaitResult) => void;
+    const promise = new Promise<MessageAckWaitResult>((resolve) => {
+      resolveWaiter = resolve;
+      timer = setTimeout(() => {
+        runtime.messageAckWaiters.delete(key);
+        resolve('timeout');
+      }, timeoutMs);
+    });
+
+    runtime.messageAckWaiters.set(key, { promise, resolve: resolveWaiter, timer: timer! });
+    return await promise;
+  }
+
+  function prepareAckHandling(args: {
+    params: GatewayRequestHandlerOptions['params'];
+    respond: GatewayRequestHandlerOptions['respond'];
+    client: GatewayRequestHandlerOptions['client'];
+    context: GatewayRequestHandlerOptions['context'];
+  }): {
+    accountId: string;
+    connId: string;
+    clientId?: string;
+    messageId: string;
+    entry: OutboxEntry;
+    staleObserved: { stale: boolean };
+  } | null {
+    const { params, respond, client, context } = args;
+    const gatewayContext = buildBncrGatewayEventContext({
+      params,
+      client,
+      context,
+      asString: runtime.asString,
+      normalizeAccountId: runtime.normalizeAccountId,
+      now: runtime.now,
+    });
+    const { accountId, connId, clientId } = gatewayContext;
+    const messageId = runtime.asString(params?.messageId || '').trim();
+    const staleObserved = runtime.observeLease('ack', params ?? {});
+
+    runtime.logInfo(
+      'outbox',
+      `ack ${JSON.stringify({
+        accountId,
+        messageId,
+        ok: params?.ok !== false,
+        fatal: params?.fatal === true,
+        error: runtime.asString(params?.error || ''),
+        stale: staleObserved.stale,
+      })}`,
+      { debugOnly: true },
+    );
+    if (!messageId) {
+      respond(false, { error: 'messageId required' });
+      return null;
+    }
+
+    if (runtime.stopped()) {
+      respond(true, { ok: true, ignored: true, reason: 'service-stopped' });
+      return null;
+    }
+
+    const entry = runtime.outbox.get(messageId);
+    if (!entry) {
+      respond(true, { ok: true, message: 'already-acked-or-missing', stale: staleObserved.stale });
+      return null;
+    }
+
+    if (entry.accountId !== accountId) {
+      respond(false, { error: 'account mismatch' });
+      return null;
+    }
+
+    if (staleObserved.stale) {
+      const sameConn = !!entry.lastPushConnId && entry.lastPushConnId === connId;
+      const sameClient =
+        !entry.lastPushConnId &&
+        !!entry.lastPushClientId &&
+        !!clientId &&
+        entry.lastPushClientId === clientId;
+      if (!(sameConn || sameClient)) {
+        runtime.logWarn(
+          'stale',
+          `ignore kind=ack accountId=${accountId} connId=${connId} clientId=${clientId || '-'} messageId=${messageId} reason=owner-mismatch lastPushConnId=${entry.lastPushConnId || '-'} lastPushClientId=${entry.lastPushClientId || '-'}`,
+          { debugOnly: true },
+        );
+        respond(true, { ok: true, stale: true, ignored: true });
+        return null;
+      }
+    } else {
+      runtime.rememberGatewayContext(gatewayContext.context);
+      runtime.markSeen(accountId, connId, clientId);
+    }
+
+    return {
+      accountId,
+      connId,
+      clientId,
+      messageId,
+      entry,
+      staleObserved,
+    };
+  }
+
+  function respondAckResult(
+    respond: GatewayRequestHandlerOptions['respond'],
+    stale: boolean,
+    result: { ok: true; movedToDeadLetter?: true; willRetry?: true },
+  ) {
+    respond(true, stale ? { ...result, stale: true, staleAccepted: true } : result);
+  }
+
+  function handleAckOutcome(args: {
+    params: GatewayRequestHandlerOptions['params'];
+    respond: GatewayRequestHandlerOptions['respond'];
+    accountId: string;
+    connId: string;
+    clientId?: string;
+    messageId: string;
+    entry: OutboxEntry;
+    staleObserved: { stale: boolean };
+  }) {
+    const { params, respond, accountId, connId, clientId, messageId, entry, staleObserved } = args;
+    const ok = params?.ok !== false;
+    const fatal = params?.fatal === true;
+
+    if (ok) {
+      runtime.handleAckOk({
+        accountId,
+        messageId,
+        connId,
+        clientId,
+        stale: staleObserved.stale,
+        entry,
+      });
+      respondAckResult(respond, staleObserved.stale, { ok: true });
+      runtime.flushPushQueueBestEffort({
+        accountId,
+        trigger: runtime.outboundFlushTriggerAckOk,
+        reason: runtime.outboundFlushReasonMessageAcked,
+      });
+      return;
+    }
+
+    if (fatal) {
+      const error = runtime.asString(params?.error || 'fatal-ack');
+      runtime.handleAckFatal({
+        entry,
+        messageId,
+        connId,
+        clientId,
+        error,
+      });
+      respondAckResult(respond, staleObserved.stale, {
+        ok: true,
+        movedToDeadLetter: true,
+      });
+      return;
+    }
+
+    runtime.handleAckRetry({
+      entry,
+      messageId,
+      connId,
+      clientId,
+      error: runtime.asString(params?.error || 'retryable-ack'),
+    });
+
+    respondAckResult(respond, staleObserved.stale, {
+      ok: true,
+      willRetry: true,
+    });
+  }
+
+  return {
+    clearAllMessageAckWaiters,
+    resolveMessageAck,
+    waitForMessageAck,
+    prepareAckHandling,
+    handleAckOutcome,
+  };
+}

package/src/plugin/message-send.ts

@@ -1,13 +1,23 @@
+import type { ChannelMessageSendResult } from 'openclaw/plugin-sdk/channel-message';
+
+type MessageSendContext = Record<string, unknown>;
+
 export type BncrMessageSendBridge = {
-  channelMessageSendText: (ctx: any) => unknown | Promise<unknown>;
-  channelMessageSendMedia: (ctx: any) => unknown | Promise<unknown>;
-  channelMessageSendPayload: (ctx: any) => unknown | Promise<unknown>;
+  channelMessageSendText: (
+    ctx: MessageSendContext,
+  ) => ChannelMessageSendResult | Promise<ChannelMessageSendResult>;
+  channelMessageSendMedia: (
+    ctx: MessageSendContext,
+  ) => ChannelMessageSendResult | Promise<ChannelMessageSendResult>;
+  channelMessageSendPayload: (
+    ctx: MessageSendContext,
+  ) => ChannelMessageSendResult | Promise<ChannelMessageSendResult>;
 };
 
 export function createBncrMessageSend(getBridge: () => BncrMessageSendBridge) {
   return {
-    text: async (ctx: any) => getBridge().channelMessageSendText(ctx),
-    media: async (ctx: any) => getBridge().channelMessageSendMedia(ctx),
-    payload: async (ctx: any) => getBridge().channelMessageSendPayload(ctx),
+    text: async (ctx: MessageSendContext) => getBridge().channelMessageSendText(ctx),
+    media: async (ctx: MessageSendContext) => getBridge().channelMessageSendMedia(ctx),
+    payload: async (ctx: MessageSendContext) => getBridge().channelMessageSendPayload(ctx),
   };
 }