@xmoxmo/bncr 0.3.6 → 0.3.8

package/src/plugin/messaging.ts

@@ -1,37 +1,95 @@
+import type { ChatType } from 'openclaw/plugin-sdk/core';
 import { BNCR_DEFAULT_ACCOUNT_ID, normalizeAccountId } from '../core/accounts.ts';
-import { formatDisplayScope, formatTargetDisplay, parseExplicitTarget } from '../core/targets.ts';
+import { formatDisplayScope, parseExplicitTarget } from '../core/targets.ts';
+import type { BncrRoute } from '../core/types.ts';
+import { asSanitizedString } from '../core/value-sanitize.ts';
 import { resolveBncrOutboundSessionRoute } from '../messaging/outbound/session-route.ts';
 import {
   looksLikeBncrExplicitTarget,
   resolveBncrOutboundTarget,
 } from '../messaging/outbound/target-resolver.ts';
+import type { BncrChannelConfigRoot } from './channel-runtime-types.ts';
 
 type BncrMessagingRuntimeBridge = {
   canonicalAgentId?: string;
-  ensureCanonicalAgentId: (params: { cfg: any; accountId: string }) => string;
-  resolveRouteBySession: (raw: string, accountId: string) => any;
+  ensureCanonicalAgentId: (params: { cfg: BncrChannelConfigRoot; accountId: string }) => string;
+  resolveRouteBySession: (raw: string, accountId: string) => BncrRoute | null;
 };
 
