@xmoxmo/bncr 0.2.4 → 0.2.6

package/src/core/outbox-file-transfer-guards.ts

@@ -0,0 +1,66 @@
+import type { BncrConnection, OutboxEntry } from './types.ts';
+
+export type FileTransferGuardResult =
+  | { ok: false; reason: 'no-gateway-context'; lastError: 'gateway context unavailable' }
+  | {
+      ok: false;
+      reason: 'no-active-connection';
+      lastError: 'no active bncr client for file chunk transfer';
+      recentInboundReachable: boolean;
+    }
+  | { ok: false; reason: 'media-url-missing'; lastError: 'file transfer mediaUrl missing' }
+  | {
+      ok: true;
+      owner: BncrConnection | null;
+      connIds: Set<string>;
+      recentInboundReachable: boolean;
+      routeReason: string;
+      mediaUrl: string;
+    };
+
+export function resolveFileTransferGuard(args: {
+  gatewayContext: unknown;
+  entry: OutboxEntry;
+  owner: BncrConnection | null;
+  routeSelection: {
+    connIds: Iterable<string>;
+    recentInboundReachable: boolean;
+    routeReason: string;
+  };
+  mediaUrl: string;
+}): FileTransferGuardResult {
+  if (!args.gatewayContext) {
+    return {
+      ok: false,
+      reason: 'no-gateway-context',
+      lastError: 'gateway context unavailable',
+    };
+  }
+
+  const connIds = new Set(args.routeSelection.connIds);
+  if (!connIds.size) {
+    return {
+      ok: false,
+      reason: 'no-active-connection',
+      lastError: 'no active bncr client for file chunk transfer',
+      recentInboundReachable: args.routeSelection.recentInboundReachable,
+    };
+  }
+
+  if (!args.mediaUrl) {
+    return {
+      ok: false,
+      reason: 'media-url-missing',
+      lastError: 'file transfer mediaUrl missing',
+    };
+  }
+
+  return {
+    ok: true,
+    owner: args.owner,
+    connIds,
+    recentInboundReachable: args.routeSelection.recentInboundReachable,
+    routeReason: args.routeSelection.routeReason,
+    mediaUrl: args.mediaUrl,
+  };
+}

package/src/core/outbox-file-transfer-prep.ts

@@ -0,0 +1,31 @@
+import type { BncrConnection, OutboxEntry } from './types.ts';
+
+export function prepareFileTransferRouteSelection(args: {
+  entry: OutboxEntry;
+  owner: BncrConnection | null;
+  resolvePushConnIds: (accountId: string) => Iterable<string>;
+  resolveRecentInboundConnIds: (accountId: string) => Iterable<string>;
+  hasRecentInboundReachability: (accountId: string) => boolean;
+  isRevalidatedAttemptedConn: (connId: string) => boolean;
+  selectOutboxFileTransferRouteCandidates: (args: {
+    routeCandidates: Iterable<string>;
+    attemptedConnIds: string[];
+    recentInboundConnIds: Iterable<string>;
+    ownerConnId?: string;
+    recentInboundReachable: boolean;
+    isRevalidatedAttemptedConn: (connId: string) => boolean;
+  }) => { connIds: Iterable<string>; recentInboundReachable: boolean; routeReason: string };
+}) {
+  const attemptedConnIds = Array.isArray(args.entry.routeAttemptConnIds)
+    ? args.entry.routeAttemptConnIds.filter((v): v is string => typeof v === 'string' && !!v)
+    : [];
+
+  return args.selectOutboxFileTransferRouteCandidates({
+    routeCandidates: args.resolvePushConnIds(args.entry.accountId),
+    attemptedConnIds,
+    recentInboundConnIds: args.resolveRecentInboundConnIds(args.entry.accountId),
+    ownerConnId: args.owner?.connId,
+    recentInboundReachable: args.hasRecentInboundReachability(args.entry.accountId),
+    isRevalidatedAttemptedConn: args.isRevalidatedAttemptedConn,
+  });
+}

package/src/core/outbox-file-transfer-success.ts

