dsh-vision-router 2.2.8 → 3.0.0

package/lib/client.js

@@ -12,6 +12,147 @@ window.__ModuleLoader__.load({
     const { useState, useMemo } = React
     const { ImageGallery } = require('@deepseek-ai/dsh-client-ui-attachment')
 
+    // <generated:client-maintenance-actions>
+function createClientMaintenanceActions({
+fetchImpl,
+t,
+getTestState,
+setTestState,
+getUpdateState,
+setUpdateState,
+getSelfUpdateState,
+setSelfUpdateState,
+confirmImpl,
+alertImpl,
+} = {}) {
+if (typeof fetchImpl !== 'function') throw new TypeError('client maintenance actions require fetch')
+const translate = typeof t === 'function' ? t : (key) => String(key)
+
+const diagnosticError = (value, fallback) => {
+if (typeof value === 'string' && value.trim() !== '') return value.trim()
+if (value && typeof value.message === 'string' && value.message.trim() !== '') {
+return value.message.trim()
+}
+return fallback
+}
+
+const runTestConnection = async () => {
+if (getTestState?.()?.status === 'running') return
+setTestState?.({ status: 'running' })
+try {
+const response = await fetchImpl('/_dsh/vision-router/test-connection')
+const result = await response.json().catch(() => undefined)
+setTestState?.({ status: 'done', result })
+} catch (error) {
+setTestState?.({
+status: 'done',
+result: { ok: false, error: error && error.message ? error.message : String(error) },
+})
+}
+}
+
+const requestDesktopScreenshotPermission = () => {
+// Fire-and-forget: the native permission dialog must never hold Settings
+// save completion open. The actual screenshot tool still reports denial.
+try {
+void Promise.resolve(fetchImpl('/_dsh/vision-router/request-screenshot-permission', {
+method: 'POST',
+cache: 'no-store',
+})).catch(() => {})
+} catch {
+// Permission prompting is best-effort after an already-landed setting.
+}
+}
+
+const runUpdateCheck = async (force = false) => {
+const current = getUpdateState?.() ?? {}
+if (current.status === 'running') return
+setUpdateState?.({ status: 'running', result: current.result })
+try {
+const response = await fetchImpl(
+'/_dsh/vision-router/update-check' + (force ? '?force=1' : ''),
+{ cache: 'no-store' },
+)
+const result = await response.json().catch(() => undefined)
+if (!response.ok) {
+throw new Error(diagnosticError(result && result.error, `HTTP ${response.status}`))
+}
+if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
+throw new Error(translate('updateInvalidResponse'))
+}
+setUpdateState?.({ status: 'done', result })
+} catch (error) {
+setUpdateState?.({
+status: 'done',
+result: {
+ok: false,
+error: error && error.message ? error.message : String(error),
+},
+})
+}
+}
+
+const runSelfUpdate = async () => {
+if (getSelfUpdateState?.()?.status === 'running') return
+const checked = getUpdateState?.()?.result
+const auto = checked && checked.autoUpdate
+if (!checked || checked.ok !== true || checked.updateAvailable !== true || !auto || !auto.token) return
+if (typeof confirmImpl === 'function' && confirmImpl(translate('updateConfirm')) !== true) return
+setSelfUpdateState?.({ status: 'running', result: undefined })
+try {
+const response = await fetchImpl('/_dsh/vision-router/self-update', {
+method: 'POST',
+cache: 'no-store',
+headers: { 'x-dsh-vision-router-update-token': auto.token },
+})
+const result = await response.json().catch(() => undefined)
+if (!response.ok) {
+throw new Error(diagnosticError(result && result.error, `HTTP ${response.status}`))
+}
+if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
+throw new Error(translate('updateInvalidResponse'))
+}
+setSelfUpdateState?.({ status: 'done', result })
+} catch (error) {
+setSelfUpdateState?.({
+status: 'error',
+result: { ok: false, error: error && error.message ? error.message : String(error) },
+})
+}
+}
+
+const openLogFolder = async () => {
+try {
+const response = await fetchImpl('/_dsh/vision-router/logs', {
+method: 'POST',
+cache: 'no-store',
+})
+const result = await response.json().catch(() => undefined)
+if (!response.ok || !result || result.ok !== true) {
+throw new Error(result && result.error ? result.error : `HTTP ${response.status}`)
+}
+return result
+} catch (error) {
+if (typeof alertImpl === 'function') {
+alertImpl(
+translate('openLogFolderFailed') + '：' +
+(error && error.message ? error.message : String(error)),
+)
+}
+return undefined
+}
+}
+
+return {
+runTestConnection,
+requestDesktopScreenshotPermission,
+runUpdateCheck,
+runSelfUpdate,
+openLogFolder,
+}
+}
+    // </generated:client-maintenance-actions>
+
     // ── locale dictionaries (follow the app's language setting) ─────────────
     const NS = 'vision-router'
     const zh = {
@@ -37,7 +178,8 @@ window.__ModuleLoader__.load({
       guideStep1Body: '聊天页右下角、输入框旁的模型选择器已经被高亮。选择你平时使用的聊天模型；发图片时请选择带「+ 自动识图」的版本。选好后点击「下一步」。',
       guideStepNext: '下一步',
       guidePromptTitle: '第 2 步 · 选择识图模型',
-      guidePromptGearBody: '点击侧边栏左下角被高亮圈出的「设置」齿轮打开设置面板；也可以直接点「下一步」帮你打开。',
+      guidePromptLauncherBody: '点击侧边栏左下角被高亮的设置入口；Desktop 中这里可能显示为账号头像或「更多」。也可以直接点「下一步」继续。',
+      guidePromptMenuBody: '在弹出的账号菜单中点击被高亮的「设置」（或点「下一步」自动打开设置面板）。',
       guidePromptNavBody: '在设置面板左侧点击被高亮的「Vision Router」入口（或点「下一步」自动进入）。我会直接定位到「识图模型」。',
       guidePromptCancel: '结束引导',
       guideChainTitle: '第 3 步 · 设置备用模型',
@@ -238,12 +380,9 @@ window.__ModuleLoader__.load({
         '本地后端不受影响，仍在最前。关闭时保持既有顺序（付费在前、免费补全在后）。',
       hintDesktopScreenshot: '允许模型按需截取桌面屏幕用于识图。默认关闭；开启后才提供 vision_screenshot 工具。macOS 在保存开启时会立即触发一次屏幕录制授权检查；如果已经授权，系统不会重复弹窗。',
       hintStealth:
-        '只作用于官方 DeepSeek 路由。新版 DSH 中官方 provider 始终归 Host 所有，Vision Router 只使用「+ 自动识图」' +
-        '包装，不再要求你禁用 llm-deepseek；旧版 Host 仍保留官方行缺失时的历史接管兼容。opencode 等自定义路由' +
-        '默认自动包装，只有要限制范围时才用下方手动包装。',
-      stealthOfficialDeadHint:
-        '提示：这是旧版 Host，且官方 DeepSeek 行当前被禁用；Vision Router 正使用兼容性 keep-alive 路由。' +
-        '如需恢复完全官方的原生行，请在 cordis.patch.yml 中重新启用 llm-deepseek 后重启。',
+        '仅保留旧配置字段兼容。DVR 2.3 支持的 DSH 中官方 provider 始终归 Host 所有，Vision Router 只使用' +
+        '「+ 自动识图」包装，不再接管或重建 deepseek-official，也不要求你禁用 llm-deepseek。opencode 等' +
+        '自定义路由默认自动包装，只有要限制范围时才用下方手动包装。',
       stealthOfficialHostOwnedHint:
         '检测到官方 DeepSeek provider 被禁用或不可用，但当前 DSH 已由 Host 负责该路由。Vision Router 不会自行重建它。' +
         '请重新启用 llm-deepseek，再通过「+ 自动识图」包装 /「👁 识图」处理图片任务。',
@@ -325,7 +464,8 @@ window.__ModuleLoader__.load({
       guideStep1Body: 'The model selector next to the chat input in the lower-right corner is now highlighted. For image turns, pick a group marked “+ Auto Vision”; the model inside still handles chat, reasoning, and tool calls. Click “Next” when done.',
       guideStepNext: 'Next',
       guidePromptTitle: 'Step 2 · Choose the vision model',
-      guidePromptGearBody: 'Click the highlighted Settings gear at the bottom-left of the sidebar, or press “Next” and I will open it for you.',
+      guidePromptLauncherBody: 'Click the highlighted settings launcher at the bottom-left of the sidebar. In Desktop it may appear as your account avatar or the More menu. You can also press “Next”.',
+      guidePromptMenuBody: 'In the account menu, click the highlighted “Settings” item (or press “Next” to open Settings automatically).',
       guidePromptNavBody: 'In Settings, click the highlighted “Vision Router” entry (or press “Next”). I will take you directly to “Vision model”.',
       guidePromptCancel: 'End guide',
       guideChainTitle: 'Step 3 · Add fallback models',
@@ -527,13 +667,10 @@ window.__ModuleLoader__.load({
         'Local backends are unaffected and stay first. When off, the existing order is preserved (paid first, free appended last).',
       hintDesktopScreenshot: 'Lets the model capture the desktop on demand for image understanding. Off by default; vision_screenshot is exposed only when enabled. On macOS, saving the enabled setting immediately triggers a screen-recording permission check; if permission was already granted, macOS will not prompt again.',
       hintStealth:
-        'Only affects the official DeepSeek route. On newer DSH Hosts the official provider stays Host-owned, so Vision Router ' +
-        'uses the “+ Auto Vision” wrapper and never asks you to disable llm-deepseek. Legacy Hosts retain the historical ' +
-        'takeover compatibility when the stock row is absent. Custom routes like opencode are auto-wrapped by default; use ' +
-        'the manual wrapper section below only when you want to restrict their scope.',
-      stealthOfficialDeadHint:
-        'Notice: on this legacy Host the official DeepSeek row is disabled, so Vision Router is using its compatibility ' +
-        'keep-alive route. To restore the fully official route, re-enable llm-deepseek in cordis.patch.yml and restart.',
+        'Retained only for persisted-setting compatibility. On every DSH Host supported by DVR 2.3, the official provider stays ' +
+        'Host-owned: Vision Router uses the “+ Auto Vision” wrapper and never takes over or reconstructs deepseek-official, nor ' +
+        'asks you to disable llm-deepseek. Custom routes like opencode are auto-wrapped by default; use the manual wrapper section ' +
+        'below only when you want to restrict their scope.',
       stealthOfficialHostOwnedHint:
         'The official DeepSeek provider is disabled or unavailable, but this DSH Host owns that provider route. Vision Router ' +
         'will not recreate it. Re-enable llm-deepseek, then use the “+ Auto Vision” wrapper / Vision control for image tasks.',
@@ -1849,15 +1986,49 @@ window.__ModuleLoader__.load({
       }
       return undefined
     }
-    // The sidebar settings gear: aria-haspopup="dialog" also appears on the
-    // composer's context meter, so exclude anything inside the composer card.
-    function guideGearButton() {
+    // Web/older Hosts expose a direct Settings dialog button; Desktop can
+    // replace it with an account launcher. Anchor that shape to sidebar.settings.
+    function guideSidebarSettingsRoot() {
+      if (typeof document === 'undefined') return undefined
+      return document.querySelector('[data-slot="sidebar.settings"]') || undefined
+    }
+    function guideDirectSettingsButton() {
       if (typeof document === 'undefined') return undefined
+      const root = guideSidebarSettingsRoot()
+      const direct = root && root.querySelector('button[aria-haspopup="dialog"]')
+      if (guideElementUsable(direct)) return direct
+      // Older supported Hosts may predate the sidebar.settings wrapper.
       const list = Array.from(document.querySelectorAll('button[aria-haspopup="dialog"]')).filter(
         (el) => !el.closest || !el.closest('[data-composer-card]'),
       )
       return list.find(guideElementUsable)
     }
+    function guideAccountSettingsLauncher() {
+      const root = guideSidebarSettingsRoot()
+      if (!root) return undefined
+      const launcher = root.querySelector('button[aria-haspopup="menu"]')
+      return guideElementUsable(launcher) ? launcher : undefined
+    }
+    function guideSettingsLauncher() {
+      return guideDirectSettingsButton() || guideAccountSettingsLauncher()
+    }
+    function guideSettingsMenuItem() {
+      if (typeof document === 'undefined') return undefined
+      const launcher = guideAccountSettingsLauncher()
+      if (!launcher || launcher.getAttribute('aria-expanded') !== 'true') return undefined
+      const menus = Array.from(document.querySelectorAll('[role="menu"]'))
+      for (let index = menus.length - 1; index >= 0; index--) {
+        const menu = menus[index]
+        if (!guideElementUsable(menu)) continue
+        const rows = Array.from(menu.querySelectorAll('button[role="menuitem"]'))
+        const match = rows.find((row) => {
+          const label = (row.textContent || '').trim()
+          return label.startsWith('设置') || label.startsWith('Settings')
+        })
+        if (guideElementUsable(match)) return match
+      }
+      return undefined
+    }
     // The walkthrough has one canonical destination: the first-class
     // Vision Router settings section registered below.
     function guideVisionRouterNav() {
@@ -1878,13 +2049,20 @@ window.__ModuleLoader__.load({
       settingsPanel: guideSettingsPanel,
       settingsOpen: guideSettingsPanelOpen,
       chatModelTarget: () => guideFindFirstUsable(GUIDE_SELECTOR_TARGETS),
-      settingsButton: guideGearButton,
+      settingsLauncher: guideSettingsLauncher,
+      settingsMenuItem: guideSettingsMenuItem,
       visionRouterNav: guideVisionRouterNav,
       closeSettings: closeSettingsShell,
-      openSettings() {
-        const gear = guideGearButton()
-        if (!gear || typeof gear.click !== 'function') return false
-        gear.click()
+      advanceSettingsLauncher() {
+        const launcher = guideSettingsLauncher()
+        if (!launcher || typeof launcher.click !== 'function') return false
+        launcher.click()
+        return true
+      },
+      openSettingsFromMenu() {
+        const item = guideSettingsMenuItem()
+        if (!item || typeof item.click !== 'function') return false
+        item.click()
         return true
       },
       openVisionRouter() {
@@ -1905,15 +2083,17 @@ window.__ModuleLoader__.load({
         return guideHostUi.chatModelTarget() ? 'selector' : 'corner'
       }
       if (guideSessionState === GUIDE_STATE.VISION_MODEL) return 'done'
-      if (typeof document === 'undefined') return 'gear'
+      if (typeof document === 'undefined') return 'launcher'
       if (document.querySelector('[data-vr-guide-target="vision-backend"]')) return 'done'
       if (guideHostUi.settingsPanel()) return 'nav'
-      return 'gear'
+      if (guideHostUi.settingsMenuItem()) return 'menu'
+      return 'launcher'
     }
     function guideTarget(step, phase) {
       if (step === 'step1') return guideHostUi.chatModelTarget()
       if (phase === 'nav') return guideHostUi.visionRouterNav()
-      return guideHostUi.settingsButton()
+      if (phase === 'menu') return guideHostUi.settingsMenuItem()
+      return guideHostUi.settingsLauncher()
     }
     function ensureGuideSpotlight() {
       if (visionGuideSpotlight) return visionGuideSpotlight
@@ -1954,7 +2134,11 @@ window.__ModuleLoader__.load({
       if (step === 'step1') return { title: t('guideStep1Title'), body: t('guideStep1Body') }
       return {
         title: t('guidePromptTitle'),
-        body: phase === 'nav' ? t('guidePromptNavBody') : t('guidePromptGearBody'),
+        body: phase === 'nav'
+          ? t('guidePromptNavBody')
+          : phase === 'menu'
+            ? t('guidePromptMenuBody')
+            : t('guidePromptLauncherBody'),
       }
     }
     function buildGuidePrompt(t, step, phase) {
@@ -1988,12 +2172,19 @@ window.__ModuleLoader__.load({
       next.type = 'button'
       next.className = 'vr-btn vr-btn-save'
       next.textContent = t('guideStepNext')
-      next.addEventListener('click', () => {
+      const keepSettingsMenuOpen = (event) => {
+        if (step !== 'step2' || prompt.dataset.vrPhase !== 'menu') return
+        event.preventDefault(); event.stopPropagation()
+      }
+      next.addEventListener('pointerdown', keepSettingsMenuOpen)
+      next.addEventListener('click', (event) => {
         if (step === 'step1') {
           dispatchGuide({ type: GUIDE_EVENT.NEXT }, t)
         } else {
-          const currentPhase = guidePhase('step2')
-          if (currentPhase === 'gear') guideHostUi.openSettings()
+          const currentPhase = prompt.dataset.vrPhase || guidePhase('step2')
+          if (currentPhase === 'menu') keepSettingsMenuOpen(event)
+          if (currentPhase === 'launcher') guideHostUi.advanceSettingsLauncher()
+          else if (currentPhase === 'menu') guideHostUi.openSettingsFromMenu()
           else if (currentPhase === 'nav') guideHostUi.openVisionRouter()
         }
         clearGuidePromptUI()
@@ -2055,9 +2246,8 @@ window.__ModuleLoader__.load({
         if (arrow) arrow.classList.add(step === 'step1' ? 'vr-guide-arrow-corner-se' : 'vr-guide-arrow-corner-sw')
         return
       }
-      // The gear sits at the bottom-left: land above it first. Everywhere
-      // else prefer the side so the card reads naturally left-to-right.
-      const prefer = phase === 'gear' ? ['top', 'right', 'bottom', 'left'] : ['right', 'top', 'bottom', 'left']
+      // The bottom-left Settings launcher reads best with the prompt above it.
+      const prefer = phase === 'launcher' ? ['top', 'right', 'bottom', 'left'] : ['right', 'top', 'bottom', 'left']
       const clampX = (value) => Math.min(Math.max(value, margin), Math.max(margin, vw - pw - margin))
       const clampY = (value) => Math.min(Math.max(value, margin), Math.max(margin, vh - ph - margin))
       // Keep a small halo around the target clear so the prompt never sits
@@ -3089,91 +3279,24 @@ window.__ModuleLoader__.load({
         }
       }
 
-      const runTestConnection = async () => {
-        if (testState.status === 'running') return
-        setTestState({ status: 'running' })
-        try {
-          const response = await fetch('/_dsh/vision-router/test-connection')
-          const result = await response.json().catch(() => undefined)
-          setTestState({ status: 'done', result })
-        } catch (error) {
-          setTestState({ status: 'done', result: { ok: false, error: error && error.message ? error.message : String(error) } })
-        }
-      }
-
-      const requestDesktopScreenshotPermission = () => {
-        // Fire-and-forget: saving the setting must stay responsive while macOS
-        // owns the native permission dialog. The tool itself still reports a
-        // real capture failure if the user denies access.
-        void fetch('/_dsh/vision-router/request-screenshot-permission', {
-          method: 'POST',
-          cache: 'no-store',
-        }).catch(() => {})
-      }
-
-      const diagnosticError = (value, fallback) => {
-        if (typeof value === 'string' && value.trim() !== '') return value.trim()
-        if (value && typeof value.message === 'string' && value.message.trim() !== '') {
-          return value.message.trim()
-        }
-        return fallback
-      }
-
-      const runUpdateCheck = async (force = false) => {
-        if (updateState.status === 'running') return
-        setUpdateState({ status: 'running', result: updateState.result })
-        try {
-          const response = await fetch(
-            '/_dsh/vision-router/update-check' + (force ? '?force=1' : ''),
-            { cache: 'no-store' },
-          )
-          const result = await response.json().catch(() => undefined)
-          if (!response.ok) {
-            throw new Error(diagnosticError(result && result.error, `HTTP ${response.status}`))
-          }
-          if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
-            throw new Error(t('updateInvalidResponse'))
-          }
-          setUpdateState({ status: 'done', result })
-        } catch (error) {
-          setUpdateState({
-            status: 'done',
-            result: {
-              ok: false,
-              error: error && error.message ? error.message : String(error),
-            },
-          })
-        }
-      }
-
-      const runSelfUpdate = async () => {
-        if (selfUpdateState.status === 'running') return
-        const checked = updateState.result
-        const auto = checked && checked.autoUpdate
-        if (!checked || checked.ok !== true || checked.updateAvailable !== true || !auto || !auto.token) return
-        if (typeof window.confirm === 'function' && !window.confirm(t('updateConfirm'))) return
-        setSelfUpdateState({ status: 'running', result: undefined })
-        try {
-          const response = await fetch('/_dsh/vision-router/self-update', {
-            method: 'POST',
-            cache: 'no-store',
-            headers: { 'x-dsh-vision-router-update-token': auto.token },
-          })
-          const result = await response.json().catch(() => undefined)
-          if (!response.ok) {
-            throw new Error(diagnosticError(result && result.error, `HTTP ${response.status}`))
-          }
-          if (!result || typeof result !== 'object' || typeof result.ok !== 'boolean') {
-            throw new Error(t('updateInvalidResponse'))
-          }
-          setSelfUpdateState({ status: 'done', result })
-        } catch (error) {
-          setSelfUpdateState({
-            status: 'error',
-            result: { ok: false, error: error && error.message ? error.message : String(error) },
-          })
-        }
-      }
+      const {
+        runTestConnection,
+        requestDesktopScreenshotPermission,
+        runUpdateCheck,
+        runSelfUpdate,
+        openLogFolder,
+      } = createClientMaintenanceActions({
+        fetchImpl: (...args) => fetch(...args),
+        t,
+        getTestState: () => testState,
+        setTestState,
+        getUpdateState: () => updateState,
+        setUpdateState,
+        getSelfUpdateState: () => selfUpdateState,
+        setSelfUpdateState,
+        confirmImpl: typeof window.confirm === 'function' ? window.confirm.bind(window) : undefined,
+        alertImpl: typeof window.alert === 'function' ? window.alert.bind(window) : undefined,
+      })
 
       const overriddenBadge = (key) =>
         userHas(snapshot, key)
@@ -3898,8 +4021,8 @@ window.__ModuleLoader__.load({
       // fetched (including after a remount that reset the state), start the
       // fetch. React supports setState during render for the same component,
       // and the status flips to 'loading' so this cannot loop. The same kick
-      // runs the cheap test-connection probe once so the stealth keep-alive
-      // notice (official row disabled) can render without a button click.
+      // runs the cheap test-connection probe once so the Host-owned official
+      // provider availability notice can render without a button click.
       if (open && catalog.status === 'idle') {
         loadCatalog()
       }
@@ -4055,11 +4178,8 @@ window.__ModuleLoader__.load({
         if (testState.status !== 'done') return null
         const state = testState.result && testState.result.stealth
         if (!state) return null
-        if (state.reason === 'host-owned-official-unavailable') {
-          return h('p', { className: 'vr-hint vr-stealth-notice' }, t('stealthOfficialHostOwnedHint'))
-        }
-        if (state.active !== true || state.reason !== 'official-unavailable') return null
-        return h('p', { className: 'vr-hint vr-stealth-notice' }, t('stealthOfficialDeadHint'))
+        if (state.reason !== 'host-owned-official-unavailable') return null
+        return h('p', { className: 'vr-hint vr-stealth-notice' }, t('stealthOfficialHostOwnedHint'))
       }
 
       return h('li', { className: 'vr-card' + (open ? ' vr-card-open' : '') },
@@ -4272,25 +4392,7 @@ window.__ModuleLoader__.load({
     ) : null,              h('div', { className: 'vr-footer' },
                 h('button', {
                   type: 'button', className: 'vr-btn',
-                  onClick: async () => {
-                    try {
-                      const response = await fetch('/_dsh/vision-router/logs', {
-                        method: 'POST',
-                        cache: 'no-store',
-                      })
-                      const result = await response.json().catch(() => undefined)
-                      if (!response.ok || !result || result.ok !== true) {
-                        throw new Error(result && result.error ? result.error : `HTTP ${response.status}`)
-                      }
-                    } catch (error) {
-                      if (typeof window.alert === 'function') {
-                        window.alert(
-                          t('openLogFolderFailed') + '：' +
-                            (error && error.message ? error.message : String(error)),
-                        )
-                      }
-                    }
-                  },
+                  onClick: openLogFolder,
                 }, t('openLogFolder')),
                 failed ? h('p', { className: 'vr-failed', role: 'alert' },
                   t('saveFailed') + (failedFields.length > 0 ? `（${failedFields.join('、')}）` : '')) : null,

package/lib/core-apply-lifecycle.js

@@ -0,0 +1,41 @@
+export function runCoreApplyLifecycle(invoke, { onSuccess, onFailure } = {}) {
+    if (typeof invoke !== 'function')
+        throw new TypeError('Core apply lifecycle requires an invoke function');
+    const succeed = typeof onSuccess === 'function' ? onSuccess : () => { };
+    const fail = (error) => {
+        try {
+            onFailure?.(error);
+        }
+        catch {
+            // Cleanup/diagnostic failure must not replace the Core apply error.
+        }
+        throw error;
+    };
+    let result;
+    try {
+        result = invoke();
+    }
+    catch (error) {
+        return fail(error);
+    }
+    if (result !== null
+        && (typeof result === 'object' || typeof result === 'function')
+        && typeof result.then === 'function') {
+        return Promise.resolve(result).then((value) => {
+            try {
+                succeed();
+                return value;
+            }
+            catch (error) {
+                return fail(error);
+            }
+        }, fail);
+    }
+    try {
+        succeed();
+        return result;
+    }
+    catch (error) {
+        return fail(error);
+    }
+}

package/lib/core-cache.js

@@ -0,0 +1,87 @@
+export function cacheWeight(value) {
+    if (Buffer.isBuffer(value) || value instanceof Uint8Array)
+        return value.byteLength;
+    if (typeof value === 'string')
+        return Buffer.byteLength(value, 'utf8');
+    try {
+        const encoded = JSON.stringify(value);
+        return Buffer.byteLength(encoded === undefined ? String(value) : encoded, 'utf8');
+    }
+    catch {
+        return Buffer.byteLength(String(value), 'utf8');
+    }
+}
+/**
+ * LRU+TTL cache bounded by both entry count and retained bytes.
+ *
+ * Keys are normalized to strings at the ownership boundary. A rejected write
+ * never remains resident, and every eviction updates retained-byte accounting
+ * before the entry is released.
+ */
+export function createCache(maxEntries, ttlMsValue, options = {}) {
+    const entries = new Map();
+    const entryLimit = Math.max(0, Math.floor(Number(maxEntries) || 0));
+    const ttlMs = ttlMsValue;
+    const maxBytes = Number.isFinite(Number(options.maxBytes)) && Number(options.maxBytes) >= 0
+        ? Math.floor(Number(options.maxBytes))
+        : 8 * 1024 * 1024;
+    const maxEntryBytes = Number.isFinite(Number(options.maxEntryBytes)) && Number(options.maxEntryBytes) >= 0
+        ? Math.floor(Number(options.maxEntryBytes))
+        : Math.min(maxBytes, 1024 * 1024);
+    let retainedBytes = 0;
+    const remove = (key) => {
+        const entry = entries.get(key);
+        if (entry === undefined)
+            return;
+        retainedBytes = Math.max(0, retainedBytes - entry.weight);
+        entries.delete(key);
+    };
+    const evict = () => {
+        while (entries.size > entryLimit || retainedBytes > maxBytes) {
+            const oldest = entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            remove(oldest);
+        }
+    };
+    return {
+        get(key) {
+            const rawKey = key;
+            const entry = entries.get(rawKey);
+            if (entry === undefined)
+                return undefined;
+            if (entry.expiresAt <= Date.now()) {
+                remove(rawKey);
+                return undefined;
+            }
+            entries.delete(rawKey);
+            entries.set(rawKey, entry);
+            return entry.value;
+        },
+        set(key, value) {
+            const normalizedKey = String(key);
+            const weight = Buffer.byteLength(normalizedKey, 'utf8') + cacheWeight(value);
+            remove(normalizedKey);
+            if (entryLimit === 0
+                || maxBytes === 0
+                || weight > maxEntryBytes
+                || weight > maxBytes) {
+                return false;
+            }
+            entries.set(normalizedKey, {
+                value,
+                weight,
+                expiresAt: ttlMs <= 0 ? Infinity : Date.now() + ttlMs,
+            });
+            retainedBytes += weight;
+            evict();
+            return entries.has(normalizedKey);
+        },
+        get size() {
+            return entries.size;
+        },
+        get bytes() {
+            return retainedBytes;
+        },
+    };
+}