@xmoxmo/bncr 0.5.6 → 0.5.8

package/src/messaging/inbound/scene-admin.ts

@@ -21,7 +21,7 @@ export type BncrSceneAdminCommand =
   | { kind: 'history-force-set'; sceneKey: string; enabled: boolean | 'clear' }
   | { kind: 'history-help' }
   | { kind: 'download-media-get'; sceneKey?: string }
-  | { kind: 'download-media-set'; sceneKey: string; enabled: boolean }
+  | { kind: 'download-media-set'; sceneKey: string; enabled: boolean | undefined }
   | { kind: 'download-media-global-get' }
   | { kind: 'download-media-global-set'; enabled: boolean };
 
@@ -132,7 +132,7 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
           return {
             matched: true,
             valid: true,
-            command: { kind: 'mode', sceneKey: '', mode: 'clear' as any },
+            command: { kind: 'mode', sceneKey: '', mode: 'clear' },
           };
         }
         if (args[0] === 'help') {
@@ -159,7 +159,7 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
         return {
           matched: true,
           valid: true,
-          command: { kind: 'mode', sceneKey: args[1], mode: 'clear' as any },
+          command: { kind: 'mode', sceneKey: args[1], mode: 'clear' },
         };
       }
       if (GROUP_REPLY_MODES.has(args[0] as BncrGroupReplyMode) && args[1]) {
@@ -205,7 +205,7 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
           return {
             matched: true,
             valid: true,
-            command: { kind: 'history-limit-set', sceneKey: '', limit: 'clear' as any },
+            command: { kind: 'history-limit-set', sceneKey: '', limit: 'clear' },
           };
         }
         const num = parseInt(args[0], 10);
@@ -227,7 +227,7 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
           return {
             matched: true,
             valid: true,
-            command: { kind: 'history-limit-set', sceneKey: args[1], limit: 'clear' as any },
+            command: { kind: 'history-limit-set', sceneKey: args[1], limit: 'clear' },
           };
         }
         const num = parseInt(args[0], 10);
@@ -253,13 +253,13 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
           return {
             matched: true,
             valid: true,
-            command: { kind: 'history-force-set', sceneKey: '', enabled: 'clear' as any },
+            command: { kind: 'history-force-set', sceneKey: '', enabled: 'clear' },
           };
         }
         return {
           matched: true,
           valid: true,
-          command: { kind: 'history-force-set', sceneKey: args[1], enabled: 'clear' as any },
+          command: { kind: 'history-force-set', sceneKey: args[1], enabled: 'clear' },
         };
       }
       if (args[0] === 'on' || args[0] === 'off') {
@@ -302,7 +302,7 @@ export function parseSceneAdminCommand(command: NativeCommand): ParsedSceneAdmin
           command: {
             kind: 'download-media-set',
             sceneKey: args[1] || '',
-            enabled: undefined as any,
+            enabled: undefined,
           },
         };
       }

package/src/messaging/outbound/diagnostics-debug-builders.ts

@@ -348,18 +348,3 @@ export function buildPushFailureDebugInfo(args: {
       (typeof args.lastError === 'string' && args.lastError) || OUTBOUND_TERMINAL_REASON.PUSH_RETRY,
   };
 }
-
-export function buildReplyMediaFallbackDebugInfo(args: {
-  sessionKey: string;
-  mediaUrl: string;
-  replyToId: string;
-  fallback: { text: string; reason: string };
-}) {
-  return {
-    sessionKey: args.sessionKey,
-    mediaUrl: args.mediaUrl,
-    replyToId: args.replyToId || undefined,
-    fallbackText: args.fallback.text,
-    reason: args.fallback.reason,
-  };
-}

package/src/messaging/outbound/diagnostics.ts

@@ -5,6 +5,7 @@ import type {
   BncrOutboxQueueDiagnostics,
   OutboxEntry,
 } from '../../core/types.ts';
