@xmoxmo/bncr 0.0.3 → 0.0.5

package/src/core/accounts.ts

@@ -0,0 +1,50 @@
+const CHANNEL_ID = 'bncr';
+const BNCR_DEFAULT_ACCOUNT_ID = 'Primary';
+
+function asString(v: unknown, fallback = ''): string {
+  if (typeof v === 'string') return v;
+  if (v == null) return fallback;
+  return String(v);
+}
+
+export function normalizeAccountId(accountId?: string | null): string {
+  const v = asString(accountId || '').trim();
+  if (!v) return BNCR_DEFAULT_ACCOUNT_ID;
+  const lower = v.toLowerCase();
+  if (lower === 'default' || lower === 'primary') return BNCR_DEFAULT_ACCOUNT_ID;
+  return v;
+}
+
+export function resolveDefaultDisplayName(rawName: unknown, accountId: string): string {
+  const raw = asString(rawName || '').trim();
+  if (!raw || raw === accountId || /^bncr$/i.test(raw) || /^status$/i.test(raw) || /^runtime$/i.test(raw)) {
+    return 'Monitor';
+  }
+  return raw;
+}
+
+export function resolveAccount(cfg: any, accountId?: string | null) {
+  const accounts = cfg?.channels?.[CHANNEL_ID]?.accounts || {};
+  let key = normalizeAccountId(accountId);
+
+  if (!accounts[key]) {
+    const first = Object.keys(accounts)[0];
+    if (first) key = first;
+  }
+
+  const account = accounts[key] || {};
+  const displayName = resolveDefaultDisplayName(account?.name, key);
+
+  return {
+    accountId: key,
+    name: displayName,
+    enabled: account?.enabled !== false,
+  };
+}
+
+export function listAccountIds(cfg: any): string[] {
+  const ids = Object.keys(cfg?.channels?.[CHANNEL_ID]?.accounts || {});
+  return ids.length ? ids : [BNCR_DEFAULT_ACCOUNT_ID];
+}
+
+export { CHANNEL_ID, BNCR_DEFAULT_ACCOUNT_ID };

package/src/core/config-schema.ts

@@ -0,0 +1,42 @@
+export const BncrConfigSchema = {
+  schema: {
+    type: 'object',
+    additionalProperties: true,
+    properties: {
+      enabled: { type: 'boolean' },
+      dmPolicy: {
+        type: 'string',
+        enum: ['open', 'allowlist', 'disabled'],
+      },
+      groupPolicy: {
+        type: 'string',
+        enum: ['open', 'allowlist', 'disabled'],
+      },
+      allowFrom: {
+        type: 'array',
+        items: { type: 'string' },
+      },
+      groupAllowFrom: {
+        type: 'array',
+        items: { type: 'string' },
+      },
+      requireMention: {
+        type: 'boolean',
+        default: false,
+        description:
+          'Whether group messages must explicitly mention the bot before bncr handles them. Default false. Current version keeps this as a reserved field and does not enforce it yet.',
+      },
+      accounts: {
+        type: 'object',
+        additionalProperties: {
+          type: 'object',
+          additionalProperties: true,
+          properties: {
+            enabled: { type: 'boolean' },
+            name: { type: 'string' },
+          },
+        },
+      },
+    },
+  },
+};

package/src/core/permissions.ts

@@ -0,0 +1,29 @@
+function asString(v: unknown, fallback = ''): string {
+  if (typeof v === 'string') return v;
+  if (v == null) return fallback;
+  return String(v);
+}
+
+export function getBncrElevatedConfig(rootCfg: any) {
+  const elevated = rootCfg?.tools?.elevated || {};
+  const allowFrom = elevated?.allowFrom || {};
+  const bncrRules = Array.isArray(allowFrom?.bncr) ? allowFrom.bncr.map((x: unknown) => asString(x).trim()).filter(Boolean) : [];
+
+  return {
+    enabled: elevated?.enabled === true,
+    bncrAllowed: bncrRules.length > 0,
+    bncrRules,
+  };
+}
+
+export function buildBncrPermissionSummary(rootCfg: any) {
+  const elevated = getBncrElevatedConfig(rootCfg);
+  return {
+    elevatedEnabled: elevated.enabled,
+    bncrElevatedAllowed: elevated.bncrAllowed,
+    bncrElevatedRules: elevated.bncrRules,
+    note: elevated.bncrAllowed
+      ? 'bncr can request elevated operations; final execution may still be gated by approvals policy'
+      : 'bncr elevated not explicitly allowed',
+  };
+}