@@ -0,0 +1,34 @@
+import type { BncrConnection, OutboxEntry } from './types.ts';
+import {
+  buildPushBroadcastPayload,
+  buildPushRouteSelectArgs,
+} from './outbox-push-args.ts';
+
+export function buildFileTransferBroadcastPayload(args: {
+  frame: Record<string, unknown>;
+  messageId: string;
+}) {
+  return buildPushBroadcastPayload({
+    payload: args.frame,
+    messageId: args.messageId,
+  });
+}
+
+export function buildFileTransferRouteSelectArgs(args: {
+  entry: OutboxEntry;
+  connIds: Iterable<string>;
+  routeReason: string;
+  recentInboundReachable: boolean;
+  owner: BncrConnection | null;
+  event: string;
+}) {
+  return buildPushRouteSelectArgs({
+    entry: args.entry,
+    connIds: args.connIds,
+    routeReason: args.routeReason,
+    recentInboundReachable: args.recentInboundReachable,
+    owner: args.owner,
+    event: args.event,
+    kind: 'file-transfer',
+  });
+}

package/src/core/outbox-push-args.ts

@@ -0,0 +1,67 @@
+import type { BncrConnection, OutboxEntry } from './types.ts';
+
+export function buildPushBroadcastPayload(args: {
+  payload: Record<string, unknown>;
+  messageId: string;
+}) {
+  return {
+    ...args.payload,
+    idempotencyKey: args.messageId,
+  };
+}
+
+export function buildPushRouteSelectArgs(args: {
+  entry: OutboxEntry;
+  connIds: Iterable<string>;
+  routeReason: string;
+  recentInboundReachable: boolean;
+  owner: BncrConnection | null;
+  event: string;
+  kind?: 'file-transfer';
+}) {
+  return {
+    messageId: args.entry.messageId,
+    accountId: args.entry.accountId,
+    kind: args.kind,
+    routeReason: args.routeReason,
+    connIds: args.connIds,
+    ownerConnId: args.owner?.connId || '',
+    ownerClientId: args.owner?.clientId || '',
+    recentInboundReachable: args.recentInboundReachable,
+    event: args.event,
+  };
+}
+
+export function buildPushOkArgs(args: {
+  entry: OutboxEntry;
+  connIds: Iterable<string>;
+  recentInboundReachable: boolean;
+  event: string;
+  kind?: 'file-transfer';
+}) {
+  return {
+    messageId: args.entry.messageId,
+    accountId: args.entry.accountId,
+    kind: args.kind,
+    connIds: args.connIds,
+    ownerConnId: args.entry.lastPushConnId || '',
+    ownerClientId: args.entry.lastPushClientId || '',
+    recentInboundReachable: args.recentInboundReachable,
+    event: args.event,
+  };
+}
+
+export function buildPushFailureArgs(args: {
+  entry: OutboxEntry;
+  retryable?: boolean;
+  kind?: 'file-transfer';
+}) {
+  return {
+    messageId: args.entry.messageId,
+    accountId: args.entry.accountId,
+    retryCount: args.entry.retryCount,
+    kind: args.kind,
+    retryable: args.retryable,
+    lastError: args.entry.lastError,
+  };
+}

package/src/core/outbox-queue.ts

