@xmoxmo/bncr 0.3.5 → 0.3.7

package/src/core/types.ts

@@ -10,6 +10,85 @@ export type BncrConnection = {
   clientId?: string;
   connectedAt: number;
   lastSeenAt: number;
+  inboundOnly?: boolean;
+  outboundReady?: boolean;
+  preferredForOutbound?: boolean;
+};
+
+export type BncrGatewayCapabilityFlags = {
+  outboundReady: boolean;
+  preferredForOutbound: boolean;
+  inboundOnly: boolean;
+};
+
+export type FileRecvTransferStatus = 'init' | 'transferring' | 'completed' | 'aborted';
+
+type FileRecvTransferBase = {
+  transferId: string;
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  fileName: string;
+  mimeType: string;
+  fileSize: number;
+  chunkSize: number;
+  totalChunks: number;
+  fileSha256: string;
+  startedAt: number;
+  bufferByChunk: Map<number, Buffer>;
+  receivedChunks: Set<number>;
+  ownerConnId?: string;
+  ownerClientId?: string;
+};
+
+export type FileRecvTransferInitState = FileRecvTransferBase & {
+  status: 'init';
+};
+
+export type FileRecvTransferTransferringState = FileRecvTransferBase & {
+  status: 'transferring';
+};
+
+export type FileRecvTransferCompletedState = FileRecvTransferBase & {
+  status: 'completed';
+  completedPath: string;
+  terminalAt: number;
+};
+
+export type FileRecvTransferAbortedState = FileRecvTransferBase & {
+  status: 'aborted';
+  terminalAt: number;
+  error: string;
+};
+
+export type FileRecvTransferState =
+  | FileRecvTransferInitState
+  | FileRecvTransferTransferringState
+  | FileRecvTransferCompletedState
+  | FileRecvTransferAbortedState;
+
+export type FileSendTransferStatus = 'init' | 'transferring' | 'completed' | 'aborted';
+
+export type FileSendTransferState = {
+  transferId: string;
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  fileName: string;
+  mimeType: string;
+  fileSize: number;
+  chunkSize: number;
+  totalChunks: number;
+  fileSha256: string;
+  startedAt: number;
+  status: FileSendTransferStatus;
+  ackedChunks: Set<number>;
+  failedChunks: Map<number, string>;
+  ownerConnId?: string;
+  ownerClientId?: string;
+  completedPath?: string;
+  terminalAt?: number;
+  error?: string;
 };
 
 export type PendingAdmission = {
@@ -78,3 +157,145 @@ export type BncrDiagnosticsSummary = {
     ok: boolean;
   };
 };