package/src/core/policy.ts

@@ -0,0 +1,27 @@
+function asString(v: unknown, fallback = ''): string {
+  if (typeof v === 'string') return v;
+  if (v == null) return fallback;
+  return String(v);
+}
+
+function asList(v: unknown): string[] {
+  if (!Array.isArray(v)) return [];
+  return v.map((x) => asString(x).trim()).filter(Boolean);
+}
+
+function asBoolean(v: unknown, fallback = false): boolean {
+  if (typeof v === 'boolean') return v;
+  if (v == null) return fallback;
+  return String(v).trim().toLowerCase() === 'true';
+}
+
+export function resolveBncrChannelPolicy(channelCfg: any) {
+  return {
+    enabled: channelCfg?.enabled !== false,
+    dmPolicy: asString(channelCfg?.dmPolicy || 'open').toLowerCase(),
+    groupPolicy: asString(channelCfg?.groupPolicy || 'open').toLowerCase(),
+    allowFrom: asList(channelCfg?.allowFrom),
+    groupAllowFrom: asList(channelCfg?.groupAllowFrom),
+    requireMention: asBoolean(channelCfg?.requireMention, false),
+  };
+}

package/src/core/probe.ts

@@ -0,0 +1,45 @@
+export function probeBncrAccount(params: {
+  accountId: string;
+  connected: boolean;
+  pending: number;
+  deadLetter: number;
+  activeConnections: number;
+  invalidOutboxSessionKeys: number;
+  legacyAccountResidue: number;
+  lastActivityAt?: number | null;
+  structure?: {
+    coreComplete: boolean;
+    inboundComplete: boolean;
+    outboundComplete: boolean;
+  };
+}) {
+  const issues: string[] = [];
+
+  if (!params.connected) issues.push('not-connected');
+  if (params.pending > 20) issues.push('pending-high');
+  if (params.deadLetter > 0) issues.push('dead-letter');
+  if (params.activeConnections > 3) issues.push('too-many-connections');
+  if (params.invalidOutboxSessionKeys > 0) issues.push('invalid-session-keys');
+  if (params.legacyAccountResidue > 0) issues.push('legacy-account-residue');
+
+  let level: 'ok' | 'warn' | 'error' = 'ok';
+  if (issues.length > 0) level = 'warn';
+  if (!params.connected && (params.deadLetter > 0 || params.invalidOutboxSessionKeys > 0)) level = 'error';
+
+  return {
+    ok: level === 'ok',
+    level,
+    summary: issues.length ? issues.join(', ') : 'healthy',
+    details: {
+      accountId: params.accountId,
+      connected: params.connected,
+      pending: params.pending,
+      deadLetter: params.deadLetter,
+      activeConnections: params.activeConnections,
+      invalidOutboxSessionKeys: params.invalidOutboxSessionKeys,
+      legacyAccountResidue: params.legacyAccountResidue,
+      lastActivityAt: params.lastActivityAt ?? null,
+      structure: params.structure ?? null,
+    },
+  };
+}

package/src/core/status.ts