@@ -0,0 +1,69 @@
+import type { OutboxEntry } from './types.ts';
+
+export function buildDeadLetterEntry(entry: OutboxEntry, reason: string): OutboxEntry {
+  return {
+    ...entry,
+    lastError: reason,
+  };
+}
+
+export function appendDeadLetter(args: {
+  deadLetter: OutboxEntry[];
+  entry: OutboxEntry;
+  maxEntries: number;
+}): OutboxEntry[] {
+  const next = [...args.deadLetter, args.entry];
+  if (next.length <= args.maxEntries) return next;
+  return next.slice(-args.maxEntries);
+}
+
+export function collectDueOutboxEntries(args: {
+  outbox: Iterable<OutboxEntry>;
+  accountId: string;
+  now: number;
+  maxBatch: number;
+  maxRetry: number;
+  backoffMs: (retryCount: number) => number;
+}): {
+  duePayloads: Array<Record<string, unknown>>;
+  updatedEntries: OutboxEntry[];
+  deadLetterEntries: OutboxEntry[];
+} {
+  const duePayloads: Array<Record<string, unknown>> = [];
+  const updatedEntries: OutboxEntry[] = [];
+  const deadLetterEntries: OutboxEntry[] = [];
+
+  for (const originalEntry of args.outbox) {
+    if (originalEntry.accountId !== args.accountId) continue;
+    if (originalEntry.nextAttemptAt > args.now) continue;
+
+    const nextAttempt = originalEntry.retryCount + 1;
+    if (nextAttempt > args.maxRetry) {
+      deadLetterEntries.push(buildDeadLetterEntry(originalEntry, 'retry-limit'));
+      continue;
+    }
+
+    const updatedEntry: OutboxEntry = {
+      ...originalEntry,
+      retryCount: nextAttempt,
+      lastAttemptAt: args.now,
+      nextAttemptAt: args.now + args.backoffMs(nextAttempt),
+    };
+    updatedEntries.push(updatedEntry);
+    duePayloads.push({
+      ...updatedEntry.payload,
+      _meta: {
+        retryCount: updatedEntry.retryCount,
+        nextAttemptAt: updatedEntry.nextAttemptAt,
+      },
+    });
+
+    if (duePayloads.length >= args.maxBatch) break;
+  }
+
+  return {
+    duePayloads,
+    updatedEntries,
+    deadLetterEntries,
+  };
+}

package/src/core/outbox-summary.ts

@@ -0,0 +1,14 @@
+import type { OutboxEntry } from './types.ts';
+
+export function summarizeOutboxEntry(args: {
+  entry: OutboxEntry;
+  asString: (value: unknown) => string;
+  formatDisplayScope: (route: OutboxEntry['route']) => string;
+  summarizeTextPreview: (raw: string, limit?: number) => string;
+}) {
+  const msg = (args.entry.payload as any)?.message || {};
+  const type = args.asString(msg.type || (args.entry.payload as any)?.type || 'unknown');
+  const text = args.asString(msg.msg || '');
+  const preview = args.summarizeTextPreview(text);
+  return [type, args.formatDisplayScope(args.entry.route), preview].join('|');
+}

package/src/core/outbox-text-push-failure.ts

@@ -0,0 +1,10 @@
+import type { OutboxEntry } from './types.ts';
+import { buildPushFailureArgs } from './outbox-push-args.ts';
+
+export function buildTextPushFailureArgs(args: {
+  entry: OutboxEntry;
+}) {
+  return buildPushFailureArgs({
+    entry: args.entry,
+  });
+}

package/src/core/outbox-text-push-guards.ts

@@ -0,0 +1,51 @@
+import type { OutboxEntry } from './types.ts';
+
+export type TextPushGuardResult =
+  | { ok: false; reason: 'no-gateway-context' }
+  | {
+      ok: false;
+      reason: 'no-active-connection';
+      recentInboundReachable: boolean;
+    }
+  | {
+      ok: true;
+      connIds: Set<string>;
+      recentInboundReachable: boolean;
+      routeReason: string;
+      ownerConnId?: string;
+    };
+
+export function resolveTextPushGuard(args: {
+  gatewayContext: unknown;
+  entry: OutboxEntry;
+  routeSelection: {
+    connIds: Iterable<string>;
+    recentInboundReachable: boolean;
+    routeReason: string;
+    ownerConnId?: string;
+  };
+}): TextPushGuardResult {
+  if (!args.gatewayContext) {
+    return {
+      ok: false,
+      reason: 'no-gateway-context',
+    };
+  }
+
+  const connIds = new Set(args.routeSelection.connIds);
+  if (!connIds.size) {
+    return {
+      ok: false,
+      reason: 'no-active-connection',
+      recentInboundReachable: args.routeSelection.recentInboundReachable,
+    };
+  }
+
+  return {
+    ok: true,
+    connIds,
+    recentInboundReachable: args.routeSelection.recentInboundReachable,
+    routeReason: args.routeSelection.routeReason,
+    ownerConnId: args.routeSelection.ownerConnId,
+  };
+}

