@xmoxmo/bncr 0.6.4 → 0.6.6

package/src/messaging/inbound/conversation-history.ts

@@ -5,6 +5,7 @@ import {
   type HistoryEntry,
   type HistoryMediaEntry,
 } from 'openclaw/plugin-sdk/reply-history';
+import { normalizeAccountId } from '../../core/accounts.ts';
 import { formatOpenClawAgentEnvelope } from '../../openclaw/reply-runtime.ts';
 import type { BncrInboundApi } from './contracts.ts';
 import type { ParsedInbound } from './dispatch-prep.ts';
@@ -87,33 +88,53 @@ export function resolveBncrHistoryLimit(historyLimit?: number): number {
   return resolved >= 2 ? resolved : DEFAULT_HISTORY_LIMIT;
 }
 
-export function buildBncrConversationHistoryKey(parsed: ParsedInbound): string | null {
+export function buildBncrConversationHistoryKey(
+  parsed: ParsedInbound,
+  options?: { accountId?: string | null },
+): string | null {
   const platform = String(parsed.platform || '').trim();
   if (!platform) return null;
+  const accountId = normalizeAccountId(options?.accountId ?? parsed.accountId);
   if (parsed.peer.kind === 'group') {
     const groupId = String(parsed.groupId || '').trim();
     if (!groupId || groupId === '0') return null;
-    return `${platform}:${groupId}`;
+    return `${accountId}:${platform}:${groupId}`;
   }
   const userId = String(parsed.userId || '').trim();
   if (!userId || userId === '0') return null;
-  return `${platform}:${userId}`;
+  return `${accountId}:${platform}:${userId}`;
 }
 
 export function buildBncrConversationHistoryKeyFromRoute(args: {
+  accountId?: string | null;
   platform?: string;
   groupId?: string;
   userId?: string;
 }): string | null {
   const platform = String(args.platform || '').trim();
   if (!platform) return null;
+  const accountId = normalizeAccountId(args.accountId);
   const groupId = String(args.groupId || '0').trim() || '0';
   const userId = String(args.userId || '0').trim() || '0';
-  if (groupId !== '0') return `${platform}:${groupId}`;
-  if (userId !== '0') return `${platform}:${userId}`;
+  if (groupId !== '0') return `${accountId}:${platform}:${groupId}`;
+  if (userId !== '0') return `${accountId}:${platform}:${userId}`;
   return null;
 }
 
+/**
+ * Extract the scene key (platform:userId or platform:groupId) from a history
+ * key that may contain an accountId prefix. Legacy scene-only keys pass
+ * through unchanged.
+ */
+export function resolveBncrSceneKeyFromHistoryKey(historyKey: string): string {
+  const key = String(historyKey || '').trim();
+  const firstColon = key.indexOf(':');
+  if (firstColon > 0 && key.indexOf(':', firstColon + 1) !== -1) {
+    return key.slice(firstColon + 1);
+  }
+  return key;
+}
+
 export function resolveBncrConversationHistoryMessageId(parsed: ParsedInbound): string | undefined {
   const msgId = String(parsed.msgId || '').trim();
   return msgId || undefined;

package/src/messaging/inbound/dispatch-prep.ts

@@ -20,7 +20,7 @@ import {
 } from '../../openclaw/routing-runtime.ts';
 import type { BncrInboundApi, BncrInboundConfig, BncrRememberSessionRoute } from './contracts.ts';
 import { INBOUND_MEDIA_URL_MAX_BYTES, isHttpMediaUrl } from './media-url-download.ts';
-import { parseBncrNativeCommand } from './native-command.ts';
+import { parseBncrNativeCommand, resolveBncrNativeCommandParseOptions } from './native-command.ts';
 import { loadInboundRemoteMedia } from './remote-media.ts';
 
 export type ParsedInbound = ReturnType<typeof import('./parse.ts')['parseBncrInboundParams']>;
@@ -460,9 +460,13 @@ export async function prepareBncrInboundDispatch(args: {
   const senderIdForContext = parsed.userId || parsed.clientId || resolution.canonicalTo;
   const senderDisplayName = parsed.userName || resolution.canonicalTo;
   const isBncrNativeCommand =
-    parseBncrNativeCommand(parsed.extracted.text, {
-      allowBareWhoami: parsed.isAdmin !== true,
-    }) !== null;
+    parseBncrNativeCommand(
+      parsed.extracted.text,
+      resolveBncrNativeCommandParseOptions({
+        isAdmin: parsed.isAdmin,
+        peerKind: parsed.peer.kind as 'direct' | 'group',
+      }),
+    ) !== null;
   const isOpenClawNativeCommand =
     !isBncrNativeCommand &&
     hasControlCommand(parsed.extracted.text, cfg as Parameters<typeof hasControlCommand>[1]);

package/src/messaging/inbound/dispatch.ts

@@ -176,6 +176,8 @@ export async function dispatchBncrInbound(params: {
     // A stop command must not wait behind the history serial chain or mutate
     // the accumulated conversation window. Deliver it immediately so the host
     // can abort the active run instead of queuing behind it.
+    const stopOwnerAllowFrom =
+      parsed.peer.kind === 'direct' && senderIdForContext ? [senderIdForContext] : ownerAllowFrom;
     const ctxPayload = await buildBncrInboundTurnContext({
       api,
       cfg,
@@ -185,7 +187,7 @@ export async function dispatchBncrInbound(params: {
       peer,
       senderIdForContext,
       senderDisplayName,
-      ownerAllowFrom,
+      ownerAllowFrom: stopOwnerAllowFrom,
       bridgeSenderId,
       bridgeSenderName,
       historyLimit: resolvedHistoryLimit,

package/src/messaging/inbound/native-command-runtime.ts

@@ -81,6 +81,7 @@ export function createNativeCommandTurnContext(args: {
   peer: ParsedInbound['peer'];
   resolvedRoute: { sessionKey: string; agentId: string; mainSessionKey?: string };
   sessionKey: string;
+  ownerAllowFrom?: string[];
   displayTo: string;
   originatingTo: string;
   senderIdForContext: string;
@@ -167,6 +168,9 @@ export function createNativeCommandTurnContext(args: {
       authorized: true,
       body: args.body,
     };
+    if (args.ownerAllowFrom?.length) {
+      ctx.OwnerAllowFrom = args.ownerAllowFrom;
+    }
     return ctx;
   });
 }

package/src/messaging/inbound/native-command.ts

@@ -50,7 +50,73 @@ export type NativeSessionResetCommand = {
   text: string;
 };
 
-const BNCR_NATIVE_COMMANDS = new Set([
+/**
+ * Commands that non-admin private-chat users may self-elevate for.
+ * When a non-admin direct-chat caller issues one of these commands,
+ * the plugin temporarily treats them as admin so the command follows
+ * the same code path as an admin caller. This whitelist is shared
+ * across permission checks so admin and non-admin logic stay in sync.
+ *
+ * `stop` is intentionally absent: it is handled before this set by the
+ * unified stop fast path in dispatch.ts, and `isBncrStopCommandText` only
+ * accepts the exact `/stop` form.
+ */
+export const BNCR_SELF_SERVICE_COMMANDS: ReadonlySet<string> = new Set([
+  'whoami',
+  'status',
+  'verbose',
+  'model',
+  'new',
+  'reset',
+]);
+
+/**
+ * Synthetic command name used when an admin bare command is routed to the
+ * OpenClaw native parser. It must never be exposed to the user.
+ */
+export const BNCR_OPENCLAW_NATIVE_COMMAND = '__openclaw_native__';
+
+/**
+ * Detect if the raw text is a bare whitelist command that should be
+ * elevated to admin for OpenClaw native parsing (private non-admin)
+ * or mapped to /bncr (group non-admin).
+ */
+export function isBncrWhitelistBareCommandText(rawBody: string): string | null {
+  const raw = String(rawBody || '')
+    .trim()
+    .toLowerCase();
+  if (!raw.startsWith('/')) return null;
+  const bare = raw.slice(1);
+  if (!bare) return null;
+  // Whitelist commands match the exact command name only. @bot suffixes are
+  // intentionally unsupported so bare commands stay consistent with /stop.
+  const commandName = bare.split(/\s+/, 1)[0];
+  if (!commandName) return null;
+  return BNCR_SELF_SERVICE_COMMANDS.has(commandName) ? commandName : null;
+}
+
+/**
+ * Resolve which bare slash commands bncr should treat as native commands.
+ *
+ * Admin callers never have whitelist restrictions: their bare commands go to
+ * the OpenClaw parser. Non-admin group callers map the whitelist onto /bncr
+ * native commands; non-admin private callers are elevated and routed to the
+ * OpenClaw parser instead (handled before this helper runs).
+ */
+export function resolveBncrNativeCommandParseOptions(args: {
+  isAdmin: boolean;
+  peerKind: 'direct' | 'group';
+}): ParseBncrNativeCommandOptions {
+  const isGroup = args.peerKind === 'group';
+  const isNonAdmin = args.isAdmin !== true;
+  return {
+    allowBareWhoami: isNonAdmin && isGroup,
+    allowBareStatus: isNonAdmin && isGroup,
+    allowBareSessionReset: isNonAdmin && isGroup,
+  };
+}
+
+export const BNCR_NATIVE_COMMANDS = new Set([
   'help',
   'new',
   'reset',
@@ -69,13 +135,7 @@ const BNCR_NATIVE_COMMANDS = new Set([
   'download-media',
 ]);
 
-export const BNCR_DIRECT_ALLOWED_BARE_COMMANDS = new Set([
-  'whoami',
-  'status',
-  'new',
-  'reset',
-  'stop',
-]);
+export const BNCR_DIRECT_ALLOWED_BARE_COMMANDS = new Set(['whoami', 'status', 'new', 'reset']);
 
 export const BNCR_DIRECT_ALLOWED_SUBCOMMANDS = new Set([
   'help',
@@ -128,7 +188,9 @@ export function parseBncrUnsupportedDirectCommand(text: string): {
   const raw = String(text || '').trim();
   if (!raw.startsWith('/')) return null;
 
-  const bareMatch = raw.match(/^\/([A-Za-z0-9_]+)(?:\s+.*)?$/);
+  // Hyphens are allowed in command names (e.g. /history-limit) so bare slash
+  // parsing matches the same command vocabulary as the /bncr subcommands.
+  const bareMatch = raw.match(/^\/([A-Za-z0-9_-]+)(?:\s+.*)?$/);
   if (!bareMatch) return null;
   const bareCommand = String(bareMatch[1] || '')
     .trim()
@@ -158,7 +220,7 @@ const BNCR_HELP_SECTIONS = [
       { label: '/bncr status', scopes: ['admin', 'direct', 'group'] },
       { label: '/bncr new', scopes: ['admin', 'direct'] },
       { label: '/bncr reset', scopes: ['admin', 'direct'] },
-      { label: '/bncr verbose on|off|full', scopes: ['admin'] },
+      { label: '/bncr verbose on|off|full', scopes: ['admin', 'direct'] },
     ],
   },
   {
@@ -180,20 +242,20 @@ const BNCR_HELP_SECTIONS = [
   },
   {
     title: '📋 Conversation history',
-    audience: 'admin',
+    audience: 'all',
     commands: [
-      { label: '/bncr history-help', scopes: ['admin'] },
-      { label: '/bncr history-limit [<number>|clear] [<SceneId>]', scopes: ['admin'] },
-      { label: '/bncr history-force on|off|clear [<SceneId>]', scopes: ['admin'] },
+      { label: '/bncr history-help', scopes: ['admin', 'direct'] },
+      { label: '/bncr history-limit [<number>|clear] [<SceneId>]', scopes: ['admin', 'direct'] },
+      { label: '/bncr history-force on|off|clear [<SceneId>]', scopes: ['admin', 'direct'] },
     ],
   },
   {
     title: '🌐 Remote media',
-    audience: 'admin',
+    audience: 'all',
     commands: [
       {
         label: '/bncr download-media on|off|clear|default on|off [<SceneId>]',
-        scopes: ['admin'],
+        scopes: ['admin', 'direct'],
       },
     ],
   },
@@ -271,27 +333,35 @@ export function resolveBncrNativeSessionResetCommand(args: {
   peerKind: 'direct' | 'group';
 }): NativeSessionResetCommand | null {
   if (args.command.command !== 'new' && args.command.command !== 'reset') return null;
+  // new/reset are exact session-reset commands. Extra arguments are not
+  // valid and must not silently reset or create a session.
+  if (String(args.command.argsText || '').trim()) return null;
   const reason = args.command.command === 'new' ? 'new' : 'reset';
-  const scope = args.peerKind === 'group' ? 'this group chat' : 'this private chat';
   return {
     handled: true,
     reason,
-    text:
-      reason === 'new'
-        ? `Started a new session for ${scope}.`
-        : `Reset the current session for ${scope}.`,
+    text: reason === 'new' ? '✅ New session started.' : '✅ Session reset.',
   };
 }
 
 export function resolveBncrNativeVerboseCommand(
   command: NativeCommand,
+  currentLevel?: 'on' | 'off' | 'full',
 ): NativeVerboseCommand | null {
   if (command.command !== 'verbose') return null;
   const rawLevel = String(command.argsText || '')
     .trim()
     .toLowerCase();
   if (!rawLevel || rawLevel === 'status') {
-    return { handled: true, text: 'Current verbose level is unchanged.' };
+    const label =
+      currentLevel === 'full'
+        ? 'full'
+        : currentLevel === 'off'
+          ? 'off'
+          : currentLevel === 'on'
+            ? 'on'
+            : 'default';
+    return { handled: true, text: `Current verbose level: ${label}` };
   }
   if (rawLevel === 'on')
     return { handled: true, verboseLevel: 'on', text: 'Verbose logging enabled.' };

package/src/messaging/inbound/outbound-replay-cache.ts

@@ -1,3 +1,4 @@
+import { normalizeAccountId } from '../../core/accounts.ts';
 import type {
   BncrOutboundReplayEntry,
   BncrOutboundReplayMediaEntry,
@@ -66,7 +67,7 @@ export function buildBncrOutboundReplayKeyFromRoute(args: {
   groupId?: string;
   userId?: string;
 }): string | null {
-  const accountId = String(args.accountId || '').trim() || 'default';
+  const accountId = normalizeAccountId(args.accountId);
   const platform = String(args.platform || '').trim();
   const groupId = String(args.groupId || '0').trim() || '0';
   const userId = String(args.userId || '0').trim() || '0';
@@ -167,6 +168,18 @@ export type BncrOutboundReplayRecordResult = {
   historyVersion?: number;
 };
 
+/**
+ * Record an outbound bot reply into both the conversation-history window and
+ * the outbound-replay cache.
+ *
+ * Dual-write strategy: the conversation-history window is the canonical
+ * ordered source for structured context (conversation_context). The
+ * outbound-replay cache is a lighter, indexed copy used by bridge-facing
+ * queries such as `listRecentOutbound`. Both are kept in sync for the
+ * duration of the runtime session. This is a compatibility design; the
+ * cache may be retired once all read paths are migrated to the history
+ * window.
+ */
 export function recordBncrOutboundReplay(args: {
   cache: BncrOutboundReplayCache;
   conversationHistories?: BncrConversationHistoryMap;
@@ -200,6 +213,7 @@ export function recordBncrOutboundReplay(args: {
   if (!body) return { recorded: false, historyOverflow: false };
   const recordTimestamp = args.entry.lastPushAt ?? Date.now();
   const historyKey = buildBncrConversationHistoryKeyFromRoute({
+    accountId: args.entry.accountId,
     platform: args.entry.route?.platform,
     groupId: args.entry.route?.groupId,
     userId: args.entry.route?.userId,
@@ -347,7 +361,9 @@ export function readBncrOutboundReplaySnapshot(args: {
     : [];
   if (!args.conversationHistories) return legacyEntries;
 
-  const historyKey = buildBncrConversationHistoryKey(args.parsed);
+  const historyKey = buildBncrConversationHistoryKey(args.parsed, {
+    accountId: args.accountId,
+  });
   const historyEntries = historyKey
     ? (args.conversationHistories.get(historyKey) || [])
         .filter((entry) => entry.role === 'assistant')

package/src/messaging/inbound/reply-dispatch.ts

@@ -6,6 +6,7 @@ import {
   resolveBncrPinnedMainDmOwnerFromAllowlist,
 } from '../../openclaw/inbound-session-runtime.ts';
 import { dispatchOpenClawReplyWithBufferedBlockDispatcher } from '../../openclaw/reply-runtime.ts';
+import { mergeBncrOwnerAllowFromIntoConfig } from './command-owner.ts';
 import type {
   BncrEnqueueFromReply,
   BncrInboundApi,
@@ -18,7 +19,11 @@ import type {
   ParsedInbound,
 } from './dispatch-prep.ts';
 import { buildBncrInboundRecordUpdateLastRoute } from './last-route.ts';
-import { isBncrStopCommandText, parseBncrNativeCommand } from './native-command.ts';
+import {
+  isBncrStopCommandText,
+  parseBncrNativeCommand,
+  resolveBncrNativeCommandParseOptions,
+} from './native-command.ts';
 import { buildBncrReplyConfig } from './reply-config.ts';
 import { runBncrReplyDispatchSerial } from './reply-dispatch-serial.ts';
 import { resolveBncrChannelInboundRuntime } from './runtime-compat.ts';
@@ -29,32 +34,6 @@ import {
 } from './session-label.ts';
 import { createBncrSessionMetaTaskBarrier } from './session-meta-task.ts';
 
-function mergeBncrCommandOwnerAllowFrom(args: {
-  cfg: BncrInboundConfig;
-  parsed: ParsedInbound;
-  isBncrNativeCommand: boolean;
-  senderIdForContext: string;
-}) {
-  const { cfg, parsed, isBncrNativeCommand, senderIdForContext } = args;
-  if (parsed.isAdmin !== true || isBncrNativeCommand) return cfg;
-  const senderId = String(senderIdForContext || '').trim();
-  if (!senderId) return cfg;
-
-  const currentCommands = (cfg.commands || {}) as { ownerAllowFrom?: string[] };
-  const currentOwnerAllowFrom = Array.isArray(currentCommands.ownerAllowFrom)
-    ? currentCommands.ownerAllowFrom
-    : [];
-  if (currentOwnerAllowFrom.includes(senderId)) return cfg;
-
-  return {
-    ...cfg,
-    commands: {
-      ...currentCommands,
-      ownerAllowFrom: [...currentOwnerAllowFrom, senderId],
-    },
-  } satisfies BncrInboundConfig;
-}
-
 function sleep(ms: number) {
   return new Promise((resolve) => setTimeout(resolve, ms));
 }
@@ -180,15 +159,17 @@ export async function runBncrInboundReplyDispatch(args: {
     pinnedMainDmOwner,
   });
   const isBncrNativeCommand =
-    parseBncrNativeCommand(rawBody, {
-      allowBareWhoami: parsed.isAdmin !== true,
-    }) !== null;
-  const commandDispatchCfg = mergeBncrCommandOwnerAllowFrom({
-    cfg,
-    parsed,
-    isBncrNativeCommand,
-    senderIdForContext,
-  });
+    parseBncrNativeCommand(
+      rawBody,
+      resolveBncrNativeCommandParseOptions({
+        isAdmin: parsed.isAdmin,
+        peerKind: parsed.peer.kind as 'direct' | 'group',
+      }),
+    ) !== null;
+  const commandDispatchCfg =
+    parsed.isAdmin === true && !isBncrNativeCommand
+      ? mergeBncrOwnerAllowFromIntoConfig({ cfg, senderIdForContext })
+      : cfg;
 
   if (!shouldDispatch) {
     await wrapBncrInboundRecordSessionLabelCorrection({
@@ -266,6 +247,14 @@ export async function runBncrInboundReplyDispatch(args: {
                     sessionMetaBarrier.track(task);
                   },
                 },
+                // OpenClaw ≥8.1 requires prepared turns to carry a runDispatchLifecycle
+                // shim. Bncr dispatches directly via runDispatch and does not participate
+                // in the adoption lifecycle, so turnAdoptionLifecycle is intentionally
+                // left as undefined; onDispatchSkipped is a safe no-op here.
+                runDispatchLifecycle: {
+                  turnAdoptionLifecycle: undefined,
+                  onDispatchSkipped: async () => {},
+                },
                 runDispatch: async () => {
                   await sessionMetaBarrier.wait();
                   await correctBncrInboundSessionLabel({

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

@@ -435,13 +435,41 @@ export function executeSceneAdminCommand(args: {
   defaultAdminAgentId: string;
   defaultPublicAgentId: string;
   now: () => number;
+  /**
+   * When true, non-admin callers in direct chat are allowed to execute
+   * self-admin commands (history-*, download-media) scoped to
+   * their own session only.  The flag is set by the caller after an
+   * explicit allow-list check – it must NOT be granted unconditionally
+   * for direct chat.
+   */
+  allowNonAdminSelfAdmin?: boolean;
 }): { ok: true; text: string } | { ok: false; text: string } {
-  const { parsed, command, sceneRegistry, defaultAdminAgentId, defaultPublicAgentId, now } = args;
-
-  if (!parsed.isAdmin) {
+  const {
+    parsed,
+    command,
+    sceneRegistry,
+    defaultAdminAgentId,
+    defaultPublicAgentId,
+    now,
+    allowNonAdminSelfAdmin,
+  } = args;
+
+  // Admin always passes; non-admin only passes when the caller explicitly
+  // opted in via allowNonAdminSelfAdmin (self-admin commands in direct chat).
+  if (!parsed.isAdmin && !allowNonAdminSelfAdmin) {
     return { ok: false, text: 'Admin permission required.' };
   }
 
+  // Non-admin self-admin: enforce that sceneId targets only the caller's own session.
+  if (allowNonAdminSelfAdmin && !parsed.isAdmin) {
+    const currentSceneKey = resolveCurrentSceneKey(parsed);
+    const cmdSceneKey =
+      'sceneKey' in command ? (command as { sceneKey?: string }).sceneKey : undefined;
+    if (cmdSceneKey && currentSceneKey && cmdSceneKey !== currentSceneKey) {
+      return { ok: false, text: 'You can only manage your own private chat session.' };
+    }
+  }
+
   if (command.kind === 'history-help') {
     return { ok: true, text: HISTORY_HELP_TEXT };
   }

package/src/openclaw/inbound-session-runtime.ts

@@ -1,6 +1,7 @@
 import { recordInboundSession as sdkRecordInboundSession } from 'openclaw/plugin-sdk/conversation-runtime';
 import { resolvePinnedMainDmOwnerFromAllowlist as sdkResolvePinnedMainDmOwnerFromAllowlist } from 'openclaw/plugin-sdk/security-runtime';
 import {
+  getSessionEntry as sdkGetSessionEntry,
   recordSessionMetaFromInbound as sdkRecordSessionMetaFromInbound,
   resolveStorePath as sdkResolveStorePath,
   updateSessionStoreEntry as sdkUpdateSessionStoreEntry,
@@ -14,6 +15,7 @@ type ResolveStorePathFn = (
 type RecordInboundSessionFn = typeof sdkRecordInboundSession;
 type RecordSessionMetaFromInboundFn = typeof sdkRecordSessionMetaFromInbound;
 type UpdateSessionStoreEntryFn = typeof sdkUpdateSessionStoreEntry;
+type GetSessionEntryFn = typeof sdkGetSessionEntry;
 type ReadSessionUpdatedAtFn = (params: { storePath: string; sessionKey: string }) => unknown;
 type ResolvePinnedMainDmOwnerFromAllowlistFn = typeof sdkResolvePinnedMainDmOwnerFromAllowlist;
 
@@ -22,6 +24,7 @@ type BncrInboundSessionRuntime = {
   recordInboundSession: RecordInboundSessionFn;
   recordSessionMetaFromInbound: RecordSessionMetaFromInboundFn;
   updateSessionStoreEntry: UpdateSessionStoreEntryFn;
+  getSessionEntry: GetSessionEntryFn;
   readSessionUpdatedAt?: ReadSessionUpdatedAtFn;
   resolvePinnedMainDmOwnerFromAllowlist: ResolvePinnedMainDmOwnerFromAllowlistFn;
 };
@@ -36,6 +39,7 @@ function resolveRuntime(): BncrInboundSessionRuntime {
       testRuntimeOverride?.recordSessionMetaFromInbound ?? sdkRecordSessionMetaFromInbound,
     updateSessionStoreEntry:
       testRuntimeOverride?.updateSessionStoreEntry ?? sdkUpdateSessionStoreEntry,
+    getSessionEntry: testRuntimeOverride?.getSessionEntry ?? sdkGetSessionEntry,
     readSessionUpdatedAt: testRuntimeOverride?.readSessionUpdatedAt,
     resolvePinnedMainDmOwnerFromAllowlist:
       testRuntimeOverride?.resolvePinnedMainDmOwnerFromAllowlist ??
@@ -81,6 +85,19 @@ export function readBncrSessionUpdatedAt(
   return readSessionUpdatedAt(params);
 }
 
+export async function readBncrSessionEntry(params: {
+  storePath: string;
+  sessionKey: string;
+}): Promise<Record<string, unknown> | undefined> {
+  const runtime = resolveRuntime();
+  try {
+    const entry = await runtime.getSessionEntry(params);
+    return entry && typeof entry === 'object' ? (entry as Record<string, unknown>) : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 export function resolveBncrPinnedMainDmOwnerFromAllowlist(
   params: Parameters<ResolvePinnedMainDmOwnerFromAllowlistFn>[0],
 ): ReturnType<ResolvePinnedMainDmOwnerFromAllowlistFn> {

package/src/openclaw/session-reset-runtime.ts

@@ -0,0 +1,125 @@
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { createRequire } from 'node:module';
+import { dirname, join } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+type SessionResetResult = { ok?: boolean } | undefined;
+type SessionResetParams = {
+  key: string;
+  reason: 'new' | 'reset';
+  agentId?: string;
+  commandSource?: string;
+};
+type SessionResetFn = (params: SessionResetParams) => Promise<SessionResetResult>;
+
+let testOverride: SessionResetFn | null = null;
+let resolvedSessionResetRuntimeCache: SessionResetFn | null = null;
+
+export function setBncrSessionResetRuntimeForTest(fn: SessionResetFn | null): () => void {
+  const previous = testOverride;
+  testOverride = fn;
+  return () => {
+    testOverride = previous;
+  };
+}
+
+function findPackageRoot(startPath: string, packageName: string): string | null {
+  let current = dirname(startPath);
+  while (true) {
+    const pkgPath = join(current, 'package.json');
+    try {
+      const pkg = JSON.parse(readFileSync(pkgPath, 'utf8')) as { name?: string };
+      if (pkg.name === packageName) return current;
+    } catch {
+      // Keep walking toward the package root.
+    }
+    const parent = dirname(current);
+    if (parent === current) return null;
+    current = parent;
+  }
+}
+
+function resolveOpenClawDistDir(): string {
+  let current = dirname(fileURLToPath(import.meta.url));
+  let resolvedOpenClawEntry: string | null = null;
+  try {
+    resolvedOpenClawEntry = createRequire(import.meta.url).resolve('openclaw');
+  } catch {
+    // Fall back to the plugin-local dependency path below.
+  }
+
+  const openClawRoot = resolvedOpenClawEntry
+    ? findPackageRoot(resolvedOpenClawEntry, 'openclaw')
+    : null;
+  if (openClawRoot) {
+    const distDir = join(openClawRoot, 'dist');
+    if (existsSync(distDir)) return distDir;
+  }
+
+  while (true) {
+    const pluginRoot = findPackageRoot(current, '@xmoxmo/bncr');
+    if (pluginRoot) {
+      const distDir = join(pluginRoot, 'node_modules', 'openclaw', 'dist');
+      if (existsSync(distDir)) return distDir;
+    }
+    const parent = dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+
+  const resolvedPath = resolvedOpenClawEntry || '(unresolved)';
+  const pluginPath = join(
+    dirname(fileURLToPath(import.meta.url)),
+    'node_modules',
+    'openclaw',
+    'dist',
+  );
+  throw new Error(
+    `OpenClaw dist directory not found (resolved entry: ${resolvedPath}; plugin fallback: ${pluginPath})`,
+  );
+}
+
+function resolveOpenClawSessionsRuntimeUrls(): string[] {
+  const distDir = resolveOpenClawDistDir();
+  if (!existsSync(distDir)) {
+    throw new Error(`OpenClaw dist directory not found: ${distDir}`);
+  }
+
+  // Scan dist for sessions.runtime*.js, preferring the stable re-export.
+  const candidates = readdirSync(distDir)
+    .filter((name) => /^sessions\.runtime(?:-[A-Za-z0-9_-]+)?\.js$/.test(name))
+    .sort(
+      (a, b) =>
+        Number(b === 'sessions.runtime.js') - Number(a === 'sessions.runtime.js') ||
+        a.localeCompare(b),
+    );
+  return candidates.map((name) => pathToFileURL(join(distDir, name)).href);
+}
+
+export async function performBncrGatewaySessionReset(
+  params: SessionResetParams,
+): Promise<SessionResetResult> {
+  if (testOverride) return testOverride(params);
+  if (!resolvedSessionResetRuntimeCache) {
+    const candidates = resolveOpenClawSessionsRuntimeUrls();
+    const importErrors: string[] = [];
+    for (const url of candidates) {
+      try {
+        const mod = (await import(url)) as { performGatewaySessionReset?: SessionResetFn };
+        if (typeof mod.performGatewaySessionReset === 'function') {
+          resolvedSessionResetRuntimeCache = mod.performGatewaySessionReset;
+          break;
+        }
+        importErrors.push(`${url}: export unavailable`);
+      } catch (error) {
+        importErrors.push(`${url}: ${error instanceof Error ? error.message : String(error)}`);
+      }
+    }
+    if (!resolvedSessionResetRuntimeCache) {
+      throw new Error(
+        `OpenClaw performGatewaySessionReset is unavailable; candidates: ${importErrors.join('; ') || '(none)'}`,
+      );
+    }
+  }
+  return resolvedSessionResetRuntimeCache(params);
+}