@@ -0,0 +1,145 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import type { BncrDiagnosticsSummary, PendingAdmission } from './types.js';
+
+type RuntimeStatusInput = {
+  accountId: string;
+  connected: boolean;
+  pending: number;
+  deadLetter: number;
+  activeConnections: number;
+  connectEvents: number;
+  inboundEvents: number;
+  activityEvents: number;
+  ackEvents: number;
+  startedAt: number;
+  pendingAdmissions?: PendingAdmission[];
+  lastSession?: { sessionKey: string; scope: string; updatedAt: number } | null;
+  lastActivityAt?: number | null;
+  lastInboundAt?: number | null;
+  lastOutboundAt?: number | null;
+  sessionRoutesCount: number;
+  invalidOutboxSessionKeys: number;
+  legacyAccountResidue: number;
+  running?: boolean;
+  lastError?: string | null;
+  channelRoot?: string;
+};
+
+function now() {
+  return Date.now();
+}
+
+function fmtAgo(ts?: number | null): string {
+  if (!ts || !Number.isFinite(ts) || ts <= 0) return '-';
+  const diff = Math.max(0, now() - ts);
+  if (diff < 1_000) return 'just now';
+  if (diff < 60_000) return `${Math.floor(diff / 1_000)}s ago`;
+  if (diff < 3_600_000) return `${Math.floor(diff / 60_000)}m ago`;
+  if (diff < 86_400_000) return `${Math.floor(diff / 3_600_000)}h ago`;
+  return `${Math.floor(diff / 86_400_000)}d ago`;
+}
+
+export function buildIntegratedDiagnostics(input: RuntimeStatusInput): BncrDiagnosticsSummary {
+  const root = input.channelRoot || path.join(process.cwd(), 'plugins', 'bncr');
+  const pluginIndexExists = fs.existsSync(path.join(root, 'index.ts'));
+  const pluginChannelExists = fs.existsSync(path.join(root, 'src', 'channel.ts'));
+
+  return {
+    health: {
+      connected: input.connected,
+      pending: input.pending,
+      pendingAdmissions: Array.isArray(input.pendingAdmissions) ? input.pendingAdmissions.length : 0,
+      deadLetter: input.deadLetter,
+      activeConnections: input.activeConnections,
+      connectEvents: input.connectEvents,
+      inboundEvents: input.inboundEvents,
+      activityEvents: input.activityEvents,
+      ackEvents: input.ackEvents,
+      uptimeSec: Math.floor((now() - input.startedAt) / 1000),
+    },
+    regression: {
+      pluginFilesPresent: pluginIndexExists && pluginChannelExists,
+      pluginIndexExists,
+      pluginChannelExists,
+      totalKnownRoutes: input.sessionRoutesCount,
+      invalidOutboxSessionKeys: input.invalidOutboxSessionKeys,
+      legacyAccountResidue: input.legacyAccountResidue,
+      ok: input.invalidOutboxSessionKeys === 0 && input.legacyAccountResidue === 0,
+    },
+  };
+}
+
+export function buildStatusHeadlineFromRuntime(input: RuntimeStatusInput): string {
+  const diag = buildIntegratedDiagnostics(input);
+  const h = diag.health;
+  const r = diag.regression;
+
+  const parts = [
+    r.ok ? 'diag:ok' : 'diag:warn',
+    `p:${h.pending}`,
+    `d:${h.deadLetter}`,
+    `c:${h.activeConnections}`,
+  ];
+
+  if (!r.ok) {
+    if (r.invalidOutboxSessionKeys > 0) parts.push(`invalid:${r.invalidOutboxSessionKeys}`);
+    if (r.legacyAccountResidue > 0) parts.push(`legacy:${r.legacyAccountResidue}`);
+  }
+
+  return parts.join(' ');
+}
+
+export function buildStatusMetaFromRuntime(input: RuntimeStatusInput) {
+  const diagnostics = buildIntegratedDiagnostics(input);
+  return {
+    pending: input.pending,
+    pendingAdmissionsCount: Array.isArray(input.pendingAdmissions) ? input.pendingAdmissions.length : 0,
+    pendingAdmissions: Array.isArray(input.pendingAdmissions)
+      ? input.pendingAdmissions.map((item) => ({
+          clientId: item.clientId,
+          scope: item.route ? `${item.route.platform}:${item.route.groupId}:${item.route.userId}` : null,
+          scopes: Array.isArray(item.routes)
+            ? item.routes.map((route) => `${route.platform}:${route.groupId}:${route.userId}`)
+            : [],
+          firstSeenAt: item.firstSeenAt,
+          lastSeenAt: item.lastSeenAt,
+          attempts: item.attempts,
+        }))
+      : [],
+    deadLetter: input.deadLetter,
+    lastSessionScope: input.lastSession?.scope || null,
+    lastSessionAt: input.lastSession?.updatedAt || null,
+    lastSessionAgo: fmtAgo(input.lastSession?.updatedAt || null),
+    lastActivityAt: input.lastActivityAt || null,
+    lastActivityAgo: fmtAgo(input.lastActivityAt || null),
+    lastInboundAt: input.lastInboundAt || null,
+    lastInboundAgo: fmtAgo(input.lastInboundAt || null),
+    lastOutboundAt: input.lastOutboundAt || null,
+    lastOutboundAgo: fmtAgo(input.lastOutboundAt || null),
+    diagnostics,
+  };
+}
+
+export function buildAccountRuntimeSnapshot(input: RuntimeStatusInput) {
+  return {
+    accountId: input.accountId,
+    running: input.running ?? true,
+    connected: input.connected,
+    linked: input.connected,
+    lastEventAt: input.lastActivityAt || null,
+    lastInboundAt: input.lastInboundAt || null,
+    lastOutboundAt: input.lastOutboundAt || null,
+    mode: input.connected ? 'linked' : 'configured',
+    lastError: input.lastError ?? null,
+    meta: buildStatusMetaFromRuntime(input),
+  };
+}
+
+export function buildChannelSummaryFromRuntime(input: RuntimeStatusInput) {
+  const headline = buildStatusHeadlineFromRuntime(input);
+  return {
+    linked: input.connected,
+    self: { e164: headline },
+  };
+}