package/src/core/outbox-text-push-prep.ts

@@ -0,0 +1,36 @@
+import type { BncrConnection, OutboxEntry } from './types.ts';
+
+export function prepareTextPushRouteSelection(args: {
+  entry: OutboxEntry;
+  owner: BncrConnection | null;
+  resolvePushConnIds: (accountId: string) => Iterable<string>;
+  resolveRecentInboundConnIds: (accountId: string) => Iterable<string>;
+  hasRecentInboundReachability: (accountId: string) => boolean;
+  isRevalidatedAttemptedConn: (connId: string) => boolean;
+  selectOutboxRouteCandidates: (args: {
+    routeCandidates: Iterable<string>;
+    attemptedConnIds: string[];
+    recentInboundConnIds: Iterable<string>;
+    ownerConnId?: string;
+    recentInboundReachable: boolean;
+    isRevalidatedAttemptedConn: (connId: string) => boolean;
+  }) => {
+    connIds: Iterable<string>;
+    recentInboundReachable: boolean;
+    routeReason: string;
+    ownerConnId?: string;
+  };
+}) {
+  const attemptedConnIds = Array.isArray(args.entry.routeAttemptConnIds)
+    ? args.entry.routeAttemptConnIds.filter((v): v is string => typeof v === 'string' && !!v)
+    : [];
+
+  return args.selectOutboxRouteCandidates({
+    routeCandidates: args.resolvePushConnIds(args.entry.accountId),
+    attemptedConnIds,
+    recentInboundConnIds: args.resolveRecentInboundConnIds(args.entry.accountId),
+    ownerConnId: args.owner?.connId,
+    recentInboundReachable: args.hasRecentInboundReachability(args.entry.accountId),
+    isRevalidatedAttemptedConn: args.isRevalidatedAttemptedConn,
+  });
+}

package/src/core/outbox-text-push-success.ts

@@ -0,0 +1,62 @@
+import type { BncrConnection, OutboxEntry } from './types.ts';
+import {
+  buildPushBroadcastPayload,
+  buildPushOkArgs,
+  buildPushRouteSelectArgs,
+} from './outbox-push-args.ts';
+
+export function buildTextPushBroadcastPayload(args: {
+  payload: Record<string, unknown>;
+  messageId: string;
+}) {
+  return buildPushBroadcastPayload({
+    payload: args.payload,
+    messageId: args.messageId,
+  });
+}
+
+export function buildTextPushRouteSelectArgs(args: {
+  entry: OutboxEntry;
+  connIds: Iterable<string>;
+  routeReason: string;
+  recentInboundReachable: boolean;
+  owner: BncrConnection | null;
+  event: string;
+}) {
+  return buildPushRouteSelectArgs({
+    entry: args.entry,
+    connIds: args.connIds,
+    routeReason: args.routeReason,
+    recentInboundReachable: args.recentInboundReachable,
+    owner: args.owner,
+    event: args.event,
+  });
+}
+
+export function buildTextPushSuccessArgs(args: {
+  entry: OutboxEntry;
+  connIds: Iterable<string>;
+  ownerConnId?: string;
+  ownerClientId?: string;
+}) {
+  return {
+    entry: args.entry,
+    connIds: args.connIds,
+    ownerConnId: args.ownerConnId,
+    ownerClientId: args.ownerClientId,
+  };
+}
+
+export function buildTextPushOkArgs(args: {
+  entry: OutboxEntry;
+  connIds: Iterable<string>;
+  recentInboundReachable: boolean;
+  event: string;
+}) {
+  return buildPushOkArgs({
+    entry: args.entry,
+    connIds: args.connIds,
+    recentInboundReachable: args.recentInboundReachable,
+    event: args.event,
+  });
+}

package/src/core/policy.ts

@@ -25,3 +25,12 @@ export function resolveBncrChannelPolicy(channelCfg: any) {
     requireMention: asBoolean(channelCfg?.requireMention, false),
   };
 }
