@xmoxmo/bncr 0.3.5 → 0.3.7

package/src/core/probe.ts

@@ -1,18 +1,4 @@
-function finiteNumberOr(value: unknown, fallback: number): number {
-  if (value == null) return fallback;
-  const n = Number(value);
-  return Number.isFinite(n) ? n : fallback;
-}
-
-function finiteNumberOrNull(value: unknown): number | null {
-  if (value == null) return null;
-  const n = Number(value);
-  return Number.isFinite(n) ? n : null;
-}
-
-function nonNegativeFiniteNumberOr(value: unknown, fallback: number): number {
-  return Math.max(0, finiteNumberOr(value, fallback));
-}
+import { finiteNumberOrNull, nonNegativeFiniteNumberOr } from './value-sanitize.ts';
 
 export function probeBncrAccount(params: {
   accountId: string;
@@ -64,3 +50,5 @@ export function probeBncrAccount(params: {
     },
   };
 }
+
+export type BncrAccountProbe = ReturnType<typeof probeBncrAccount>;

package/src/core/register-trace.ts

@@ -35,9 +35,9 @@ export type RegisterTraceSummary = {
 
 export type RegisterDriftSnapshot = {
   capturedAt: number;
-  registerCount: number;
-  apiGeneration: number;
-  postWarmupRegisterCount: number;
+  registerCount: number | null;
+  apiGeneration: number | null;
+  postWarmupRegisterCount: number | null;
   apiInstanceId: string | null;
   registryFingerprint: string | null;
   dominantBucket: string | null;

package/src/core/status.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { buildRuntimeStatusMetaDisplay } from './status-meta.ts';
-import type { BncrDiagnosticsSummary, PendingAdmission } from './types.ts';
+import type { BncrDiagnosticsSummary, BncrRuntimeLastSession, PendingAdmission } from './types.ts';
 
 type RuntimeStatusInput = {
   accountId: string;
@@ -15,7 +15,7 @@ type RuntimeStatusInput = {
   ackEvents: number;
   startedAt: number;
   pendingAdmissions?: PendingAdmission[];
-  lastSession?: { sessionKey: string; scope: string; updatedAt: number } | null;
+  lastSession?: BncrRuntimeLastSession | null;
   lastActivityAt?: number | null;
   lastInboundAt?: number | null;
   lastOutboundAt?: number | null;
@@ -140,9 +140,48 @@ export function buildAccountRuntimeSnapshot(input: RuntimeStatusInput) {
   };
 }
 
+export type BncrAccountRuntimeSnapshot = ReturnType<typeof buildAccountRuntimeSnapshot>;
+
 export function buildAccountStatusSnapshot(input: {
   account: { accountId: string; name?: string; enabled?: boolean };
-  runtime: any;
+  runtime:
+    | {
+        connected?: boolean;
+        running?: boolean;
+        mode?: string;
+        pending?: number | null;
+        deadLetter?: number | null;
+        lastEventAt?: number | null;
+        lastError?: string | null;
+        lastSessionKey?: string | null;
+        lastSessionScope?: string | null;
+        lastSessionAt?: number | null;
+        lastActivityAt?: number | null;
+        lastInboundAt?: number | null;
+        lastOutboundAt?: number | null;
+        lastSessionAgo?: string | null;
+        lastActivityAgo?: string | null;
+        lastInboundAgo?: string | null;
+        lastOutboundAgo?: string | null;
+        diagnostics?: BncrDiagnosticsSummary | Record<string, unknown> | null;
+        meta?: {
+          pending?: number | null;
+          deadLetter?: number | null;
+          lastSessionKey?: string | null;
+          lastSessionScope?: string | null;
+          lastSessionAt?: number | null;
+          lastActivityAt?: number | null;
+          lastInboundAt?: number | null;
+          lastOutboundAt?: number | null;
+          lastSessionAgo?: string | null;
+          lastActivityAgo?: string | null;
+          lastInboundAgo?: string | null;
+          lastOutboundAgo?: string | null;
+          diagnostics?: BncrDiagnosticsSummary | Record<string, unknown> | null;
+        } | null;
+      }
+    | null
+    | undefined;
   healthSummary: string;
   displayName: string;
 }) {
@@ -162,7 +201,7 @@ export function buildAccountStatusSnapshot(input: {
   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';
+  const normalizedMode = rt?.mode === 'linked' ? 'linked' : 'configured';
 
   return {
     accountId: input.account.accountId,

package/src/core/targets.ts

@@ -1,6 +1,14 @@
 import type { BncrRoute } from './types.ts';
 
+type RouteInputLike = {
+  platform?: unknown;
+  groupId?: unknown;
+  userId?: unknown;
+  route?: unknown;
+};
+
 export type BncrSessionKind = 'direct' | 'group';
+
 export type BncrExplicitTarget = {
   raw: string;
   normalized: string;
@@ -20,22 +28,14 @@ export type BncrExplicitTarget = {
   groupId?: string;
 };
 
-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 };
+export function asTargetString(value: unknown, fallback = ''): string {
+  if (typeof value === 'string') return value;
+  if (value == null) return fallback;
+  return String(value);
 }
 
-function parseRouteFromStandardDisplayScope(scope: string): BncrRoute | null {
-  const parts = asString(scope).trim().split(':');
+export function parseRouteFromStandardDisplayScope(scope: string): BncrRoute | null {
+  const parts = asTargetString(scope).trim().split(':');
   if (parts.length === 2) {
     const [platform, userId] = parts;
     if (!platform || !userId) return null;
@@ -51,8 +51,8 @@ function parseRouteFromStandardDisplayScope(scope: string): BncrRoute | null {
   return null;
 }
 
-function normalizeDisplayScopePrefix(scope: string): string {
-  const raw = asString(scope).trim();
+export function normalizeDisplayScopePrefix(scope: string): string {
+  const raw = asTargetString(scope).trim();
   if (!raw) return '';
   if (raw.startsWith('Bncr:')) return raw;
   if (/^bncr[:-]/i.test(raw)) return raw;
@@ -60,108 +60,40 @@ function normalizeDisplayScopePrefix(scope: string): string {
   return `Bncr:${raw}`;
 }
 
-export function parseRouteFromDisplayScope(scope: string): BncrRoute | null {
-  const raw = normalizeDisplayScopePrefix(scope);
-  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 formatTargetDisplay(
-  input: BncrRoute | BncrExplicitTarget | null | undefined,
-): string {
-  if (!input) return '';
-  const route = parseRouteLike((input as any)?.route) || parseRouteLike(input);
-  if (!route) return '';
-  return formatDisplayScope(route);
+export function resolveCanonicalSessionKind(): BncrSessionKind {
+  return 'direct';
 }
 
-export function parseExplicitTarget(
-  input: string,
-  options?: { canonicalAgentId?: string | null },
-): BncrExplicitTarget | null {
-  const raw = asString(input).trim();
-  if (!raw) return null;
-
-  const canonicalAgentId = asString(options?.canonicalAgentId).trim() || undefined;
-  let route: BncrRoute | null = null;
-  let source: BncrExplicitTarget['source'] | null = null;
-
-  const strict = parseStrictBncrSessionKey(raw);
-  if (strict?.route) {
-    route = strict.route;
-    source = 'strict-session-key';
-  }
-
-  if (!route) {
-    const displayRoute = parseRouteFromDisplayScope(raw);
-    if (displayRoute) {
-      route = displayRoute;
-      source = 'display-scope';
-    }
-  }
-
-  if (!route) {
-    const legacy = parseLegacySessionKey(raw);
-    if (legacy?.route) {
-      route = legacy.route;
-      source = legacy.source === 'hex' ? 'hex-scope' : 'legacy-session-key';
-    }
-  }
-
-  if (!route) {
-    const hexRoute = parseRouteFromHexScope(raw);
-    if (hexRoute) {
-      route = hexRoute;
-      source = 'hex-scope';
-    }
-  }
-
-  if (!route) {
-    const scopedRoute = parseRouteFromScope(raw);
-    if (scopedRoute) {
-      route = scopedRoute;
-      source = 'route-scope';
-    }
-  }
-
-  if (!route || !source) return null;
-
-  const kind: BncrSessionKind = route.groupId === '0' ? 'direct' : 'group';
-  const displayScope = formatDisplayScope(route);
+export function buildExplicitTargetResult(args: {
+  raw: string;
+  source:
+    | 'display-scope'
+    | 'strict-session-key'
+    | 'legacy-session-key'
+    | 'hex-scope'
+    | 'route-scope';
+  route: BncrRoute;
+  displayScope: string;
+  canonicalSessionKey?: string;
+}) {
+  const kind: BncrSessionKind = args.route.groupId === '0' ? 'direct' : 'group';
   return {
-    raw,
-    normalized: displayScope,
-    source,
+    raw: args.raw,
+    normalized: args.displayScope,
+    source: args.source,
     kind,
-    chatType: 'direct',
-    displayScope,
-    route,
-    ...(canonicalAgentId
-      ? { canonicalSessionKey: buildCanonicalBncrSessionKey(route, canonicalAgentId) }
-      : {}),
-    platform: route.platform,
-    userId: route.userId,
-    ...(route.groupId === '0' ? {} : { groupId: route.groupId }),
+    chatType: 'direct' as const,
+    displayScope: args.displayScope,
+    route: args.route,
+    ...(args.canonicalSessionKey ? { canonicalSessionKey: args.canonicalSessionKey } : {}),
+    platform: args.route.platform,
+    userId: args.route.userId,
+    ...(args.route.groupId === '0' ? {} : { groupId: args.route.groupId }),
   };
 }
 
 export function isLowerHex(input: string): boolean {
-  const raw = asString(input).trim();
+  const raw = asTargetString(input).trim();
   return !!raw && /^[0-9a-fA-F]+$/.test(raw) && raw.length % 2 === 0;
 }
 
@@ -170,8 +102,16 @@ export function routeScopeToHex(route: BncrRoute): string {
   return Buffer.from(raw, 'utf8').toString('hex').toLowerCase();
 }
 
+export function parseRouteFromScope(scope: string): BncrRoute | null {
+  const parts = asTargetString(scope).trim().split(':');
+  if (parts.length < 3) return null;
+  const [platform, groupId, userId] = parts;
+  if (!platform || !groupId || !userId) return null;
+  return { platform, groupId, userId };
+}
+
 export function parseRouteFromHexScope(scopeHex: string): BncrRoute | null {
-  const rawHex = asString(scopeHex).trim();
+  const rawHex = asTargetString(scopeHex).trim();
   if (!isLowerHex(rawHex)) return null;
 
   try {
@@ -182,26 +122,42 @@ export function parseRouteFromHexScope(scopeHex: string): BncrRoute | 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 parseStrictBncrSessionKey(input: string): {
+  inputSessionKey: string;
+  inputAgentId: string;
+  inputKind: BncrSessionKind;
+  scopeHex: string;
+  route: BncrRoute;
+} | null {
+  const raw = asTargetString(input).trim();
+  if (!raw) return null;
 
-export function resolveCanonicalSessionKind(_input?: {
-  route?: BncrRoute | null;
-  scope?: string | null;
-  sessionKey?: string | null;
-}): BncrSessionKind {
-  return 'direct';
-}
+  const m = raw.match(/^agent:([^:]+):bncr:(direct|group):(.+)$/);
+  if (!m?.[1] || !m?.[2] || !m?.[3]) return null;
 
-export function buildCanonicalBncrSessionKey(route: BncrRoute, canonicalAgentId: string): string {
-  const agentId = asString(canonicalAgentId).trim() || 'main';
-  const kind = resolveCanonicalSessionKind({ route });
-  return `agent:${agentId}:bncr:${kind}:${routeScopeToHex(route)}`;
+  const inputAgentId = asTargetString(m[1]).trim();
+  const inputKind = m[2] as BncrSessionKind;
+  const payload = asTargetString(m[3]).trim();
+  let route: BncrRoute | null = null;
+  let scopeHex = '';
+
+  if (isLowerHex(payload)) {
+    scopeHex = payload.toLowerCase();
+    route = parseRouteFromHexScope(scopeHex);
+  } else {
+    route = parseRouteFromScope(payload);
+    if (route) scopeHex = routeScopeToHex(route);
+  }
+
+  if (!route || !scopeHex) return null;
+
+  return {
+    inputSessionKey: raw,
+    inputAgentId,
+    inputKind,
+    scopeHex,
+    route,
+  };
 }
 
 export function parseLegacySessionKey(input: string): {
@@ -210,7 +166,7 @@ export function parseLegacySessionKey(input: string): {
   inputAgentId?: string;
   source: 'legacy-direct' | 'legacy-bncr' | 'legacy-agent' | 'hex';
 } | null {
-  const raw = asString(input).trim();
+  const raw = asTargetString(input).trim();
   if (!raw) return null;
 
   const directLegacy = raw.match(/^agent:([^:]+):bncr:direct:([0-9a-fA-F]+):0$/);
@@ -266,68 +222,36 @@ export function parseLegacySessionKey(input: string): {
 }
 
 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();
+  const platform = asTargetString(route.platform).trim().toLowerCase();
+  const groupId = asTargetString(route.groupId).trim().toLowerCase();
+  const userId = asTargetString(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): {
-  inputSessionKey: string;
-  inputAgentId: string;
-  inputKind: BncrSessionKind;
-  scopeHex: string;
-  route: BncrRoute;
-} | null {
-  const raw = asString(input).trim();
+export function parseRouteFromDisplayScope(scope: string): BncrRoute | null {
+  const raw = normalizeDisplayScopePrefix(scope);
   if (!raw) return null;
 
-  const m = raw.match(/^agent:([^:]+):bncr:(direct|group):(.+)$/);
-  if (!m?.[1] || !m?.[2] || !m?.[3]) return null;
-
-  const inputAgentId = asString(m[1]).trim();
-  const inputKind = m[2] as BncrSessionKind;
-  const payload = asString(m[3]).trim();
-  let route: BncrRoute | null = null;
-  let scopeHex = '';
-
-  if (isLowerHex(payload)) {
-    scopeHex = payload.toLowerCase();
-    route = parseRouteFromHexScope(scopeHex);
-  } else {
-    route = parseRouteFromScope(payload);
-    if (route) scopeHex = routeScopeToHex(route);
-  }
-
-  if (!route || !scopeHex) return null;
-
-  return {
-    inputSessionKey: raw,
-    inputAgentId,
-    inputKind,
-    scopeHex,
-    route,
-  };
+  const payload = raw.match(/^Bncr:(.+)$/)?.[1];
+  if (!payload) return null;
+  return parseRouteFromStandardDisplayScope(payload);
 }
 
-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 buildCanonicalBncrSessionKey(route: BncrRoute, canonicalAgentId: string): string {
+  const agentId = asTargetString(canonicalAgentId).trim() || 'main';
+  const kind = resolveCanonicalSessionKind();
+  return `agent:${agentId}:bncr:${kind}:${routeScopeToHex(route)}`;
 }
 
 export function normalizeStoredSessionKey(
   input: string,
   canonicalAgentId?: string | null,
+  helpers?: { normalizeTaskKey?: (input: unknown) => string | null },
 ): { sessionKey: string; route: BncrRoute } | null {
-  const raw = asString(input).trim();
+  const raw = asTargetString(input).trim();
   if (!raw) return null;
 
   let taskKey: string | null = null;
@@ -335,8 +259,8 @@ export function normalizeStoredSessionKey(
 
   const taskTagged = raw.match(/^(.*):task:([a-z0-9_-]{1,32})$/i);
   if (taskTagged) {
-    base = asString(taskTagged[1]).trim();
-    taskKey = normalizeTaskKey(taskTagged[2]);
+    base = asTargetString(taskTagged[1]).trim();
+    taskKey = helpers?.normalizeTaskKey?.(taskTagged[2]) || null;
   }
 
   let route: BncrRoute | null = null;
@@ -359,7 +283,7 @@ export function normalizeStoredSessionKey(
   if (!route) return null;
   if (isLegacyNoiseRoute(route)) return null;
 
-  const finalAgentId = asString(canonicalAgentId).trim() || passthroughAgentId;
+  const finalAgentId = asTargetString(canonicalAgentId).trim() || passthroughAgentId;
   if (!finalAgentId) return null;
 
   const finalSessionKey = buildCanonicalBncrSessionKey(route, finalAgentId);
@@ -374,51 +298,132 @@ export function normalizeInboundSessionKey(
   route: BncrRoute,
   canonicalAgentId: string,
 ): string | null {
-  const raw = asString(scope).trim();
+  const raw = asTargetString(scope).trim();
   let finalRoute: BncrRoute | null = null;
 
-  if (!raw) {
-    finalRoute = route;
+  if (!raw) finalRoute = route;
+  if (!finalRoute) finalRoute = parseStrictBncrSessionKey(raw)?.route || null;
+  if (!finalRoute) finalRoute = parseLegacySessionKey(raw)?.route || null;
+  if (!finalRoute) finalRoute = parseRouteFromDisplayScope(raw);
+  if (!finalRoute) finalRoute = parseRouteFromScope(raw);
+  if (!finalRoute && route) finalRoute = route;
+  if (!finalRoute) return null;
+
+  return buildCanonicalBncrSessionKey(finalRoute, canonicalAgentId);
+}
+
+export function buildFallbackSessionKey(route: BncrRoute, canonicalAgentId: string): string {
+  return buildCanonicalBncrSessionKey(route, canonicalAgentId);
+}
+
+export function parseRouteLike(input: unknown): BncrRoute | null {
+  const routeInput = input && typeof input === 'object' ? (input as RouteInputLike) : null;
+  const platform = asTargetString(routeInput?.platform || '').trim();
+  const groupId = asTargetString(routeInput?.groupId || '').trim();
+  const userId = asTargetString(routeInput?.userId || '').trim();
+  if (!platform || !groupId || !userId) return null;
+  return { platform, groupId, userId };
+}
+
+export type BncrExplicitTargetSource =
+  | 'display-scope'
+  | 'strict-session-key'
+  | 'legacy-session-key'
+  | 'hex-scope'
+  | 'route-scope';
+
+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) => asTargetString(x).trim()).filter(Boolean)));
+}
+
+export function resolveExplicitTargetRoute(raw: string): {
+  route: BncrRoute | null;
+  source: BncrExplicitTargetSource | null;
+} {
+  let route: BncrRoute | null = null;
+  let source: BncrExplicitTargetSource | null = null;
+
+  const strict = parseStrictBncrSessionKey(raw);
+  if (strict?.route) {
+    route = strict.route;
+    source = 'strict-session-key';
   }
 
-  if (!finalRoute) {
-    const strict = parseStrictBncrSessionKey(raw);
-    if (strict?.route) {
-      finalRoute = strict.route;
+  if (!route) {
+    const displayRoute = parseRouteFromDisplayScope(raw);
+    if (displayRoute) {
+      route = displayRoute;
+      source = 'display-scope';
     }
   }
 
-  if (!finalRoute) {
+  if (!route) {
     const legacy = parseLegacySessionKey(raw);
     if (legacy?.route) {
-      finalRoute = legacy.route;
+      route = legacy.route;
+      source = legacy.source === 'hex' ? 'hex-scope' : 'legacy-session-key';
     }
   }
 
-  if (!finalRoute) {
-    const displayRoute = parseRouteFromDisplayScope(raw);
-    if (displayRoute) {
-      finalRoute = displayRoute;
+  if (!route) {
+    const hexRoute = parseRouteFromHexScope(raw);
+    if (hexRoute) {
+      route = hexRoute;
+      source = 'hex-scope';
     }
   }
 
-  if (!finalRoute) {
+  if (!route) {
     const scopedRoute = parseRouteFromScope(raw);
     if (scopedRoute) {
-      finalRoute = scopedRoute;
+      route = scopedRoute;
+      source = 'route-scope';
     }
   }
 
-  if (!finalRoute && route) {
-    finalRoute = route;
-  }
+  return { route, source };
+}
 
-  if (!finalRoute) return null;
-  return buildCanonicalBncrSessionKey(finalRoute, canonicalAgentId);
+export function parseExplicitTarget(input: string, options?: { canonicalAgentId?: string | null }) {
+  const raw = asTargetString(input).trim();
+  if (!raw) return null;
+
+  const canonicalAgentId = asTargetString(options?.canonicalAgentId).trim() || undefined;
+  const { route, source } = resolveExplicitTargetRoute(raw);
+  if (!route || !source) return null;
+
+  const displayScope = formatDisplayScope(route);
+  return buildExplicitTargetResult({
+    raw,
+    source,
+    route,
+    displayScope,
+    ...(canonicalAgentId
+      ? { canonicalSessionKey: buildCanonicalBncrSessionKey(route, canonicalAgentId) }
+      : {}),
+  });
+}
+
+export function normalizeTaskKey(input: unknown): string | null {
+  const raw = asTargetString(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 extractInlineTaskKey(text: string): { taskKey: string | null; text: string } {
-  const raw = asString(text);
+  const raw = asTargetString(text);
   if (!raw) return { taskKey: null, text: '' };
 
   const tagged = raw.match(
@@ -427,7 +432,7 @@ export function extractInlineTaskKey(text: string): { taskKey: string | null; te
   if (tagged) {
     return {
       taskKey: normalizeTaskKey(tagged[1]),
-      text: asString(tagged[2]),
+      text: asTargetString(tagged[2]),
     };
   }
 
@@ -435,7 +440,7 @@ export function extractInlineTaskKey(text: string): { taskKey: string | null; te
   if (spaced) {
     return {
       taskKey: normalizeTaskKey(spaced[1]),
-      text: asString(spaced[2]),
+      text: asTargetString(spaced[2]),
     };
   }
 
@@ -443,15 +448,21 @@ export function extractInlineTaskKey(text: string): { taskKey: string | null; te
 }
 
 export function withTaskSessionKey(sessionKey: string, taskKey?: string | null): string {
-  const base = asString(sessionKey).trim();
+  const base = asTargetString(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, canonicalAgentId: string): string {
-  return buildCanonicalBncrSessionKey(route, canonicalAgentId);
+export function formatTargetDisplay(
+  input: BncrRoute | BncrExplicitTarget | null | undefined,
+): string {
+  if (!input) return '';
+  const routeInput = input && typeof input === 'object' ? (input as RouteInputLike) : null;
+  const route = parseRouteLike(routeInput?.route) || parseRouteLike(input);
+  if (!route) return '';
+  return formatDisplayScope(route);
 }
 
 export function routeKey(accountId: string, route: BncrRoute): string {