package/src/core/targets.ts

@@ -0,0 +1,243 @@
+import type { BncrRoute } from './types.js';
+
+const BNCR_SESSION_KEY_PREFIX = 'agent:main:bncr:direct:';
+
+function asString(v: unknown, fallback = ''): string {
+  if (typeof v === 'string') return v;
+  if (v == null) return fallback;
+  return String(v);
+}
+
+export function parseRouteFromScope(scope: string): BncrRoute | null {
+  const parts = asString(scope).trim().split(':');
+  if (parts.length < 3) return null;
+  const [platform, groupId, userId] = parts;
+  if (!platform || !groupId || !userId) return null;
+  return { platform, groupId, userId };
+}
+
+function parseRouteFromStandardDisplayScope(scope: string): BncrRoute | null {
+  const parts = asString(scope).trim().split(':');
+  if (parts.length === 2) {
+    const [platform, userId] = parts;
+    if (!platform || !userId) return null;
+    return { platform, groupId: '0', userId };
+  }
+
+  if (parts.length === 3) {
+    const [platform, groupId, userId] = parts;
+    if (!platform || !groupId || !userId) return null;
+    return { platform, groupId, userId };
+  }
+
+  return null;
+}
+
+export function parseRouteFromDisplayScope(scope: string): BncrRoute | null {
+  const raw = asString(scope).trim();
+  if (!raw) return null;
+
+  const payload = raw.match(/^Bncr:(.+)$/)?.[1];
+  if (!payload) return null;
+  return parseRouteFromStandardDisplayScope(payload);
+}
+
+export function formatDisplayScope(route: BncrRoute): string {
+  if (route.groupId === '0' && route.userId !== '0') {
+    return `Bncr:${route.platform}:${route.userId}`;
+  }
+  return `Bncr:${route.platform}:${route.groupId}:${route.userId}`;
+}
+
+export function buildDisplayScopeCandidates(route: BncrRoute): string[] {
+  const candidates = [formatDisplayScope(route)].filter(Boolean);
+  return Array.from(new Set(candidates.map((x) => asString(x).trim()).filter(Boolean)));
+}
+
+export function isLowerHex(input: string): boolean {
+  const raw = asString(input).trim();
+  return !!raw && /^[0-9a-fA-F]+$/.test(raw) && raw.length % 2 === 0;
+}
+
+export function routeScopeToHex(route: BncrRoute): string {
+  const raw = `${route.platform}:${route.groupId}:${route.userId}`;
+  return Buffer.from(raw, 'utf8').toString('hex').toLowerCase();
+}
+
+export function parseRouteFromHexScope(scopeHex: string): BncrRoute | null {
+  const rawHex = asString(scopeHex).trim();
+  if (!isLowerHex(rawHex)) return null;
+
+  try {
+    const decoded = Buffer.from(rawHex, 'hex').toString('utf8');
+    return parseRouteFromScope(decoded);
+  } catch {
+    return null;
+  }
+}
+
+export function parseRouteLike(input: unknown): BncrRoute | null {
+  const platform = asString((input as any)?.platform || '').trim();
+  const groupId = asString((input as any)?.groupId || '').trim();
+  const userId = asString((input as any)?.userId || '').trim();
+  if (!platform || !groupId || !userId) return null;
+  return { platform, groupId, userId };
+}
+
+export function parseLegacySessionKeyToStrict(input: string): string | null {
+  const raw = asString(input).trim();
+  if (!raw) return null;
+
+  const directLegacy = raw.match(/^agent:main:bncr:direct:([0-9a-fA-F]+):0$/);
+  if (directLegacy?.[1]) {
+    const route = parseRouteFromHexScope(directLegacy[1].toLowerCase());
+    if (route) return buildFallbackSessionKey(route);
+  }
+
+  const bncrLegacy = raw.match(/^bncr:([0-9a-fA-F]+):0$/);
+  if (bncrLegacy?.[1]) {
+    const route = parseRouteFromHexScope(bncrLegacy[1].toLowerCase());
+    if (route) return buildFallbackSessionKey(route);
+  }
+
+  const agentLegacy = raw.match(/^agent:main:bncr:([0-9a-fA-F]+):0$/);
+  if (agentLegacy?.[1]) {
+    const route = parseRouteFromHexScope(agentLegacy[1].toLowerCase());
+    if (route) return buildFallbackSessionKey(route);
+  }
+
+  if (isLowerHex(raw.toLowerCase())) {
+    const route = parseRouteFromHexScope(raw.toLowerCase());
+    if (route) return buildFallbackSessionKey(route);
+  }
+
+  return null;
+}
+
+export function isLegacyNoiseRoute(route: BncrRoute): boolean {
+  const platform = asString(route.platform).trim().toLowerCase();
+  const groupId = asString(route.groupId).trim().toLowerCase();
+  const userId = asString(route.userId).trim().toLowerCase();
+
+  if (platform === 'agent' && groupId === 'main' && userId === 'bncr') return true;
+  if (platform === 'bncr' && userId === '0' && isLowerHex(groupId)) return true;
+  return false;
+}
+
+export function parseStrictBncrSessionKey(input: string): { sessionKey: string; scopeHex: string; route: BncrRoute } | null {
+  const raw = asString(input).trim();
+  if (!raw) return null;
+
+  const m = raw.match(/^agent:main:bncr:(direct|group):(.+)$/);
+  if (!m?.[1] || !m?.[2]) return null;
+
+  const payload = asString(m[2]).trim();
+  let route: BncrRoute | null = null;
+  let scopeHex = '';
+
+  if (isLowerHex(payload)) {
+    scopeHex = payload;
+    route = parseRouteFromHexScope(payload);
+  } else {
+    route = parseRouteFromScope(payload);
+    if (route) scopeHex = routeScopeToHex(route);
+  }
+
+  if (!route || !scopeHex) return null;
+
+  return {
+    sessionKey: `${BNCR_SESSION_KEY_PREFIX}${scopeHex}`,
+    scopeHex,
+    route,
+  };
+}
+
+export function normalizeTaskKey(input: unknown): string | null {
+  const raw = asString(input).trim().toLowerCase();
+  if (!raw) return null;
+  const normalized = raw.replace(/[^a-z0-9_-]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 32);
+  return normalized || null;
+}
+
+export function normalizeStoredSessionKey(input: string): { sessionKey: string; route: BncrRoute } | null {
+  const raw = asString(input).trim();
+  if (!raw) return null;
+
+  let taskKey: string | null = null;
+  let base = raw;
+
+  const taskTagged = raw.match(/^(.*):task:([a-z0-9_-]{1,32})$/i);
+  if (taskTagged) {
+    base = asString(taskTagged[1]).trim();
+    taskKey = normalizeTaskKey(taskTagged[2]);
+  }
+
+  const strict = parseStrictBncrSessionKey(base);
+  if (strict) {
+    if (isLegacyNoiseRoute(strict.route)) return null;
+    return {
+      sessionKey: taskKey ? `${strict.sessionKey}:task:${taskKey}` : strict.sessionKey,
+      route: strict.route,
+    };
+  }
+
+  const migrated = parseLegacySessionKeyToStrict(base);
+  if (!migrated) return null;
+
+  const parsed = parseStrictBncrSessionKey(migrated);
+  if (!parsed) return null;
+  if (isLegacyNoiseRoute(parsed.route)) return null;
+
+  return {
+    sessionKey: taskKey ? `${parsed.sessionKey}:task:${taskKey}` : parsed.sessionKey,
+    route: parsed.route,
+  };
+}
+
+export function normalizeInboundSessionKey(scope: string, route: BncrRoute): string | null {
+  const raw = asString(scope).trim();
+  if (!raw) return buildFallbackSessionKey(route);
+
+  const parsed = parseStrictBncrSessionKey(raw);
+  if (!parsed) return null;
+  return parsed.sessionKey;
+}
+
+export function extractInlineTaskKey(text: string): { taskKey: string | null; text: string } {
+  const raw = asString(text);
+  if (!raw) return { taskKey: null, text: '' };
+
+  const tagged = raw.match(/^\s*(?:#task|\/task)\s*[:=]\s*([a-zA-Z0-9_-]{1,32})\s*\n?\s*([\s\S]*)$/i);
+  if (tagged) {
+    return {
+      taskKey: normalizeTaskKey(tagged[1]),
+      text: asString(tagged[2]),
+    };
+  }
+
+  const spaced = raw.match(/^\s*\/task\s+([a-zA-Z0-9_-]{1,32})\s+([\s\S]*)$/i);
+  if (spaced) {
+    return {
+      taskKey: normalizeTaskKey(spaced[1]),
+      text: asString(spaced[2]),
+    };
+  }
+
+  return { taskKey: null, text: raw };
+}
+
+export function withTaskSessionKey(sessionKey: string, taskKey?: string | null): string {
+  const base = asString(sessionKey).trim();
+  const tk = normalizeTaskKey(taskKey);
+  if (!base || !tk) return base;
+  if (/:task:[a-z0-9_-]+(?:$|:)/i.test(base)) return base;
+  return `${base}:task:${tk}`;
+}
+
+export function buildFallbackSessionKey(route: BncrRoute): string {
+  return `${BNCR_SESSION_KEY_PREFIX}${routeScopeToHex(route)}`;
+}
+
+export function routeKey(accountId: string, route: BncrRoute): string {
+  return `${accountId}:${route.platform}:${route.groupId}:${route.userId}`.toLowerCase();
+}

package/src/core/types.ts

@@ -0,0 +1,59 @@
+export type BncrRoute = {
+  platform: string;
+  groupId: string;
+  userId: string;
+};
+
+export type BncrConnection = {
+  accountId: string;
+  connId: string;
+  clientId?: string;
+  connectedAt: number;
+  lastSeenAt: number;
+};
+
+export type PendingAdmission = {
+  clientId: string;
+  route: BncrRoute;
+  routes: BncrRoute[];
+  firstSeenAt: number;
+  lastSeenAt: number;
+  attempts: number;
+};
+
+export type OutboxEntry = {
+  messageId: string;
+  accountId: string;
+  sessionKey: string;
+  route: BncrRoute;
+  payload: Record<string, unknown>;
+  createdAt: number;
+  retryCount: number;
+  nextAttemptAt: number;
+  lastAttemptAt?: number;
+  lastError?: string;
+};
+
+export type BncrDiagnosticsSummary = {
+  health: {
+    connected: boolean;
+    pending: number;
+    pendingAdmissions: number;
+    deadLetter: number;
+    activeConnections: number;
+    connectEvents: number;
+    inboundEvents: number;
+    activityEvents: number;
+    ackEvents: number;
+    uptimeSec: number;
+  };
+  regression: {
+    pluginFilesPresent: boolean;
+    pluginIndexExists: boolean;
+    pluginChannelExists: boolean;
+    totalKnownRoutes: number;
+    invalidOutboxSessionKeys: number;
+    legacyAccountResidue: number;
+    ok: boolean;
+  };
+};