+
+export type BncrDeadLetterDiagnosticsSummary = {
+  total: number;
+  allAccountsTotal: number;
+  sinceStart: number;
+  cappedAt: number;
+  oldestAt: number | null;
+  newestAt: number | null;
+  topReasons: Array<{ reason: string; count: number }>;
+};
+
+export type BncrDeadLetterEntrySummary = {
+  messageId: string;
+  accountId: string;
+  sessionKey: string;
+  route: string;
+  kind: string;
+  createdAt: number | null;
+  retryCount: number;
+  lastError: string | null;
+  textPreview: string;
+};
+
+export type BncrDownlinkHealthSummary = {
+  pendingOutbox: number;
+  oldestPendingCreatedAt: number | null;
+  oldestPendingAgeMs: number;
+  lastAckOkAt: number | null;
+  lastAckTimeoutAt: number | null;
+  recentAckTimeoutCount: number;
+  activeConnectionCount: number;
+  recentInboundReachable: boolean;
+  onlineByConn: boolean;
+  ackStalled: boolean;
+  recommendReconnect: boolean;
+  recommendReason: string;
+};
+
+export type BncrAckObservability = {
+  lastAckOkAt: number | null;
+  lastAckTimeoutAt: number | null;
+  recentAckTimeoutCount: number;
+  lateAckOkCount: number;
+  lastLateAckOkAt: number | null;
+  lastLateAckAgeMs: number | null;
+  lateAckObservationTtlMs: number;
+  lateAckObservationExpired: boolean;
+  adaptiveAckRecoveryOkCount: number;
+  adaptiveAckRecoveryOkThreshold: number;
+  adaptiveAckRecovered: boolean;
+  lastAckQueueLatencyMs: number | null;
+  lastAckPushLatencyMs: number | null;
+  lastLateAckQueueLatencyMs: number | null;
+  lastLateAckPushLatencyMs: number | null;
+  adaptiveAckTimeoutEnabled: boolean;
+  defaultAckTimeoutMs: number;
+  currentAckTimeoutMs: number;
+  recommendedAckTimeoutMs: number;
+  recommendedAckTimeoutReason: string;
+};
+
+export type BncrAckStrategy = {
+  mode: 'adaptive' | 'fixed';
+  currentMs: number;
+  defaultMs: number;
+  maxMs: number;
+  reason: string;
+  active: boolean;
+  lastLateAckAgeMs: number | null;
+  lateAckObservationTtlMs: number | null;
+  recovered: boolean;
+};
+
+export type BncrStaleCounterSummary = {
+  staleConnect: number;
+  staleInbound: number;
+  staleActivity: number;
+  staleAck: number;
+  staleFileInit: number;
+  staleFileChunk: number;
+  staleFileComplete: number;
+  staleFileAbort: number;
+  lastStaleAt: number | null;
+};
+
+export type BncrRuntimeLastSession = {
+  sessionKey: string;
+  scope: string;
+  updatedAt: number;
+};
+
+export type BncrOutboxQueueDiagnostics = {
+  pending: number;
+  pendingAllAccounts: number;
+  oldestPendingAt: number | null;
+  newestPendingAt: number | null;
+  lastAttemptAt: number | null;
+  lastPushAt: number | null;
+  lastPushError: string | null;
+  activeOutboundConnection: boolean;
+  activeOutboundConnectionCount: number;
+};
+
+export type BncrOutboxIncidentAckSummary = {
+  lastQueueLatencyMs: number | null;
+  lastPushLatencyMs: number | null;
+  lastLateQueueLatencyMs: number | null;
+  lastLatePushLatencyMs: number | null;
+  lastLateAckAgeMs: number | null;
+  adaptiveTimeoutMs: number | null;
+  adaptiveTimeoutReason: string | null;
+};
+
+export type BncrOutboxIncidentSummary = {
+  active: boolean;
+  type: string;
+  severity: 'ok' | 'warning' | 'critical';
+  recommendedAction: string;
+  pending: number;
+  oldestPendingAgeMs: number | null;
+  lastAttemptAgeMs: number | null;
+  lastPushAgeMs: number | null;
+  lastPushError: string | null;
+  hasGatewayContext: boolean;
+  activeOutboundConnection: boolean;
+  activeOutboundConnectionCount: number;
+  prePushGuardSkipCount: number;
+  lastPrePushGuardSkipAgeMs: number | null;
+  lastPrePushGuardSkipReason: string | null;
+  ack: BncrOutboxIncidentAckSummary;
+};
+
+export type BncrExtendedOutboundDiagnostics = BncrOutboxQueueDiagnostics & {
+  enqueueCount: number;
+  lastEnqueueAt: number | null;
+  prePushGuardSkipCount: number;
+  lastPrePushGuardSkipAt: number | null;
+  lastPrePushGuardSkipReason: string | null;
+  hasGatewayContext: boolean;
+  lastGatewayContextAt: number | null;
+  incident: BncrOutboxIncidentSummary;
+};

package/src/core/value-sanitize.ts