+import { finiteNumberOrNull } from '../../core/value-sanitize.ts';
 
 export {
   buildFlushDebugInfo,
@@ -16,7 +17,6 @@ export {
   buildOutboxRouteSelectDebugInfo,
   buildOutboxScheduleDebugInfo,
   buildPushFailureDebugInfo,
-  buildReplyMediaFallbackDebugInfo,
   buildRetryRerouteDebugInfo,
 } from './diagnostics-debug-builders.ts';
 
@@ -42,12 +42,6 @@ type OutboxIncidentSummaryInput = {
   nowMs?: number;
 };
 
-function finiteNumberOrNull(value: unknown): number | null {
-  if (value == null) return null;
-  const n = Number(value);
-  return Number.isFinite(n) ? n : null;
-}
-
 function positiveAgeMs(nowMs: number, at: unknown): number | null {
   const n = finiteNumberOrNull(at);
   if (n === null || n < 0) return null;

package/src/messaging/outbound/durable-queue-adapter.ts

@@ -8,7 +8,7 @@ export type BncrDurableQueuedReceipt = {
     platformMessageId: string;
     kind: 'text' | 'media' | 'voice' | 'unknown';
     index: number;
-    threadId?: string;
+    threadId?: string | number | null;
     replyToId?: string;
     raw: {
       channel: 'bncr';
@@ -20,7 +20,7 @@ export type BncrDurableQueuedReceipt = {
       meta: BncrDurableQueuedReceiptMeta;
     };
   }>;
-  threadId?: string;
+  threadId?: string | number | null;
   replyToId?: string;
   sentAt: number;
   raw: Array<{
@@ -66,8 +66,12 @@ export type BncrDurableQueuedResult = {
 };
 
 type OutboxPayload = OutboxEntry['payload'];
-type OutboxMeta = NonNullable<OutboxPayload['_meta']>;
-type OutboxMessagePayload = { type?: unknown };
+type OutboxMessagePayload = {
+  type?: unknown;
+  transferMode?: string;
+  asVoice?: boolean;
+  audioAsVoice?: boolean;
+};
 
 function getOutboxPayload(entry: OutboxEntry): OutboxPayload {
   return entry.payload;
@@ -76,7 +80,7 @@ function getOutboxPayload(entry: OutboxEntry): OutboxPayload {
 export function buildBncrDurableQueuedResult(args: {
   entry: OutboxEntry;
   index?: number;
-  threadId?: string;
+  threadId?: string | number | null;
   replyToId?: string;
   sentAt?: number;
 }): BncrDurableQueuedResult {
@@ -145,20 +149,22 @@ function extractPayloadType(entry: OutboxEntry): string | undefined {
 
 function extractReplyToId(entry: OutboxEntry): string | undefined {
   const payload = getOutboxPayload(entry);
-  const metaReply = (payload?._meta as OutboxMeta | undefined)?.replyToId;
-  const replyToId = payload?.replyToId ?? metaReply;
+  const message =
+    payload?.message && typeof payload.message === 'object' && !Array.isArray(payload.message)
+      ? (payload.message as Record<string, unknown>)
+      : null;
+  const replyToId = payload?.replyToId ?? (message?.replyToId as string | undefined);
   return typeof replyToId === 'string' ? replyToId : undefined;
 }
 
 function inferReceiptKind(entry: OutboxEntry): 'text' | 'media' | 'voice' | 'unknown' {
   const payload = getOutboxPayload(entry);
-  const meta = payload?._meta as OutboxMeta | undefined;
   const message =
-    payload.message && typeof payload.message === 'object'
+    payload?.message && typeof payload.message === 'object'
       ? (payload.message as OutboxMessagePayload)
       : null;
-  if (meta?.kind === 'file-transfer') {
-    if (meta.asVoice === true || meta.audioAsVoice === true) return 'voice';
+  if (message?.transferMode === 'media') {
+    if (message?.asVoice === true || message?.audioAsVoice === true) return 'voice';
     return 'media';
   }
   if (message?.type === 'text') return 'text';

package/src/messaging/outbound/marker-parser.ts

@@ -6,29 +6,35 @@
  *
  * Format: [BncrParam:{"key":"val","asVoice":true}]
  *
- * Incomplete markers (missing closing ]) are left in text unchanged.
- * Invalid JSON within a complete marker - marker is removed but no params.
+ * - Complete marker whose JSON parses successfully → stripped, params merged.
+ * - Complete marker whose JSON fails to parse → left in text (not stripped)
+ *   so the user can see and fix the bad payload.
+ * - Incomplete marker (no closing ]) → left in text, does NOT block later
+ *   complete markers.
+ * - Multiple valid markers → all stripped, params merge (later same-key wins).
+ * - When path/paths/mediaUrl/mediaUrls are present, probe for reachability.
+ *   Unreachable single paths keep the marker visible in the output text.
+ *   Unreachable entries in path arrays are dropped with warnings logged.
  */
 
-const PREFIX = '[BncrParam:';
+import fs from 'node:fs';
 
-export function parseBncrMarker(text: string): {
-  cleanText: string;
-  params: Record<string, unknown>;
-} {
-  const idx = text.indexOf(PREFIX);
-  if (idx === -1) return { cleanText: text, params: {} };
+const PREFIX = '[BncrParam:';
 
-  const start = idx + PREFIX.length;
-  if (start >= text.length) return { cleanText: text, params: {} };
+/**
+ * Locate the closing `]` of a complete marker starting at `prefixIdx`.
+ * Returns the index of the closing `]`, or -1 if incomplete.
+ */
+function findMarkerEnd(text: string, prefixIdx: number): number {
+  const start = prefixIdx + PREFIX.length;
+  if (start >= text.length) return -1;
 
   // Scan character-by-character tracking brace/bracket depth so that
-  // ] inside JSON values (e.g. CDATA content) is not mistaken for
+  // ] inside JSON values (e.g. CDATA / lyric tags) is not mistaken for
   // the closing marker bracket.
   let depth = 0;
   let inString = false;
   let esc = false;
-  let end = -1;
   let started = false;
 
   for (let i = start; i < text.length; i++) {
@@ -63,29 +69,62 @@ export function parseBncrMarker(text: string): {
         if (depth === 0) {
           // JSON content complete - expect ] to close the marker
           if (i + 1 < text.length && text[i + 1] === ']') {
-            end = i + 1;
+            return i + 1;
           }
-          break;
+          return -1;
         }
       }
     }
   }
 
-  if (end === -1) return { cleanText: text, params: {} };
+  return -1;
+}
 
-  const rawJson = text.slice(start, end);
-  let params: Record<string, unknown> = {};
+export function parseBncrMarker(text: string): {
+  cleanText: string;
+  params: Record<string, unknown>;
+} {
+  const params: Record<string, unknown> = {};
+  let result = text;
+  let searchFrom = 0;
 
-  try {
-    const parsed = JSON.parse(rawJson);
-    if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
-      params = parsed as Record<string, unknown>;
+  while (true) {
+    const idx = result.indexOf(PREFIX, searchFrom);
+    if (idx === -1) break;
+
+    const end = findMarkerEnd(result, idx);
+    if (end === -1) {
+      // Incomplete marker (missing ]): leave in place,
+      // keep looking after this PREFIX so later valid markers are not blocked.
+      searchFrom = idx + PREFIX.length;
+      continue;
+    }
+
+    const rawJson = result.slice(idx + PREFIX.length, end);
+    let parsedOk = false;
+    try {
+      const parsed = JSON.parse(rawJson);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        Object.assign(params, parsed as Record<string, unknown>);
+        parsedOk = true;
+      }
+    } catch {
+      // JSON parse failed — do NOT strip marker so the user can debug it
+    }
+
+    if (parsedOk) {
+      // Strip the complete valid marker
+      result = result.slice(0, idx) + result.slice(end + 1);
+      searchFrom = idx;
+    } else {
+      // Leave the invalid marker in place, continue after it
+      searchFrom = end + 1;
     }
-  } catch {
-    // Invalid JSON — remove marker but don't apply params
   }
 
-  const cleanText = (text.slice(0, idx) + text.slice(end + 1)).replace(/ {2,}/g, ' ').trim();
+  // Only trim whitespace when markers were actually stripped (result changed).
+  // Without markers the original text is returned as-is for maximum fidelity.
+  const cleanText = result !== text ? result.replace(/ {2,}/g, ' ').trim() : result;
   return { cleanText, params };
 }
 
@@ -103,6 +142,7 @@ const MEDIA_CONSUMPTION_TYPES = new Set(['file', 'image', 'video', 'audio', 'voi
  * based on whether its value is a recognized media type.
  */
 const CONSUMPTION_FIELDS_NO_TYPE = new Set([
+  'ismedia',
   'asVoice',
   'audioAsVoice',
   'kind',
@@ -110,8 +150,6 @@ const CONSUMPTION_FIELDS_NO_TYPE = new Set([
   'downloadMedia',
 ]);
 
-const CONSUMPTION_FIELDS = new Set([...CONSUMPTION_FIELDS_NO_TYPE]);
-
 export function extractConsumptionFields(extra: Record<string, unknown> | undefined): {
   consumed: Partial<{
     asVoice: boolean;
@@ -120,6 +158,7 @@ export function extractConsumptionFields(extra: Record<string, unknown> | undefi
     kind: string;
     replyToId: string;
     downloadMedia: boolean;
+    ismedia: boolean;
   }>;
   remaining: Record<string, unknown>;
 } {
@@ -140,7 +179,7 @@ export function extractConsumptionFields(extra: Record<string, unknown> | undefi
       }
       continue;
     }
-    if (CONSUMPTION_FIELDS.has(key)) {
+    if (CONSUMPTION_FIELDS_NO_TYPE.has(key)) {
       consumed[key] = value;
     } else {
       remaining[key] = value;
@@ -152,3 +191,213 @@ export function extractConsumptionFields(extra: Record<string, unknown> | undefi
     remaining,
   };
 }
+
+// ---------------------------------------------------------------------------
+// Media path probing
+// ---------------------------------------------------------------------------
+
+const PROBE_TIMEOUT_MS = 5_000;
+const MEDIA_PATH_KEYS = new Set(['path', 'paths', 'mediaUrl', 'mediaUrls']);
+
+function hasMediaPathParams(params: Record<string, unknown>): boolean {
+  for (const key of MEDIA_PATH_KEYS) {
+    if (key in params) return true;
+  }
+  return false;
+}
+
+/**
+ * Check whether a single media path (HTTP URL or local file) is reachable.
+ *
+ * - HTTP/HTTPS URLs → HEAD request with short timeout (5 s), follows redirects.
+ * - Local files → fs.existsSync.
+ *
+ * Returns `{ ok, reason }` where `reason` describes the failure when `ok` is false.
+ */
+async function probeMediaPath(raw: string): Promise<{
+  ok: boolean;
+  reason?: string;
+}> {
+  const path = String(raw || '').trim();
+  if (!path) return { ok: false, reason: 'empty path' };
+
+  // HTTP(S) URL — HEAD probe
+  if (path.startsWith('http://') || path.startsWith('https://')) {
+    try {
+      const controller = new AbortController();
+      const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
+      const response = await fetch(path, {
+        method: 'HEAD',
+        signal: controller.signal,
+        redirect: 'follow',
+      });
+      clearTimeout(timer);
+      if (response.ok || response.status === 206) return { ok: true };
+      return { ok: false, reason: `HTTP ${response.status} ${response.statusText}` };
+    } catch (err: unknown) {
+      const reason = err instanceof Error ? err.message : String(err);
+      return { ok: false, reason };
+    }
+  }
+
+  // Local file
+  try {
+    if (fs.existsSync(path)) return { ok: true };
+    return { ok: false, reason: 'file not found' };
+  } catch {
+    return { ok: false, reason: 'unreadable path' };
+  }
+}
+
+/**
+ * After JSON marker parsing, probe any media paths found in the params.
+ *
+ * - Single path (`path` / `mediaUrl`): if unreachable, keeps the marker in text
+ *   (returns allValid=false, warnings populated).
+ * - Path arrays (`paths` / `mediaUrls`): unreachable entries are removed; if at
+ *   least one entry is valid the marker is still stripped.  If ALL entries are
+ *   invalid the marker is kept.
+ *
+ * Returns `{ params, warnings, allValid }`:
+ * - `params` — (potentially filtered) params with invalid array entries removed.
+ * - `warnings` — human-readable warning strings for each unreachable path.
+ * - `allValid` — false when a single path or all array entries are unreachable.
+ */
+async function probeAndResolveMarkerPaths(params: Record<string, unknown>): Promise<{
+  params: Record<string, unknown>;
+  warnings: string[];
+  allValid: boolean;
+}> {
+  const warnings: string[] = [];
+  if (!hasMediaPathParams(params)) return { params, warnings, allValid: true };
+
+  // Single path / mediaUrl
+  const singlePath = String(params.path ?? params.mediaUrl ?? '').trim();
+  if (singlePath) {
+    const result = await probeMediaPath(singlePath);
+    if (!result.ok) {
+      warnings.push(`path ${singlePath} unreachable: ${result.reason}`);
+      return { params, warnings, allValid: false };
+    }
+    // Path confirmed reachable — signal downstream that media is validated
+    // Only set ismedia:true when user hasn't explicitly opted out.
+    if (!('ismedia' in params && params.ismedia === false)) {
+      params = { ...params, ismedia: true };
+    }
+    return { params, warnings, allValid: true };
+  }
+
+  // Path arrays — paths / mediaUrls
+  const arraySource = (params.paths ?? params.mediaUrls) as unknown;
+  if (Array.isArray(arraySource) && arraySource.length > 0) {
+    const entries = arraySource.filter(
+      (v): v is string => typeof v === 'string' && v.trim().length > 0,
+    );
+    if (entries.length === 0) return { params, warnings, allValid: true };
+
+    const results = await Promise.all(entries.map((p) => probeMediaPath(p)));
+    const valid: string[] = [];
+    for (let i = 0; i < entries.length; i++) {
+      if (results[i].ok) {
+        valid.push(entries[i]);
+      } else {
+        warnings.push(`path ${entries[i]} unreachable: ${results[i].reason}`);
+      }
+    }
+
+    if (valid.length === 0) {
+      // All invalid → keep marker
+      return { params, warnings, allValid: false };
+    }
+    // At least one valid → strip marker, replace with filtered entries.
+    // Only set ismedia=true when user hasn't explicitly opted out.
+    const setMedia = !('ismedia' in params && params.ismedia === false);
+    params = { ...params, ...(setMedia ? { ismedia: true } : {}), paths: valid, mediaUrls: valid };
+  }
+
+  return { params, warnings, allValid: true };
+}
+
+/**
+ * Parse text markers AND probe media paths in one async step.
+ *
+/**
+ * Unified marker strip decision: the single place that decides whether to strip
+ * a [BncrParam:...] marker from the text or leave it in place.
+ *
+ * - Markers that JSON parse successfully AND whose media paths (if any) are
+ *   reachable → stripped from text, params extracted and merged.
+ * - Markers whose paths are unreachable (single path OR all array entries) →
+ *   kept in text, NOT stripped, NOT extracted.
+ * - Markers without path fields → stripped as normal (existing behavior).
+ * - Markers that fail JSON parse → kept in text (existing behavior).
+ * - Multiple markers → each evaluated independently, later markers' params
+ *   overwrite earlier ones when the same key appears.
+ *
+ * This function IS the single decision point.  Downstream consumers of the
+ * returned text never re-parse markers — they trust the decision made here.
+ */
+export async function resolveMarkerStripDecision(text: string): Promise<{
+  cleanText: string;
+  params: Record<string, unknown>;
+  warnings: string[];
+}> {
+  const params: Record<string, unknown> = {};
+  const warnings: string[] = [];
+  let result = text;
+  let searchFrom = 0;
+  const hadMarkers = text.includes(PREFIX);
+
+  if (!hadMarkers) return { cleanText: text, params, warnings };
+
+  while (true) {
+    const idx = result.indexOf(PREFIX, searchFrom);
+    if (idx === -1) break;
+
+    const end = findMarkerEnd(result, idx);
+    if (end === -1) {
+      searchFrom = idx + PREFIX.length;
+      continue;
+    }
+
+    const rawJson = result.slice(idx + PREFIX.length, end);
+    let parsed: Record<string, unknown> | null = null;
+    try {
+      const obj = JSON.parse(rawJson);
+      if (obj && typeof obj === 'object' && !Array.isArray(obj)) {
+        parsed = obj as Record<string, unknown>;
+      }
+    } catch {
+      // JSON parse failed → keep marker in text, continue scanning after it
+      searchFrom = end + 1;
+      continue;
+    }
+
+    // JSON parsed but is not a plain object → keep marker in text
+    if (!parsed) {
+      searchFrom = end + 1;
+      continue;
+    }
+
+    // Marker has path fields → probe before deciding to strip
+    if (hasMediaPathParams(parsed)) {
+      const probeResult = await probeAndResolveMarkerPaths(parsed);
+      if (probeResult.warnings.length > 0) warnings.push(...probeResult.warnings);
+      if (!probeResult.allValid) {
+        // Path(s) unreachable → keep marker in text, do NOT extract any params
+        searchFrom = end + 1;
+        continue;
+      }
+      // Paths valid → strip, merge params (probeResult.params includes ismedia:true + filtered arrays)
+      Object.assign(params, probeResult.params);
+    } else {
+      // No path fields → strip marker and merge params unconditionally
+      Object.assign(params, parsed);
+    }
+    result = result.slice(0, idx) + result.slice(end + 1);
+    searchFrom = idx;
+  }
+
+  const cleanText = result !== text ? result.replace(/ {2,}/g, ' ').trim() : result;
+  return { cleanText, params, warnings };
+}

package/src/messaging/outbound/media-dedupe.ts

@@ -1,3 +1,5 @@
+import { asString } from '../../core/value-sanitize.ts';
+
 export type MediaDedupeCacheEntry = {
   mediaUrl: string;
   text: string;
@@ -5,12 +7,6 @@ export type MediaDedupeCacheEntry = {
   createdAt: number;
 };
 
-function asString(v: unknown, fallback = ''): string {
-  if (typeof v === 'string') return v;
-  if (v == null) return fallback;
-  return String(v);
-}
-
 export function normalizeReplyToId(value: unknown): string {
   return asString(value || '').trim();
 }
@@ -19,10 +15,7 @@ export function normalizeMessageText(value: unknown): string {
   return asString(value || '').trim();
 }
 
-export function shouldTreatReplyToAsSame(
-  currentReplyToId: string,
-  previousReplyToId: string,
-): boolean {
+function shouldTreatReplyToAsSame(currentReplyToId: string, previousReplyToId: string): boolean {
   if (!currentReplyToId || !previousReplyToId) return true;
   return currentReplyToId === previousReplyToId;
 }

package/src/messaging/outbound/media.ts

@@ -1,13 +1,8 @@
+import { asString } from '../../core/value-sanitize.ts';
 import { normalizeOutboundReplyToId } from './reply-target-policy.ts';
 
 type BncrOutboundMessageType = 'text' | 'image' | 'video' | 'voice' | 'audio' | 'file';
 
-function asString(v: unknown, fallback = ''): string {
-  if (typeof v === 'string') return v;
-  if (v == null) return fallback;
-  return String(v);
-}
-
 function isBncrOutboundMessageType(value: string): value is BncrOutboundMessageType {
   return (
     value === 'text' ||