-function asString(v: unknown, fallback = ''): string {
-  return typeof v === 'string' ? v : fallback;
+type BncrMessagingTargetDisplayInput = {
+  target?:
+    | string
+    | {
+        displayScope?: string;
+        to?: string;
+        platform?: string;
+        groupId?: string;
+        userId?: string;
+      }
+    | null;
+  display?: string;
+  kind?: string;
+};
+
+type BncrMessagingExplicitTargetArgs = { raw: string };
+
+type BncrMessagingSessionTargetArgs = {
+  kind?: 'group' | 'channel' | string;
+  id: string;
+  threadId?: string | null;
+};
+
+type BncrMessagingOutboundSessionRouteArgs = {
+  agentId: string;
+  target: string;
+  resolvedTarget?: { to?: string } | null;
+  currentSessionKey?: string;
+  replyToId?: string | null;
+  threadId?: string | number | null;
+  accountId?: string | null;
+  cfg: BncrChannelConfigRoot;
+};
+
+type BncrMessagingResolveTargetArgs = {
+  accountId?: string | null;
+  input?: string;
+  normalized?: string;
+  preferredKind?: string;
+};
+
+function isDisplayTarget(
+  value: unknown,
+): value is Exclude<NonNullable<BncrMessagingTargetDisplayInput['target']>, string> {
+  return Boolean(value && typeof value === 'object');
 }
 
 export function normalizeBncrMessagingTarget(raw: string) {
-  const input = asString(raw).trim();
+  const input = asSanitizedString(raw).trim();
   return input || undefined;
 }
 
-export function formatBncrMessagingTargetDisplay({ target }: any) {
-  return formatTargetDisplay(target);
+export function formatBncrMessagingTargetDisplay({ target }: BncrMessagingTargetDisplayInput) {
+  if (typeof target === 'string') return asSanitizedString(target).trim();
+  if (!isDisplayTarget(target)) return '';
+  const displayScope = asSanitizedString(target?.displayScope || target?.to).trim();
+  if (displayScope) return displayScope;
+  if (target.platform || target.groupId || target.userId) {
+    return formatDisplayScope({
+      platform: asSanitizedString(target.platform).trim(),
+      groupId: asSanitizedString(target.groupId).trim(),
+      userId: asSanitizedString(target.userId).trim(),
+    });
+  }
+  return '';
 }
 
 function resolveMessagingAccountId(accountId: unknown) {
-  return normalizeAccountId(asString(accountId || BNCR_DEFAULT_ACCOUNT_ID));
+  return normalizeAccountId(asSanitizedString(accountId || BNCR_DEFAULT_ACCOUNT_ID));
 }
 
 function resolveMessagingCanonicalAgentId(
   runtimeBridge: BncrMessagingRuntimeBridge,
-  cfg: any,
+  cfg: BncrChannelConfigRoot,
   accountId: string,
 ) {
   return runtimeBridge.canonicalAgentId || runtimeBridge.ensureCanonicalAgentId({ cfg, accountId });
@@ -40,38 +98,33 @@ function resolveMessagingCanonicalAgentId(
 export function createBncrMessagingExplicitTargetParser(
   getBridge: () => BncrMessagingRuntimeBridge,
 ) {
-  return ({ raw, accountId, cfg }: any) => {
-    const resolvedAccountId = resolveMessagingAccountId(accountId);
+  return ({ raw }: BncrMessagingExplicitTargetArgs) => {
     const runtimeBridge = getBridge();
-    const canonicalAgentId = resolveMessagingCanonicalAgentId(
-      runtimeBridge,
-      cfg,
-      resolvedAccountId,
-    );
-    return parseExplicitTarget(asString(raw).trim(), { canonicalAgentId });
+    const canonicalAgentId = runtimeBridge.canonicalAgentId || 'main';
+    const parsed = parseExplicitTarget(asSanitizedString(raw).trim(), { canonicalAgentId });
+    if (!parsed) return null;
+    const chatType: ChatType = parsed.route?.groupId ? 'group' : 'direct';
+    return {
+      to: parsed.displayScope,
+      displayScope: parsed.displayScope,
+      threadId: undefined,
+      chatType,
+    };
   };
 }
 
 export function createBncrMessagingSessionTargetResolver(
   getBridge: () => BncrMessagingRuntimeBridge,
 ) {
-  return ({ id, accountId, cfg }: any) => {
-    const raw = asString(id).trim();
+  return ({ id }: BncrMessagingSessionTargetArgs) => {
+    const raw = asSanitizedString(id).trim();
     if (!raw) return undefined;
-    const resolvedAccountId = resolveMessagingAccountId(accountId);
     const runtimeBridge = getBridge();
-    const canonicalAgentId = resolveMessagingCanonicalAgentId(
-      runtimeBridge,
-      cfg,
-      resolvedAccountId,
-    );
+    const canonicalAgentId = runtimeBridge.canonicalAgentId || 'main';
 
-    let parsed = parseExplicitTarget(raw, { canonicalAgentId });
+    const parsed = parseExplicitTarget(raw, { canonicalAgentId });
     if (!parsed) {
-      const route = runtimeBridge.resolveRouteBySession(raw, resolvedAccountId);
-      if (route) {
-        parsed = parseExplicitTarget(formatDisplayScope(route), { canonicalAgentId });
-      }
+      return raw || undefined;
     }
     return parsed?.displayScope || undefined;
   };
@@ -80,7 +133,7 @@ export function createBncrMessagingSessionTargetResolver(
 export function createBncrMessagingOutboundSessionRouteResolver(
   getBridge: () => BncrMessagingRuntimeBridge,
 ) {
-  return (params: any) => {
+  return (params: BncrMessagingOutboundSessionRouteArgs) => {
     const accountId = resolveMessagingAccountId(params?.accountId);
     const runtimeBridge = getBridge();
     const canonicalAgentId = resolveMessagingCanonicalAgentId(
@@ -89,7 +142,16 @@ export function createBncrMessagingOutboundSessionRouteResolver(
       accountId,
     );
     return resolveBncrOutboundSessionRoute({
-      ...params,
+      channel: 'bncr',
+      cfg: params.cfg,
+      agentId: params.agentId,
+      accountId: params.accountId ?? undefined,
+      target: params.target,
+      resolvedTarget: params.resolvedTarget,
+      threadId:
+        params.threadId === null || params.threadId === undefined
+          ? undefined
+          : asSanitizedString(params.threadId),
       canonicalAgentId,
       resolveRouteBySession: (raw: string, acc: string) =>
         runtimeBridge.resolveRouteBySession(raw, acc),
@@ -112,12 +174,12 @@ export function createBncrMessagingSurface(getBridge: () => BncrMessagingRuntime
 export function createBncrMessagingTargetResolver(getBridge: () => BncrMessagingRuntimeBridge) {
   return {
     looksLikeId: (raw: string, normalized?: string) => {
-      return looksLikeBncrExplicitTarget(asString(normalized || raw).trim());
+      return looksLikeBncrExplicitTarget(asSanitizedString(normalized || raw).trim());
     },
-    resolveTarget: async ({ accountId, input, normalized }: any) => {
+    resolveTarget: async ({ accountId, input, normalized }: BncrMessagingResolveTargetArgs) => {
       const runtimeBridge = getBridge();
       const resolved = resolveBncrOutboundTarget({
-        target: asString(normalized || input).trim(),
+        target: asSanitizedString(normalized || input).trim(),
         accountId: resolveMessagingAccountId(accountId),
         resolveRouteBySession: (raw: string, acc: string) =>
           runtimeBridge.resolveRouteBySession(raw, acc),

package/src/plugin/outbound.ts

@@ -10,17 +10,59 @@ function asString(v: unknown, fallback = ''): string {
   return typeof v === 'string' ? v : v == null ? fallback : String(v);
 }
 
+type BncrOutboundDeliveryResult = { channel: string; messageId: string; chatId: string };
+
+type BncrOutboundSendContext = {
+  accountId?: string | null;
+  to?: string;
+  text?: string;
+  mediaUrl?: string;
+  type?: string;
+  kind?: string;
+  replyToId?: string | null;
+  replyToMessageId?: string | null;
+  asVoice?: boolean;
+  audioAsVoice?: boolean;
+  mediaLocalRoots?: readonly string[];
+};
+
+type BncrOutboundReplyActionContext = {
+  accountId?: string | null;
+  to?: string;
+  text?: string;
+  replyToId?: string | null;
+  replyToMessageId?: string | null;
+};
+
+type BncrOutboundTargetActionContext = {
+  accountId?: string | null;
+  messageId?: string | null;
+  targetMessageId?: string | null;
+};
+
+type BncrOutboundReactActionContext = BncrOutboundTargetActionContext & {
+  emoji?: string | null;
+};
+
+type BncrOutboundEditActionContext = BncrOutboundTargetActionContext & {
+  text?: string;
+};
+
 export type BncrOutboundBridge = {
-  channelSendText: (ctx: any) => unknown | Promise<unknown>;
-  channelSendMedia: (ctx: any) => unknown | Promise<unknown>;
+  channelSendText: (
+    ctx: BncrOutboundSendContext,
+  ) => BncrOutboundDeliveryResult | Promise<BncrOutboundDeliveryResult>;
+  channelSendMedia: (
+    ctx: BncrOutboundSendContext,
+  ) => BncrOutboundDeliveryResult | Promise<BncrOutboundDeliveryResult>;
 };
 
 export function createBncrOutboundRuntime(getBridge: () => BncrOutboundBridge) {
   return {
     deliveryMode: 'gateway' as const,
-    sendText: async (ctx: any) => getBridge().channelSendText(ctx),
-    sendMedia: async (ctx: any) => getBridge().channelSendMedia(ctx),
-    replyAction: async (ctx: any) =>
+    sendText: async (ctx: BncrOutboundSendContext) => getBridge().channelSendText(ctx),
+    sendMedia: async (ctx: BncrOutboundSendContext) => getBridge().channelSendMedia(ctx),
+    replyAction: async (ctx: BncrOutboundReplyActionContext) =>
       sendBncrReplyAction({
         accountId: normalizeAccountId(ctx?.accountId),
         to: asString(ctx?.to || '').trim(),
@@ -30,18 +72,18 @@ export function createBncrOutboundRuntime(getBridge: () => BncrOutboundBridge) {
         sendText: async ({ accountId, to, text }) =>
           getBridge().channelSendText({ accountId, to, text }),
       }),
-    deleteAction: async (ctx: any) =>
+    deleteAction: async (ctx: BncrOutboundTargetActionContext) =>
       deleteBncrMessageAction({
         accountId: normalizeAccountId(ctx?.accountId),
         targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
       }),
-    reactAction: async (ctx: any) =>
+    reactAction: async (ctx: BncrOutboundReactActionContext) =>
       reactBncrMessageAction({
         accountId: normalizeAccountId(ctx?.accountId),
         targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),
         emoji: asString(ctx?.emoji || '').trim(),
       }),
-    editAction: async (ctx: any) =>
+    editAction: async (ctx: BncrOutboundEditActionContext) =>
       editBncrMessageAction({
         accountId: normalizeAccountId(ctx?.accountId),
         targetMessageId: asString(ctx?.messageId || ctx?.targetMessageId || '').trim(),

package/src/plugin/outbox-ack-logs.ts

@@ -0,0 +1,136 @@
+import type { BncrRoute, OutboxEntry } from '../core/types.ts';
+import {
+  buildOutboxAckDebugInfo,
+  buildOutboxScheduleDebugInfo,
+  buildRetryRerouteDebugInfo,
+} from '../messaging/outbound/diagnostics.ts';
+import { computeOutboxRetryWait } from '../messaging/outbound/queue-selectors.ts';
+import { OUTBOUND_SCHEDULE_SOURCE } from '../messaging/outbound/reasons.ts';
+import type { RetryRerouteDecision } from '../messaging/outbound/retry-policy.ts';
+
+export type BncrOutboxAckLogsRuntime = {
+  bridgeId: string;
+  pushEvent: string;
+  now: () => number;
+  outboxSize: () => number;
+  adaptiveAckTimeoutEnabled: boolean;
+  formatDisplayScope: (route: BncrRoute) => string;
+  isFileTransferEntry: (entry: OutboxEntry) => boolean;
+  logInfo: (scope: string, message: string, options?: { debugOnly?: boolean }) => void;
+};
+
+export function createBncrOutboxAckLogs(runtime: BncrOutboxAckLogsRuntime) {
+  const logOutboxAckSummary = (
+    scope:
+      | 'outbox ack ok'
+      | 'outbox ack ok late'
+      | 'outbox ack retry'
+      | 'outbox ack timeout'
+      | 'outbox ack fatal',
+    args: {
+      messageId: string;
+      connId?: string;
+      clientId?: string;
+      err?: string;
+      queueMs?: number | null;
+      pushMs?: number | null;
+      waitMs?: number | null;
+    },
+  ) => {
+    const parts = [`mid=${args.messageId}`, `q=${runtime.outboxSize()}`];
+    if (typeof args.queueMs === 'number') parts.push(`queueMs=${args.queueMs}`);
+    if (typeof args.pushMs === 'number') parts.push(`pushMs=${args.pushMs}`);
+    if (typeof args.waitMs === 'number') parts.push(`waitMs=${args.waitMs}`);
+    if (args.err) parts.push(`err=${args.err}`);
+    runtime.logInfo(scope, parts.join('|'));
+  };
+
+  const logOutboxAckWait = (args: {
+    entry: OutboxEntry;
+    requireAck: boolean;
+    ackResult: 'acked' | 'timeout';
+    onlineNow: boolean;
+    recentInboundReachable: boolean;
+    ackTimeoutMs?: number | null;
+  }) => {
+    runtime.logInfo(
+      'outbox',
+      `ack ${JSON.stringify(
+        buildOutboxAckDebugInfo({
+          messageId: args.entry.messageId,
+          accountId: args.entry.accountId,
+          sessionKey: args.entry.sessionKey,
+          to: runtime.formatDisplayScope(args.entry.route),
+          kind: runtime.isFileTransferEntry(args.entry) ? 'file-transfer' : undefined,
+          requireAck: args.requireAck,
+          ackResult: args.ackResult,
+          ackStage: 'message',
+          ackOutcome: args.ackResult,
+          reason: args.ackResult === 'timeout' ? 'push-ack-timeout' : 'message-acked',
+          ackTimeoutMs: typeof args.ackTimeoutMs === 'number' ? args.ackTimeoutMs : undefined,
+          adaptiveAckTimeoutEnabled: runtime.adaptiveAckTimeoutEnabled,
+          onlineNow: args.onlineNow,
+          recentInboundReachable: args.recentInboundReachable,
+          connIds: args.entry.lastPushConnId ? [args.entry.lastPushConnId] : [],
+          ownerConnId: args.entry.lastPushConnId,
+          ownerClientId: args.entry.lastPushClientId,
+          event: runtime.pushEvent,
+        }),
+      )}`,
+      { debugOnly: true },
+    );
+  };
+
+  const logOutboxAckReroute = (args: {
+    accountId: string;
+    entry: OutboxEntry;
+    requireAck: boolean;
+    currentConnId: string;
+    availableConnIds: string[];
+    decision: Extract<RetryRerouteDecision, { kind: 'retry' }>;
+    localNextDelay: number | null;
+    ackTimeoutMs?: number | null;
+  }) => {
+    logOutboxAckSummary(args.requireAck ? 'outbox ack timeout' : 'outbox ack retry', {
+      messageId: args.entry.messageId,
+      connId: args.entry.lastPushConnId,
+      clientId: args.entry.lastPushClientId,
+      err: args.requireAck ? undefined : args.entry.lastError,
+      waitMs: args.requireAck ? args.ackTimeoutMs : undefined,
+    });
+    runtime.logInfo(
+      'outbox',
+      `retry-reroute ${JSON.stringify(
+        buildRetryRerouteDebugInfo({
+          messageId: args.entry.messageId,
+          accountId: args.accountId,
+          currentConnId: args.currentConnId,
+          decision: args.decision,
+          availableConnIds: args.availableConnIds,
+        }),
+      )}`,
+      { debugOnly: true },
+    );
+
+    runtime.logInfo(
+      'outbox',
+      `schedule ${JSON.stringify(
+        buildOutboxScheduleDebugInfo({
+          bridgeId: runtime.bridgeId,
+          accountId: args.accountId,
+          messageId: args.entry.messageId,
+          source: OUTBOUND_SCHEDULE_SOURCE.RETRY_REROUTE_WAIT,
+          wait: computeOutboxRetryWait(args.decision.nextAttemptAt, runtime.now()),
+          localNextDelay: args.localNextDelay,
+        }),
+      )}`,
+      { debugOnly: true },
+    );
+  };
+
+  return {
+    logOutboxAckSummary,
+    logOutboxAckWait,
+    logOutboxAckReroute,
+  };
+}

package/src/plugin/outbox-ack-outcome.ts

@@ -0,0 +1,128 @@
+import type { OutboxEntry } from '../core/types.ts';
+import {
+  buildBncrAckOkTelemetryPatch,
+  buildBncrAckRetryEntryPatch,
+} from '../runtime/outbox-transitions.ts';
+
+export type BncrOutboxAckOkTelemetryPatch = ReturnType<typeof buildBncrAckOkTelemetryPatch>;
+
+export type BncrOutboxAckOutcomeRuntime = {
+  now: () => number;
+  defaultAckTimeoutMs: number;
+  markOutboundCapability: (args: {
+    accountId: string;
+    connId: string;
+    clientId?: string;
+    outboundReady: boolean;
+    preferredForOutbound: boolean;
+  }) => void;
+  recordAckOkTelemetry: (args: {
+    accountId: string;
+    entry: OutboxEntry;
+    telemetryPatch: BncrOutboxAckOkTelemetryPatch;
+  }) => void;
+  deleteOutboxEntry: (messageId: string) => void;
+  setOutboxEntry: (messageId: string, entry: OutboxEntry) => void;
+  scheduleSave: () => void;
+  resolveMessageAck: (messageId: string, result: 'acked' | 'timeout') => void;
+  moveToDeadLetter: (entry: OutboxEntry, reason: string) => void;
+  logOutboxAckSummary: (
+    scope: 'outbox ack ok' | 'outbox ack ok late' | 'outbox ack retry' | 'outbox ack fatal',
+    args: {
+      messageId: string;
+      connId?: string;
+      clientId?: string;
+      err?: string;
+      queueMs?: number | null;
+      pushMs?: number | null;
+      waitMs?: number | null;
+    },
+  ) => void;
+};
+
+export function createBncrOutboxAckOutcome(runtime: BncrOutboxAckOutcomeRuntime) {
+  const handleAckOk = (args: {
+    accountId: string;
+    messageId: string;
+    connId: string;
+    clientId?: string;
+    stale: boolean;
+    entry: OutboxEntry;
+  }) => {
+    runtime.markOutboundCapability({
+      accountId: args.accountId,
+      connId: args.connId,
+      clientId: args.clientId,
+      outboundReady: true,
+      preferredForOutbound: true,
+    });
+    const telemetryPatch = buildBncrAckOkTelemetryPatch({
+      entry: args.entry,
+      ackAt: runtime.now(),
+      defaultAckTimeoutMs: runtime.defaultAckTimeoutMs,
+    });
+    runtime.recordAckOkTelemetry({
+      accountId: args.accountId,
+      entry: args.entry,
+      telemetryPatch,
+    });
+    runtime.deleteOutboxEntry(args.messageId);
+    runtime.scheduleSave();
+    runtime.resolveMessageAck(args.messageId, 'acked');
+    runtime.logOutboxAckSummary(
+      telemetryPatch.lateAccepted ? 'outbox ack ok late' : 'outbox ack ok',
+      {
+        messageId: args.messageId,
+        connId: args.connId,
+        clientId: args.clientId,
+        queueMs: telemetryPatch.ackQueueLatencyMs,
+        pushMs: telemetryPatch.ackPushLatencyMs,
+        err: telemetryPatch.lateAccepted ? 'accepted-after-timeout' : undefined,
+      },
+    );
+  };
+
+  const handleAckFatal = (args: {
+    entry: OutboxEntry;
+    messageId: string;
+    connId: string;
+    clientId?: string;
+    error: string;
+  }) => {
+    runtime.moveToDeadLetter(args.entry, args.error);
+    runtime.logOutboxAckSummary('outbox ack fatal', {
+      messageId: args.messageId,
+      connId: args.connId,
+      clientId: args.clientId,
+      err: args.error,
+    });
+  };
+
+  const handleAckRetry = (args: {
+    entry: OutboxEntry;
+    messageId: string;
+    connId: string;
+    clientId?: string;
+    error: string;
+  }) => {
+    const nextEntry = buildBncrAckRetryEntryPatch({
+      entry: args.entry,
+      error: args.error,
+      nextAttemptAt: runtime.now() + 1_000,
+    });
+    runtime.setOutboxEntry(args.messageId, nextEntry);
+    runtime.scheduleSave();
+    runtime.logOutboxAckSummary('outbox ack retry', {
+      messageId: args.messageId,
+      connId: args.connId,
+      clientId: args.clientId,
+      err: nextEntry.lastError,
+    });
+  };
+
+  return {
+    handleAckOk,
+    handleAckFatal,
+    handleAckRetry,
+  };
+}