+
+export function resolveBncrConfigWarnings(channelCfg: any): string[] {
+  const policy = resolveBncrChannelPolicy(channelCfg || {});
+  const warnings: string[] = [];
+  if (policy.requireMention) {
+    warnings.push('requireMention configured but not enforced yet');
+  }
+  return warnings;
+}

package/src/core/register-trace.ts

@@ -0,0 +1,115 @@
+const DEFAULT_REGISTER_WARMUP_WINDOW_MS = 30_000;
+
+function finiteNumberOr(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
+export type RegisterTraceEntry = {
+  ts: number;
+  bridgeId: string;
+  gatewayPid: number;
+  registerCount: number;
+  apiGeneration: number;
+  apiRebound: boolean;
+  apiInstanceId: string | null;
+  registryFingerprint: string | null;
+  source: string | null;
+  pluginVersion: string | null;
+  stack: string;
+  stackBucket: string;
+};
+
+export type RegisterTraceSummary = {
+  startupWindowMs: number;
+  traceWindowSize: number;
+  sourceBuckets: Record<string, number>;
+  dominantBucket: string | null;
+  warmupRegisterCount: number;
+  postWarmupRegisterCount: number;
+  unexpectedRegisterAfterWarmup: boolean;
+  lastUnexpectedRegisterAt: number | null;
+  likelyRuntimeRegistryDrift: boolean;
+  likelyStartupFanoutOnly: boolean;
+};
+
+export function classifyRegisterTrace(stack: string) {
+  if (
+    stack.includes('prepareSecretsRuntimeSnapshot') ||
+    stack.includes('resolveRuntimeWebTools') ||
+    stack.includes('resolvePluginWebSearchProviders')
+  ) {
+    return 'runtime/webtools';
+  }
+  if (stack.includes('startGatewayServer') || stack.includes('loadGatewayPlugins')) {
+    return 'gateway/startup';
+  }
+  if (stack.includes('resolvePluginImplicitProviders')) {
+    return 'provider/discovery/implicit';
+  }
+  if (stack.includes('resolvePluginDiscoveryProviders')) {
+    return 'provider/discovery/discovery';
+  }
+  if (stack.includes('resolvePluginProviders')) {
+    return 'provider/discovery/providers';
+  }
+  return 'other';
+}
+
+export function dominantRegisterBucket(sourceBuckets: Record<string, number>) {
+  let winner: string | null = null;
+  let winnerCount = -1;
+  for (const [bucket, count] of Object.entries(sourceBuckets)) {
+    if (count > winnerCount) {
+      winner = bucket;
+      winnerCount = count;
+    }
+  }
+  return winner;
+}
+
+export function buildRegisterTraceSummary(args: {
+  traceRecent: RegisterTraceEntry[];
+  firstRegisterAt: number | null;
+  warmupWindowMs?: number;
+}): RegisterTraceSummary {
+  const warmupWindowMs = Math.max(
+    0,
+    finiteNumberOr(args.warmupWindowMs, DEFAULT_REGISTER_WARMUP_WINDOW_MS),
+  );
+  const buckets: Record<string, number> = {};
+  let warmupCount = 0;
+  let postWarmupCount = 0;
+  let unexpectedRegisterAfterWarmup = false;
+  let lastUnexpectedRegisterAt: number | null = null;
+  const baseline = args.firstRegisterAt;
+
+  for (const trace of args.traceRecent) {
+    buckets[trace.stackBucket] = (buckets[trace.stackBucket] || 0) + 1;
+    const isWarmup = baseline != null && trace.ts - baseline <= warmupWindowMs;
+    if (isWarmup) {
+      warmupCount += 1;
+    } else {
+      postWarmupCount += 1;
+      unexpectedRegisterAfterWarmup = true;
+      lastUnexpectedRegisterAt = trace.ts;
+    }
+  }
+
+  const dominantBucket = dominantRegisterBucket(buckets);
+  const likelyRuntimeRegistryDrift = postWarmupCount > 0;
+  const likelyStartupFanoutOnly = warmupCount > 0 && postWarmupCount === 0;
+
+  return {
+    startupWindowMs: warmupWindowMs,
+    traceWindowSize: args.traceRecent.length,
+    sourceBuckets: buckets,
+    dominantBucket,
+    warmupRegisterCount: warmupCount,
+    postWarmupRegisterCount: postWarmupCount,
+    unexpectedRegisterAfterWarmup,
+    lastUnexpectedRegisterAt,
+    likelyRuntimeRegistryDrift,
+    likelyStartupFanoutOnly,
+  };
+}

package/src/core/status.ts

@@ -30,6 +30,11 @@ function now() {
   return Date.now();
 }
 
+function finiteNumberOr(value: unknown, fallback: number): number {
+  const n = Number(value);
+  return Number.isFinite(n) ? n : fallback;
+}
+
 function fmtAgo(ts?: number | null): string {
   if (!ts || !Number.isFinite(ts) || ts <= 0) return '-';
   const diff = Math.max(0, now() - ts);
@@ -142,6 +147,58 @@ export function buildAccountRuntimeSnapshot(input: RuntimeStatusInput) {
   };
 }
 
+export function buildAccountStatusSnapshot(input: {
+  account: { accountId: string; name?: string; enabled?: boolean };
+  runtime: any;
+  healthSummary: string;
+  displayName: string;
+}) {
+  const rt = input.runtime || {};
+  const meta = rt?.meta || {};
+
+  const pending = finiteNumberOr(rt?.pending ?? meta.pending, 0);
+  const deadLetter = finiteNumberOr(rt?.deadLetter ?? meta.deadLetter, 0);
+  const lastSessionKey = rt?.lastSessionKey ?? meta.lastSessionKey ?? null;
+  const lastSessionScope = rt?.lastSessionScope ?? meta.lastSessionScope ?? null;
+  const lastSessionAt = rt?.lastSessionAt ?? meta.lastSessionAt ?? null;
+  const lastSessionAgo = rt?.lastSessionAgo ?? meta.lastSessionAgo ?? '-';
+  const lastActivityAt = rt?.lastActivityAt ?? meta.lastActivityAt ?? null;
+  const lastActivityAgo = rt?.lastActivityAgo ?? meta.lastActivityAgo ?? '-';
+  const lastInboundAt = rt?.lastInboundAt ?? meta.lastInboundAt ?? null;
+  const lastInboundAgo = rt?.lastInboundAgo ?? meta.lastInboundAgo ?? '-';
+  const lastOutboundAt = rt?.lastOutboundAt ?? meta.lastOutboundAt ?? null;
+  const lastOutboundAgo = rt?.lastOutboundAgo ?? meta.lastOutboundAgo ?? '-';
+  const diagnostics = rt?.diagnostics ?? meta.diagnostics ?? null;
+  const normalizedMode = rt?.mode === 'linked' ? 'linked' : 'Status';
+
+  return {
+    accountId: input.account.accountId,
+    name: input.displayName,
+    enabled: input.account.enabled !== false,
+    configured: true,
+    linked: Boolean(rt?.connected),
+    running: rt?.running ?? false,
+    connected: rt?.connected ?? false,
+    lastEventAt: rt?.lastEventAt ?? null,
+    lastError: rt?.lastError ?? null,
+    mode: normalizedMode,
+    pending,
+    deadLetter,
+    healthSummary: input.healthSummary,
+    lastSessionKey,
+    lastSessionScope,
+    lastSessionAt,
+    lastSessionAgo,
+    lastActivityAt,
+    lastActivityAgo,
+    lastInboundAt,
+    lastInboundAgo,
+    lastOutboundAt,
+    lastOutboundAgo,
+    diagnostics,
+  };
+}
+
 export function buildChannelSummaryFromRuntime(input: RuntimeStatusInput) {
   const headline = buildStatusHeadlineFromRuntime(input);
   return {

package/src/core/types.ts

@@ -52,6 +52,7 @@ export type OutboxEntry = {
   routeAttemptConnIds?: string[];
   routeAttemptRound?: number;
   fastReroutePending?: boolean;
+  awaitingRetryPush?: boolean;
 };
 
 export type BncrDiagnosticsSummary = {