@@ -0,0 +1,29 @@
+export function asSanitizedString(value: unknown, fallback = ''): string {
+  if (typeof value === 'string') return value;
+  if (value == null) return fallback;
+  return String(value);
+}
+
+export function finiteNumberOr(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+export function finiteNumberOrNull(value: unknown): number | null {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : null;
+}
+
+export function nonNegativeFiniteNumberOr(value: unknown, fallback: number): number {
+  return Math.max(0, finiteNumberOr(value, fallback));
+}
+
+export function clampFiniteNumber(
+  value: unknown,
+  fallback: number,
+  min: number,
+  max: number,
+): number {
+  const finite = finiteNumberOr(value, fallback);
+  return Math.max(min, Math.min(finite, max));
+}

package/src/messaging/inbound/commands.ts

@@ -1,21 +1,37 @@
 import { emitBncrLogLine } from '../../core/logging.ts';
 import { resolveBncrChannelPolicy } from '../../core/policy.ts';
-import {
-  formatDisplayScope,
-  normalizeInboundSessionKey,
-  withTaskSessionKey,
-} from '../../core/targets.ts';
+import { formatDisplayScope } from '../../core/targets.ts';
 import {
   recordBncrInboundSession,
   resolveBncrInboundSessionStorePath,
   resolveBncrPinnedMainDmOwnerFromAllowlist,
 } from '../../openclaw/inbound-session-runtime.ts';
 import { dispatchOpenClawReplyWithBufferedBlockDispatcher } from '../../openclaw/reply-runtime.ts';
-import { resolveOpenClawAgentRoute } from '../../openclaw/routing-runtime.ts';
-import type { OutboundReplyTargetPolicy } from '../outbound/reply-target-policy.ts';
+import {
+  type OpenClawResolvedAgentRoute,
+  resolveOpenClawAgentRoute,
+} from '../../openclaw/routing-runtime.ts';
+import type {
+  BncrEnqueueFromReply,
+  BncrInboundApi,
+  BncrInboundConfig,
+  BncrInboundLogger,
+  BncrRememberSessionRoute,
+} from './contracts.ts';
+import type { ParsedInbound } from './dispatch-prep.ts';
 import { buildBncrInboundRecordUpdateLastRoute } from './last-route.ts';
 import { parseBncrNativeCommand, resolveBncrNativeVerboseCommand } from './native-command.ts';
-import { buildBncrNativeReplyDeliveryPayload } from './native-reply-delivery.ts';
+import {
+  buildBncrNativeCommandSessionState,
+  buildBncrNativeCommandSummary,
+  buildNativeCommandHandledResult,
+  buildNativeCommandRecordErrorLogger,
+  createNativeCommandReplyDeliverer,
+  createNativeCommandTurnContext,
+  logBncrNativeCommandEvent,
+  logBncrNativeCommandSummary,
+  resolveNativeCommandDebugEnabled,
+} from './native-command-runtime.ts';
 import { buildBncrReplyConfig } from './reply-config.ts';
 import { resolveBncrChannelInboundRuntime } from './runtime-compat.ts';
 import {
@@ -24,54 +40,63 @@ import {
   wrapBncrInboundRecordSessionLabelCorrection,
 } from './session-label.ts';
 
-type ParsedInbound = ReturnType<typeof import('./parse.ts')['parseBncrInboundParams']>;
+function assertResolvedAgentRoute(resolvedRoute: OpenClawResolvedAgentRoute): {
+  sessionKey: string;
+  agentId: string;
+  mainSessionKey?: string;
+} {
+  const sessionKey =
+    typeof resolvedRoute.sessionKey === 'string' ? resolvedRoute.sessionKey.trim() : '';
+  const agentId = typeof resolvedRoute.agentId === 'string' ? resolvedRoute.agentId.trim() : '';
+  if (!sessionKey) throw new Error('OpenClaw resolveAgentRoute returned empty sessionKey');
+  if (!agentId) throw new Error('OpenClaw resolveAgentRoute returned empty agentId');
+  return {
+    sessionKey,
+    agentId,
+    ...(typeof resolvedRoute.mainSessionKey === 'string' && resolvedRoute.mainSessionKey.trim()
+      ? { mainSessionKey: resolvedRoute.mainSessionKey }
+      : {}),
+  };
+}
 
-function logBncrNativeCommandEvent(
-  event: string,
-  fields: Record<string, unknown>,
-  options?: { debugOnly?: boolean; debugEnabled?: boolean },
-) {
-  if (options?.debugOnly && !options?.debugEnabled) return;
-  emitBncrLogLine('info', `[bncr] native-command ${JSON.stringify({ event, ...fields })}`);
+function buildBncrNativeCommandResolvedRoute(args: {
+  api: BncrInboundApi;
+  cfg: BncrInboundConfig;
+  channelId: string;
+  accountId: string;
+  peer: ParsedInbound['peer'];
+}) {
+  return assertResolvedAgentRoute(
+    resolveOpenClawAgentRoute(args.api, {
+      cfg: args.cfg,
+      channel: args.channelId,
+      accountId: args.accountId,
+      peer: args.peer,
+    }),
+  );
 }
 
 export { parseBncrNativeCommand } from './native-command.ts';
 
 export async function handleBncrNativeCommand(params: {
-  api: any;
+  api: BncrInboundApi;
   channelId: string;
-  cfg: any;
+  cfg: BncrInboundConfig;
   parsed: ParsedInbound;
   canonicalAgentId: string;
-  rememberSessionRoute: (sessionKey: string, accountId: string, route: any) => void;
-  enqueueFromReply: (args: {
-    accountId: string;
-    sessionKey: string;
-    route: any;
-    payload: { text?: string; mediaUrl?: string; mediaUrls?: string[] };
-    mediaLocalRoots?: readonly string[];
-    replyTargetPolicy?: OutboundReplyTargetPolicy;
-  }) => Promise<void>;
-  logger?: { warn?: (msg: string) => void; error?: (msg: string) => void };
+  rememberSessionRoute: BncrRememberSessionRoute;
+  enqueueFromReply: BncrEnqueueFromReply;
+  logger?: BncrInboundLogger;
 }): Promise<
   | { handled: false }
   | { handled: true; command: string; sessionKey: string; fallbackToAgent?: boolean }
 > {
   const { api, channelId, cfg, parsed, canonicalAgentId, rememberSessionRoute, enqueueFromReply } =
     params;
-  const {
-    accountId,
-    route,
-    peer,
-    sessionKeyfromroute,
-    providedOriginatingTo,
-    clientId,
-    extracted,
-    msgId,
-  } = parsed;
+  const { accountId, route, peer, clientId, extracted, msgId } = parsed;
   const command = parseBncrNativeCommand(extracted.text);
   if (!command) return { handled: false };
-  const nativeCommandDebugEnabled = cfg?.channels?.[channelId]?.debug?.verbose === true;
+  const nativeCommandDebugEnabled = resolveNativeCommandDebugEnabled({ cfg, channelId });
 
   logBncrNativeCommandEvent(
     'detected',
@@ -84,24 +109,23 @@ export async function handleBncrNativeCommand(params: {
     { debugOnly: true, debugEnabled: nativeCommandDebugEnabled },
   );
 
-  const resolvedRoute = resolveOpenClawAgentRoute(api, {
+  const resolvedRoute = buildBncrNativeCommandResolvedRoute({
+    api,
     cfg,
-    channel: channelId,
+    channelId,
     accountId,
     peer,
   });
 
-  const baseSessionKey =
-    normalizeInboundSessionKey(sessionKeyfromroute, route, canonicalAgentId) ||
-    resolvedRoute.sessionKey;
-  const taskSessionKey = withTaskSessionKey(baseSessionKey, extracted.taskKey);
-  const sessionKey = taskSessionKey || baseSessionKey;
+  const { baseSessionKey, taskSessionKey, sessionKey, displayTo, originatingTo } =
+    buildBncrNativeCommandSessionState({
+      parsed,
+      canonicalAgentId,
+      resolvedRoute,
+    });
   rememberSessionRoute(baseSessionKey, accountId, route);
   if (taskSessionKey && taskSessionKey !== baseSessionKey)
     rememberSessionRoute(taskSessionKey, accountId, route);
-
-  const displayTo = formatDisplayScope(route);
-  const originatingTo = providedOriginatingTo || displayTo;
   const body = command.body;
   if (!clientId) {
     emitBncrLogLine(
@@ -116,72 +140,22 @@ export async function handleBncrNativeCommand(params: {
     agentId: resolvedRoute.agentId,
   });
 
-  const ctxPayload = resolveBncrChannelInboundRuntime(api).buildContext({
-    channel: channelId,
-    provider: channelId,
-    surface: channelId,
-    accountId,
-    messageId: msgId,
-    timestamp: Date.now(),
-    from: senderIdForContext,
-    sender: {
-      id: senderIdForContext,
-      name: senderDisplayName,
-      username: senderDisplayName,
-    },
-    conversation: {
-      kind: peer.kind,
-      id: peer.id,
-      label: displayTo,
-      routePeer: {
-        kind: peer.kind,
-        id: peer.id,
-      },
-    },
-    route: {
-      agentId: resolvedRoute.agentId,
+  const ctxPayload = await Promise.resolve(
+    createNativeCommandTurnContext({
+      api,
+      channelId,
       accountId,
-      routeSessionKey: resolvedRoute.sessionKey,
-      dispatchSessionKey: sessionKey,
-      mainSessionKey: resolvedRoute.mainSessionKey,
-    },
-    reply: {
-      to: displayTo,
+      msgId: msgId || undefined,
+      peer,
+      resolvedRoute,
+      sessionKey,
+      displayTo,
       originatingTo,
-      replyToId: msgId,
-    },
-    message: {
-      inboundEventKind: 'user_request',
-      body,
-      rawBody: body,
-      bodyForAgent: body,
-      commandBody: body,
-      envelopeFrom: originatingTo,
-      senderLabel: senderDisplayName,
-    },
-    commandTurn: {
-      kind: 'native',
-      source: 'native',
-      authorized: true,
+      senderIdForContext,
+      senderDisplayName,
       body,
-    },
-    access: {
-      mentions: {
-        canDetectMention: true,
-        wasMentioned: true,
-        effectiveWasMentioned: true,
-      },
-      commands: {
-        authorized: true,
-        allowTextCommands: true,
-        useAccessGroups: false,
-        authorizers: [],
-      },
-    },
-    extra: {
-      OriginatingChannel: channelId,
-    },
-  });
+    }),
+  );
 
   const sessionIdentityPatch = buildBncrInboundSessionIdentityPatch({
     channelId,
@@ -193,14 +167,28 @@ export async function handleBncrNativeCommand(params: {
 
   const nativeVerbose = resolveBncrNativeVerboseCommand(command);
   if (nativeVerbose) {
-    logBncrNativeCommandEvent('handled-verbose', {
-      command: command.command,
-      accountId,
-      sessionKey,
-      to: displayTo,
-      msgId: msgId || null,
-      fallbackToAgent: false,
-    });
+    logBncrNativeCommandSummary(
+      buildBncrNativeCommandSummary({
+        kind: 'verbose',
+        command: command.command,
+        accountId,
+        to: displayTo,
+        msgId: msgId || null,
+        result: 'handled',
+      }),
+    );
+    logBncrNativeCommandEvent(
+      'handled-verbose',
+      {
+        command: command.command,
+        accountId,
+        sessionKey,
+        to: displayTo,
+        msgId: msgId || null,
+        fallbackToAgent: false,
+      },
+      { debugOnly: true, debugEnabled: nativeCommandDebugEnabled },
+    );
     await recordAndPatchBncrInboundSessionEntry({
       storePath,
       sessionKey,
@@ -235,7 +223,7 @@ export async function handleBncrNativeCommand(params: {
   const pinnedMainDmOwner =
     peer.kind === 'direct'
       ? resolveBncrPinnedMainDmOwnerFromAllowlist({
-          dmScope: cfg?.session?.dmScope,
+          dmScope: cfg?.session?.dmScope as string | undefined,
           allowFrom: channelPolicy.allowFrom,
           normalizeEntry: (entry: string) => String(entry || '').trim(),
         })
@@ -283,16 +271,15 @@ export async function handleBncrNativeCommand(params: {
         storePath,
         ctxPayload,
         recordInboundSession: wrapBncrInboundRecordSessionLabelCorrection({
-          recordInboundSession: recordBncrInboundSession,
+          recordInboundSession: recordBncrInboundSession as (
+            ...args: unknown[]
+          ) => Promise<unknown> | unknown,
           expectedLabel: displayTo,
         }),
         record: {
           updateLastRoute,
           onRecordError: (err: unknown) => {
-            emitBncrLogLine(
-              'warn',
-              `[bncr] inbound record native command session failed: ${String(err)}`,
-            );
+            buildNativeCommandRecordErrorLogger(err);
           },
         },
         runDispatch: () =>
@@ -300,47 +287,21 @@ export async function handleBncrNativeCommand(params: {
             ctx: ctxPayload,
             cfg: effectiveReply.replyCfg,
             dispatcherOptions: {
-              deliver: async (
-                payload: {
-                  text?: string;
-                  mediaUrl?: string;
-                  mediaUrls?: string[];
-                  audioAsVoice?: boolean;
+              deliver: createNativeCommandReplyDeliverer({
+                command: command.command,
+                accountId,
+                sessionKey,
+                to: displayTo,
+                msgId: msgId || undefined,
+                effectiveReply,
+                route,
+                enqueueFromReply,
+                nativeCommandDebugEnabled,
+                onResponded: () => responded,
+                markResponded: () => {
+                  responded = true;
                 },
-                info?: { kind?: 'tool' | 'block' | 'final' },
-              ) => {
-                const kind = info?.kind;
-                const deliveryPayload = buildBncrNativeReplyDeliveryPayload({
-                  payload,
-                  kind,
-                  effectiveReply,
-                  msgId,
-                });
-                if (!deliveryPayload) return;
-                if (!responded) {
-                  logBncrNativeCommandEvent(
-                    'payload-produced',
-                    {
-                      command: command.command,
-                      accountId,
-                      sessionKey,
-                      to: displayTo,
-                      msgId: msgId || null,
-                      kind: kind || null,
-                      fallbackToAgent: false,
-                    },
-                    { debugOnly: true, debugEnabled: nativeCommandDebugEnabled },
-                  );
-                }
-                responded = true;
-                await enqueueFromReply({
-                  accountId,
-                  sessionKey,
-                  route,
-                  payload: deliveryPayload,
-                  replyTargetPolicy: 'preserve',
-                });
-              },
+              }),
             },
             replyOptions: {
               disableBlockStreaming: !effectiveReply.blockStreaming,
@@ -352,15 +313,26 @@ export async function handleBncrNativeCommand(params: {
   });
 
   if (!responded) {
-    logBncrNativeCommandEvent('no-payload-fallback-to-agent', {
+    logBncrNativeCommandSummary(
+      `fallback command=${command.command}|accountId=${accountId}|to=${displayTo}|msgId=${msgId || '-'}|reason=no-payload`,
+    );
+    logBncrNativeCommandEvent(
+      'no-payload-fallback-to-agent',
+      {
+        command: command.command,
+        accountId,
+        sessionKey,
+        to: displayTo,
+        msgId: msgId || null,
+        fallbackToAgent: true,
+      },
+      { debugOnly: true, debugEnabled: nativeCommandDebugEnabled },
+    );
+    return buildNativeCommandHandledResult({
       command: command.command,
-      accountId,
       sessionKey,
-      to: displayTo,
-      msgId: msgId || null,
       fallbackToAgent: true,
     });
-    return { handled: true, command: command.command, sessionKey, fallbackToAgent: true };
   }
 
   logBncrNativeCommandEvent(
@@ -375,5 +347,8 @@ export async function handleBncrNativeCommand(params: {
     },
     { debugOnly: true, debugEnabled: nativeCommandDebugEnabled },
   );
-  return { handled: true, command: command.command, sessionKey };
+  return buildNativeCommandHandledResult({
+    command: command.command,
+    sessionKey,
+  });
 }