dsh-dbhub-live 5.1.0 → 5.2.0-dev.3

package/lib/config.mjs

@@ -586,6 +586,9 @@ export function normalizePrefs(raw) {
   // plugin's enabled state: hiding the shortcut does not turn the plugin off,
   // and the client ANDs the two (a disabled plugin contributes no entry at all).
   if (typeof raw.showSidebarEntry === 'boolean') defineOwn(out, 'showSidebarEntry', raw.showSidebarEntry)
+  // The user's own "announce the database-access policy to the model" preference.
+  // Turning it off removes one system-prompt section; no tool changes behavior.
+  if (typeof raw.announceAccessPolicy === 'boolean') defineOwn(out, 'announceAccessPolicy', raw.announceAccessPolicy)
   return out
 }
 

package/lib/i18n.mjs

@@ -12,6 +12,7 @@ const ZH = {
   'log.hostApply': 'host apply',
   'log.nsRegistered': '状态命名空间已注册: dsh-dbhub-live',
   'log.loaded': 'dbhub 插件已加载（{n} 个工具）',
+  'log.policyRegistered': '模型侧访问策略已注册（system prompt 段 {name}）',
   'log.initFailed': '后台初始化失败（状态卡片可见最近错误）',
   'log.disabledBoot': '插件处于禁用状态（可在 插件 → dsh-dbhub-live → 配置 开启）',
   'log.opSaved': '卡片配置：{title} 环境 {env} 已保存',
@@ -25,6 +26,11 @@ const ZH = {
   'log.syncApplied': '配置已生效：连接摘要已刷新（{n} 个工具声明）',
   'log.stateSyncFail': '状态同步失败: {msg}',
   'log.updateCheckFailed': 'dbhub 自动更新检查失败: {msg}',
+  // Plugin self-update check (the card's {op:'updateCheck'} command). Host log
+  // only — the browser-side wording lives in lib/client.js.
+  'log.appUpdate': '发现新版本：本插件 {current} → {latest}（来源 {source}）',
+  'log.appUpToDate': '已是最新版本：本插件 {current}（最新 {latest}，来源 {source}）',
+  'log.appUpdateFailed': '插件更新检查失败：{msg}（当前版本 {current}）',
   'log.testStart': '卡片连接测试：{title} 环境 {env}',
   'log.testDone': '卡片连接测试完成：{title} 环境 {env} → {result}',
   'result.testOk': '连接成功（SELECT 1，{ms} ms）',
@@ -42,7 +48,7 @@ const ZH = {
   'result.needWorkspace': '当前会话的工作区不在已注册工作区列表中，无法确定要在哪个工作区配置连接。请让用户确认后用 workspace 参数显式指定（路径或标题）：\n{list}',
   'result.unknownWorkspace': '找不到工作区 "{ws}"（不会自动改用其他工作区，以免配置到错误的位置）。可用的工作区：\n{list}',
   'result.noDsnViaModel': '出于安全原因，不能把密码/完整连接串作为 dbhub_configure 的参数传入（否则会进入模型上下文）。插件会在界面弹出密码输入框——请引导用户输入，或让用户在 插件 → dsh-dbhub-live → 配置 中修改。',
-  'result.authHint': '提示：可能是凭据不正确或连接信息（主机/端口/库）有误。可调用 dbhub_configure 更新该环境（{src}）的连接——密码通过界面输入，不会经过模型；也可让用户在 插件 → dsh-dbhub-live → 配置 中修改。',
+  'result.authHint': '提示：可能是凭据不正确或连接信息（主机/端口/库）有误。可调用 dbhub_configure 更新该环境（{src}）的连接——密码通过界面输入，不会经过模型；也可让用户在 插件 → dsh-dbhub-live → 配置 中修改。**不要为了连上这个库改用命令行客户端或脚本直连**（凭据只能由用户在插件里输入）。',
   'result.sourcesIntro': '已注册连接源 {n} 个，分属 {m} 个工作区（仅元数据：类型/主机/端口/库；密码与账号永不显示）。**每条 source 只属于一个工作区，不同工作区的相似连接是不同目标，不要混用。**',
   'result.wsCurrentHead': '【当前工作区】（优先使用这里的 source）：',
   'result.wsGroup': '- {title}（{path}）',
@@ -96,7 +102,7 @@ const ZH = {
   'result.scanNone': '扫描了 {n} 个文件，但未提取到数据库连接。可改用“输入 DSN”或“填写分项”。',
   'result.scanPicked': '已按你的确认持久化连接（来源: 项目文件扫描，环境 {env}）。查询时用 dbhub_execute_sql，source 值 = {srcId}。',
   // ── 5.1: environment-level read-only mode ──
-  'result.readOnlyHint': '提示：该环境已开启**只读模式**（由用户在配置页设置），dbhub 只放行只读语句（MySQL 为 select/with/explain/show/describe/desc，其他连接器略有不同），写操作会被拒绝（READONLY_VIOLATION）。如需写入，请让用户在 **设置 → DBHub 数据库工具**（或插件页该行的「配置」）里关闭只读——模型只能开启，不能自行关闭。',
+  'result.readOnlyHint': '提示：该环境已开启**只读模式**（由用户在配置页设置），dbhub 只放行只读语句（MySQL 为 select/with/explain/show/describe/desc，其他连接器略有不同），写操作会被拒绝（READONLY_VIOLATION）。如需写入，请让用户在 **设置 → DBHub 数据库工具**（或插件页该行的「配置」）里关闭只读——模型只能开启，不能自行关闭。**不要改用 psql/mysql 等命令行客户端、临时脚本或任何其它途径绕过本插件完成这次写入（包括换用别的数据库插件）**：只读是用户设定的安全边界，绕过等于自行提权；若这次写入确实必要，把影响与理由告诉用户，由用户决定。',
   'result.readOnlyUserOnly': '出于安全考虑，**关闭只读模式只能由用户操作**（模型只能开启、不能解除，否则等于自行提权）。请让用户在 **设置 → DBHub 数据库工具**（或插件页该行的「配置」）里关闭该环境的只读开关。',
   'result.readOnlyOn': '已开启只读模式（环境 {env}）：写操作会被 dbhub 拒绝（READONLY_VIOLATION）。',
   'result.readOnlyOff': '已关闭只读模式（环境 {env}）。',
@@ -156,6 +162,7 @@ const EN = {
   'log.hostApply': 'host apply',
   'log.nsRegistered': 'settings namespace registered: dsh-dbhub-live',
   'log.loaded': 'dbhub plugin loaded ({n} tools)',
+  'log.policyRegistered': 'model-facing access policy registered (system prompt section {name})',
   'log.initFailed': 'background init failed (see the recent error on the status card)',
   'log.disabledBoot': 'plugin disabled (enable it in Plugins → dsh-dbhub-live → Configure)',
   'log.opSaved': 'card config: {title} environment {env} saved',
@@ -169,6 +176,9 @@ const EN = {
   'log.syncApplied': 'config applied: connection summaries refreshed ({n} tool declarations)',
   'log.stateSyncFail': 'status sync failed: {msg}',
   'log.updateCheckFailed': 'dbhub auto-update check failed: {msg}',
+  'log.appUpdate': 'update available: plugin {current} -> {latest} (source {source})',
+  'log.appUpToDate': 'plugin is up to date: {current} (latest {latest}, source {source})',
+  'log.appUpdateFailed': 'plugin update check failed: {msg} (current {current})',
   'log.testStart': 'card connection test: {title} env {env}',
   'log.testDone': 'card connection test finished: {title} env {env} → {result}',
   'result.testOk': 'connection OK (SELECT 1, {ms} ms)',
@@ -186,7 +196,7 @@ const EN = {
   'result.needWorkspace': 'The session workspace is not among the registered workspaces, so the target workspace is unknown. Ask the user, then pass workspace explicitly (path or title):\n{list}',
   'result.unknownWorkspace': 'workspace "{ws}" not found (the plugin will NOT silently switch to another workspace and configure the wrong place). Available workspaces:\n{list}',
   'result.noDsnViaModel': 'For security, a password or full DSN cannot be passed as a dbhub_configure argument (it would land in the model context). The plugin prompts for the password in the UI — ask the user to enter it, or have them edit it in Plugins → dsh-dbhub-live → Configure.',
-  'result.authHint': 'Hint: the credentials are likely incorrect, or the connection details (host/port/database) are wrong. You can run dbhub_configure to update this source ({src}) — the password is entered in the UI, never through the model; the user can also edit it in Plugins → dsh-dbhub-live → Configure.',
+  'result.authHint': 'Hint: the credentials are likely incorrect, or the connection details (host/port/database) are wrong. You can run dbhub_configure to update this source ({src}) — the password is entered in the UI, never through the model; the user can also edit it in Plugins → dsh-dbhub-live → Configure. **Do not switch to a command-line client or script to reach this database** — credentials are entered by the user in the plugin, never by the model.',
   'result.sourcesIntro': 'Registered source(s): {n} across {m} workspace(s) (metadata only — type/host/port/database; passwords and usernames are never shown). **Every source belongs to exactly ONE workspace; look-alike connections in different workspaces are different targets — never treat them as the same.**',
   'result.wsCurrentHead': '[CURRENT WORKSPACE] (prefer the sources here):',
   'result.wsGroup': '- {title} ({path})',
@@ -240,7 +250,7 @@ const EN = {
   'result.scanNone': 'scanned {n} files but extracted no database connection. Use "enter DSN" or "fill in fields" instead.',
   'result.scanPicked': 'connection persisted from your selection (source: project file scan, env {env}). Query with dbhub_execute_sql; source value = {srcId}.',
   // ── 5.1: environment-level read-only mode ──
-  'result.readOnlyHint': 'Note: this environment has **read-only mode** enabled (set by the user on the configuration page). dbhub only allows read statements (on MySQL: select/with/explain/show/describe/desc; other connectors differ slightly) and rejects writes with READONLY_VIOLATION. To write, ask the user to turn read-only off in **Settings → DBHub Database Tools** (or the Configure action on that Plugins row) — the model may enable it but must never disable it.',
+  'result.readOnlyHint': 'Note: this environment has **read-only mode** enabled (set by the user on the configuration page). dbhub only allows read statements (on MySQL: select/with/explain/show/describe/desc; other connectors differ slightly) and rejects writes with READONLY_VIOLATION. To write, ask the user to turn read-only off in **Settings → DBHub Database Tools** (or the Configure action on that Plugins row) — the model may enable it but must never disable it. **Never route this write around the plugin** through a psql/mysql-style command-line client, a throwaway script, or any other path (including another database plugin): read-only is the user safety boundary, and working around it is self-granted privilege escalation. If the write is genuinely required, tell the user what it does and why, and let them decide.',
   'result.readOnlyUserOnly': 'For safety, **disabling read-only mode is a user-only action** (the model may enable it, never lift it — that would be self-escalation). Ask the user to clear that environment\u2019s read-only switch in **Settings → DBHub Database Tools** (or the Configure action on that Plugins row).',
   'result.readOnlyOn': 'read-only mode enabled (env {env}): writes are rejected by dbhub (READONLY_VIOLATION).',
   'result.readOnlyOff': 'read-only mode disabled (env {env}).',

package/lib/index.mjs

@@ -42,6 +42,7 @@ import {
   cachedRows, resolveTestDsn,
 } from './mcp.mjs'
 import { registerCoreTools } from './tools.mjs'
+import { registerDbhubPolicy } from './policy.mjs'
 import { probeConnection, probeSshTunnel, hostTimeoutFor, PROBE_TIMEOUT_SSH_MS, defaultKeyNoteOf } from './adhoc.mjs'
 import { sweepTempToml } from './toml.mjs'
 import { detectDbhubCapabilities } from './capability.mjs'
@@ -53,6 +54,11 @@ import {
   normalizeSshOptions, mergeSshOptions,
 } from './config.mjs'
 import { setLocaleProvider, currentT } from './i18n.mjs'
+// Version metadata (plugin/dsh/runtime) and the plugin self-update check are
+// leaf modules (node builtins only), so importing them here cannot create a
+// dependency cycle.
+import { versionMeta } from './meta.mjs'
+import { createUpdateChecker } from './update.mjs'
 import * as state from './state.mjs'
 import * as options from './options.mjs'
 
@@ -82,6 +88,10 @@ const STATUS_DEFAULTS = {
   // entry no matter what this says, and hiding the entry never disables anything
   // (the settings page and the Plugins row stay reachable either way).
   showSidebarEntry: true,
+  // The user's own choice to let the plugin contribute its database-access
+  // policy to the system prompt (default ON). It removes that section only:
+  // every tool keeps working, and a disabled plugin contributes nothing anyway.
+  announceAccessPolicy: true,
   // Upstream dbhub capability probe (JSON string: {version, readonlyTools, ssh,
   // warning}). The UI uses it to disable the read-only / SSH controls with a
   // reason instead of letting the user configure something that cannot work.
@@ -96,6 +106,14 @@ const STATUS_DEFAULTS = {
   // persisted anywhere — the card only shows it while its own pending nonce
   // matches (a reload drops the pending map, so the result cannot stick).
   testResult: '',
+  // Version / update metadata (lib/meta.mjs, lib/update.mjs). `update` rides as
+  // a JSON string like `workspaces` — it is '' until the card asks for its first
+  // check, so boot never waits on the network. Nothing here is secret.
+  pluginVersion: '',
+  dshVersion: '',
+  dshModern: false,
+  runtime: 'web',
+  update: '',
 }
 
 // Prefer the real schemastery schema (standard path, present in every dsh
@@ -120,10 +138,16 @@ try {
     mode: z.string().default(STATUS_DEFAULTS.mode),
     updateIntervalDays: z.number().min(0).default(STATUS_DEFAULTS.updateIntervalDays),
     showSidebarEntry: z.boolean().default(STATUS_DEFAULTS.showSidebarEntry),
+    announceAccessPolicy: z.boolean().default(STATUS_DEFAULTS.announceAccessPolicy),
     capabilities: z.string().default(STATUS_DEFAULTS.capabilities),
     workspaces: z.string().default(STATUS_DEFAULTS.workspaces),
     configOp: z.string().default(STATUS_DEFAULTS.configOp),
     testResult: z.string().default(STATUS_DEFAULTS.testResult),
+    pluginVersion: z.string().default(STATUS_DEFAULTS.pluginVersion),
+    dshVersion: z.string().default(STATUS_DEFAULTS.dshVersion),
+    dshModern: z.boolean().default(STATUS_DEFAULTS.dshModern),
+    runtime: z.string().default(STATUS_DEFAULTS.runtime),
+    update: z.string().default(STATUS_DEFAULTS.update),
   })
   // schemastery 3.18.2 (shipped with dsh 0.1.6) has no `.volatile()`; the guard
   // keeps the declaration valid there, where the fields arrive as plain values.
@@ -134,6 +158,7 @@ try {
   CONFIG_SCHEMA = z.object({
     updateIntervalDays: volatileField(z.number().min(0)),
     showSidebarEntry: volatileField(z.boolean()),
+    announceAccessPolicy: volatileField(z.boolean()),
   })
 } catch (e) {
   const fallbackSchema = (value) => {
@@ -546,6 +571,22 @@ async function handleConfigOp(rawOp, ctx, subprocess, reportTest, publishFast) {
   return patches
 }
 
+// Card commands arrive as an object (the HTTP bridge posts `{ op: <command> }`)
+// or as a JSON string (on 0.1.x the settings document carries the single string
+// field `configOp`). Normalize both shapes in one place so the early
+// `updateCheck` branch in runOp can read the command; anything unparsable falls
+// through to handleConfigOp, which owns the "bad op" warning.
+function opObjectOf(rawOp) {
+  if (rawOp && typeof rawOp === 'object') return rawOp
+  if (typeof rawOp !== 'string') return undefined
+  try {
+    const parsed = JSON.parse(rawOp)
+    return parsed && typeof parsed === 'object' ? parsed : undefined
+  } catch (e) {
+    return undefined
+  }
+}
+
 // ── live host core: one merged view, fanned out to every active channel ───
 //
 // Publishing is channel-independent: the 0.1.x settings namespace and the HTTP
@@ -570,13 +611,29 @@ function createHostCore(ctx) {
   // then vanished".
   const mirror = createRowMirror()
   const sinks = new Set()
+  // Version metadata and the plugin self-update checker are Host-lifetime
+  // singletons: the installed version cannot change under a running process,
+  // and one checker instance is what makes the throttle and the in-flight
+  // dedupe work (a per-request instance would hit the registries on every
+  // publish). `updateJson` is the browser-facing snapshot — a JSON string, ''
+  // until the card asks for its first check, so boot never waits on a network.
+  const meta = versionMeta()
+  const updateChecker = createUpdateChecker({ currentVersion: meta.pluginVersion })
+  let updateJson = ''
+  // checkedAt of the snapshot already written to the log: a throttled check
+  // just reuses the last result, and logging it again on every page mount would
+  // turn the milestone line into noise.
+  let lastLoggedCheckAt = -1
 
   const view = () => ({
     ...state.snapshot(),
     ...options.snapshot(),
+    // pluginVersion / dshVersion / dshModern / runtime — plain strings/booleans.
+    ...meta,
     workspaces: JSON.stringify(latestSummaries()),
     testResult: lastTestResult,
     capabilities: capabilities,
+    update: updateJson,
     // The browser half needs this to address the plugin's own settings form
     // (`ctx.configForms.get(entryId)`) for option writes; '' when the entry
     // cannot be resolved, in which case it falls back to POST /options.
@@ -674,9 +731,55 @@ function createHostCore(ctx) {
       return {}
     }
   }
+  // Answer the card's {op:'updateCheck'} command. The checker owns the throttle
+  // and the in-flight dedupe, so repeated clicks/reloads cost one request burst;
+  // `force` bypasses the throttle (the card's explicit "check now"). The result
+  // is mirrored into `update` and published, then logged once — check() resolves
+  // on every failure and the guard here only covers a future regression.
+  const runUpdateCheck = async (force) => {
+    let snap
+    try {
+      snap = await updateChecker.check(force === true)
+    } catch (e) {
+      snap = {
+        latest: '',
+        latestSpec: '',
+        hasUpdate: false,
+        checkedAt: Date.now(),
+        source: '',
+        error: String((e && e.message) || e),
+      }
+    }
+    updateJson = JSON.stringify(snap)
+    publishMirror()
+    // One line per ACTUAL check; a throttled reuse keeps the previous line.
+    if (snap.checkedAt === lastLoggedCheckAt) return snap
+    lastLoggedCheckAt = snap.checkedAt
+    const current = meta.pluginVersion || '?'
+    if (snap.error) {
+      console.warn('[dsh-dbhub-live] ' + currentT('log.appUpdateFailed', { msg: snap.error, current }))
+    } else if (snap.hasUpdate) {
+      console.log('[dsh-dbhub-live] ' + currentT('log.appUpdate', { current, latest: snap.latest, source: snap.source }))
+    } else {
+      console.log('[dsh-dbhub-live] ' + currentT('log.appUpToDate', {
+        current,
+        latest: snap.latest || '?',
+        source: snap.source || '?',
+      }))
+    }
+    return snap
+  }
   // One card command, from whichever channel carried it. The caller owns the
   // follow-up republish; a write is already mirrored by publishFast.
   const runOp = async (rawOp) => {
+    // `updateCheck` is not a workspace command: no rows change and it touches the
+    // network, so it is intercepted BEFORE handleConfigOp (which would reject an
+    // unknown op). It still resolves [] — a command that patches no row.
+    const command = opObjectOf(rawOp)
+    if (command && command.op === 'updateCheck') {
+      await runUpdateCheck(command.force === true)
+      return []
+    }
     const patches = await handleConfigOp(rawOp, ctx, subprocessOf(), reportTest, publishFast)
     if (Array.isArray(patches) && patches.length > 0) publish()
     else publishMirror()
@@ -906,6 +1009,10 @@ export async function apply(ctx, config) {
   })
   const subprocess = ctx.get('subprocess')
   registerCoreTools(ctx, subprocess)
+  // The system-prompt policy is what keeps database access on these tools (and
+  // out of psql/scripts); it is optional by design and contributes nothing
+  // while the plugin is disabled.
+  registerDbhubPolicy(ctx)
   refreshToolCount()
 
   // One core, two channels: every state/option change replays the walk, and

package/lib/meta.mjs

@@ -0,0 +1,267 @@
+// dsh-dbhub-live: version metadata for the Host.
+//
+// Two independent questions live here:
+//   1. which version of THIS plugin is running (its own package.json), and
+//   2. which dsh release is hosting it, and whether that release is new enough
+//      for the modern UI contracts (>= 0.2.1 base version).
+//
+// Both are read once per Host process (the card publishes them as plain view
+// fields), so everything is cached and every failure degrades to '' / false —
+// a version probe must never be able to break the plugin.
+//
+// Dependency direction: this module is a LEAF (node builtins only). lib/index.mjs
+// imports it; nothing imports back, so no cycle can form.
+
+import { readFileSync, statSync } from 'node:fs'
+import { dirname, join, resolve } from 'node:path'
+
+/** This plugin's npm package name (also the npm update-check target). */
+export const PLUGIN_NAME = 'dsh-dbhub-live'
+
+/** The first dsh release with the modern client UI contracts. */
+export const DSH_MODERN_BASE = '0.2.1'
+
+/**
+ * Package names that identify the running dsh runtime when walking up from the
+ * process entry point. The CLI, the desktop runtime wrapper and the desktop app
+ * shell are all valid hosts.
+ */
+export const DSH_PACKAGE_NAMES = Object.freeze([
+  '@deepseek-ai/dsh',
+  '@deepseek-ai/dsh-desktop-runtime',
+  '@deepseek-ai/dsh-desktop',
+])
+
+// Accepts `v1.2.3`, `1.2.3-dev.1`, `1.2.3+build.5` and `1.2.3-rc.1+sha`.
+const SEMVER_RE = /^[vV]?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+([0-9A-Za-z.-]+))?$/
+
+const NUMERIC_RE = /^\d+$/
+
+/**
+ * Parse a semver string into comparable parts.
+ *
+ * Lenient on the leading `v` (release tags are usually written `v5.2.0`) and
+ * tolerant of any build metadata (which never participates in precedence), but
+ * strict about the core triplet and empty prerelease identifiers. Returns
+ * `undefined` for anything that is not semver — callers treat that as
+ * "unknown version", never as 0.0.0.
+ *
+ * @param {unknown} text
+ * @returns {{ major: number, minor: number, patch: number, prerelease: string[], raw: string } | undefined}
+ */
+export function parseSemver(text) {
+  if (typeof text !== 'string') return undefined
+  const raw = text.trim()
+  const match = SEMVER_RE.exec(raw)
+  if (!match) return undefined
+  const prerelease = match[4] ? match[4].split('.') : []
+  // "1.2.3-alpha..beta" is invalid semver: no identifier may be empty.
+  if (prerelease.length > 0 && prerelease.some((id) => id === '')) return undefined
+  return {
+    major: Number(match[1]),
+    minor: Number(match[2]),
+    patch: Number(match[3]),
+    prerelease,
+    raw,
+  }
+}
+
+function compareTriplet(a, b) {
+  if (a.major !== b.major) return a.major < b.major ? -1 : 1
+  if (a.minor !== b.minor) return a.minor < b.minor ? -1 : 1
+  if (a.patch !== b.patch) return a.patch < b.patch ? -1 : 1
+  return 0
+}
+
+/**
+ * Semver prerelease precedence (semver.org §11): a version WITHOUT prerelease
+ * outranks the same version WITH one; numeric identifiers compare numerically;
+ * numeric sorts below alphanumeric; alphanumeric compares in ASCII order; a
+ * longer identifier list wins when every shared identifier is equal.
+ */
+function comparePrerelease(a, b) {
+  if (a.length === 0 && b.length === 0) return 0
+  if (a.length === 0) return 1
+  if (b.length === 0) return -1
+  const shared = Math.min(a.length, b.length)
+  for (let i = 0; i < shared; i += 1) {
+    const left = a[i]
+    const right = b[i]
+    const leftNumeric = NUMERIC_RE.test(left)
+    const rightNumeric = NUMERIC_RE.test(right)
+    if (leftNumeric && rightNumeric) {
+      const l = Number(left)
+      const r = Number(right)
+      if (l !== r) return l < r ? -1 : 1
+      continue
+    }
+    // Numeric identifiers always have lower precedence than alphanumeric ones.
+    if (leftNumeric !== rightNumeric) return leftNumeric ? -1 : 1
+    if (left !== right) return left < right ? -1 : 1
+  }
+  if (a.length !== b.length) return a.length < b.length ? -1 : 1
+  return 0
+}
+
+function compareParsed(a, b) {
+  const core = compareTriplet(a, b)
+  if (core !== 0) return core
+  return comparePrerelease(a.prerelease, b.prerelease)
+}
+
+/**
+ * Semver precedence between two versions (strings or already-parsed objects).
+ * Invalid input compares as "incomparable" and yields 0 — this must never throw.
+ *
+ * @returns {-1|0|1}
+ */
+export function compareSemver(a, b) {
+  const left = typeof a === 'object' && a !== null ? a : parseSemver(a)
+  const right = typeof b === 'object' && b !== null ? b : parseSemver(b)
+  if (!left || !right) return 0
+  return compareParsed(left, right)
+}
+
+/**
+ * True when `candidate` is STRICTLY newer than `current` per semver precedence.
+ * Unknown on either side yields false: without a known current version an
+ * update cannot be claimed, so the card must not show an update banner.
+ */
+export function isNewer(candidate, current) {
+  const next = parseSemver(candidate)
+  const installed = parseSemver(current)
+  if (!next || !installed) return false
+  return compareParsed(next, installed) > 0
+}
+
+/**
+ * True when `version` has the same-or-newer numeric triplet than `base`
+ * (prerelease is ignored: `0.2.1-rc.2` counts as `0.2.1`). An unknown version is
+ * false — "cannot tell" must not be reported as "modern".
+ */
+export function atLeastBase(version, base = DSH_MODERN_BASE) {
+  const parsed = parseSemver(version)
+  const floor = parseSemver(base)
+  if (!parsed || !floor) return false
+  return compareTriplet(parsed, floor) >= 0
+}
+
+let cachedPluginVersion
+
+/**
+ * This plugin's own version, read from the package.json next to lib/.
+ * Cached for the process lifetime (an installed package never changes under a
+ * running Host); '' when the file is missing or its version is not semver.
+ */
+export function readPluginVersion() {
+  if (cachedPluginVersion !== undefined) return cachedPluginVersion
+  cachedPluginVersion = ''
+  try {
+    const pkg = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8'))
+    const version = pkg && typeof pkg.version === 'string' ? pkg.version.trim() : ''
+    cachedPluginVersion = parseSemver(version) ? version : ''
+  } catch (e) {
+    cachedPluginVersion = ''
+  }
+  return cachedPluginVersion
+}
+
+function isDirectory(abs) {
+  try {
+    return statSync(abs).isDirectory()
+  } catch (e) {
+    return false
+  }
+}
+
+/**
+ * Walk up from the running process entry point looking for an installed dsh
+ * package.json. Exported so tests can drive it against a temp layout and a fake
+ * argv entry instead of touching the real installation.
+ *
+ * @param {string|undefined} entryPath - usually `process.argv[1]`
+ * @param {{ maxDepth?: number, packageNames?: ReadonlyArray<string> }} [options]
+ * @returns {string} the package version, or '' when nothing matched
+ */
+export function walkDshVersion(entryPath, options = {}) {
+  const maxDepth = Number.isInteger(options.maxDepth) && options.maxDepth > 0 ? options.maxDepth : 8
+  const names = new Set(
+    Array.isArray(options.packageNames) && options.packageNames.length > 0
+      ? options.packageNames
+      : DSH_PACKAGE_NAMES,
+  )
+  if (typeof entryPath !== 'string' || entryPath.trim() === '') return ''
+  // `process.argv[1]` is normally a file, but a loader may hand over a directory
+  // or a path that does not exist yet; both resolve to a starting directory.
+  const abs = resolve(entryPath.trim())
+  let dir = isDirectory(abs) ? abs : dirname(abs)
+  for (let depth = 0; depth < maxDepth; depth += 1) {
+    try {
+      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'))
+      const version = pkg && typeof pkg.version === 'string' ? pkg.version.trim() : ''
+      if (pkg && typeof pkg.name === 'string' && names.has(pkg.name) && parseSemver(version)) {
+        return version
+      }
+    } catch (e) {
+      /* no package.json here (or unreadable/non-JSON): keep walking up */
+    }
+    const parent = dirname(dir)
+    if (!parent || parent === dir) break
+    dir = parent
+  }
+  return ''
+}
+
+/**
+ * Best-effort identity of the running dsh runtime.
+ *
+ * `desktop` is true under the packaged desktop app (Electron main process) or
+ * whenever the desktop shell exports its own version through the environment.
+ * The version is resolved from the installed dsh package.json first (the
+ * authoritative value) and from the desktop env var second.
+ *
+ * @returns {{ version: string, desktop: boolean }}
+ */
+export function detectDshRuntime() {
+  const envVersion = process.env && typeof process.env.DSH_CLIENT_VERSION === 'string'
+    ? process.env.DSH_CLIENT_VERSION.trim()
+    : ''
+  const desktop = Boolean(process.versions && process.versions.electron) || Boolean(envVersion)
+  let version = ''
+  try {
+    version = walkDshVersion(process.argv && process.argv[1], { maxDepth: 8 })
+  } catch (e) {
+    version = ''
+  }
+  if (!version && envVersion && parseSemver(envVersion)) version = envVersion
+  return { version, desktop }
+}
+
+/**
+ * The modern-UI gate: a resolved dsh >= 0.2.1 is modern; an UNRESOLVABLE
+ * version is modern only on the desktop runtime (it ships the modern UI by
+ * definition, and its package layout is the least predictable one). An unknown
+ * version on web is treated as legacy, which is the safe assumption for the old
+ * 0.1.x line.
+ */
+export function dshIsModern(runtime) {
+  const info = runtime && typeof runtime === 'object' ? runtime : {}
+  const version = typeof info.version === 'string' ? info.version : ''
+  if (parseSemver(version)) return atLeastBase(version, DSH_MODERN_BASE)
+  return Boolean(info.desktop)
+}
+
+/**
+ * The version fields the Host publishes, computed once per Host core:
+ * `{ pluginVersion, dshVersion, dshModern, runtime }`. Plain strings/booleans —
+ * nothing here is secret and nothing here needs the network.
+ */
+export function versionMeta() {
+  const runtime = detectDshRuntime()
+  return {
+    pluginVersion: readPluginVersion(),
+    dshVersion: runtime.version,
+    dshModern: dshIsModern(runtime),
+    runtime: runtime.desktop ? 'desktop' : 'web',
+  }
+}

package/lib/options.mjs

@@ -13,6 +13,14 @@
 // keeps working. It is ANDed with the plugin's enabled state on the client (a
 // disabled plugin contributes no entry at all), because the two switches mean
 // different things: "hide the entry" versus "turn the plugin off".
+//
+// `announceAccessPolicy` is the USER's choice to let the plugin contribute its
+// database-access policy to the system prompt. Default ON: an installed plugin
+// should be the route database work takes, and the policy is what keeps a model
+// from following a shell-level "recipe" around the read-only gate. Turning it
+// off removes that text only — every tool keeps working (the tool descriptions
+// and the read-only receipt still mention the boundary), so this is a prompt
+// preference, not a capability switch.
 
 import { loadPrefs, savePrefs } from './config.mjs'
 
@@ -20,6 +28,7 @@ const BUILTIN_DEFAULTS = {
   dbhubPackage: '@bytebase/dbhub',
   updateIntervalDays: 7,
   showSidebarEntry: true,
+  announceAccessPolicy: true,
 }
 
 function envNumber(name, fallback) {
@@ -41,6 +50,9 @@ const options = {
   showSidebarEntry: persisted.showSidebarEntry !== undefined
     ? persisted.showSidebarEntry
     : BUILTIN_DEFAULTS.showSidebarEntry,
+  announceAccessPolicy: persisted.announceAccessPolicy !== undefined
+    ? persisted.announceAccessPolicy
+    : BUILTIN_DEFAULTS.announceAccessPolicy,
 }
 
 const listeners = new Set()
@@ -70,12 +82,14 @@ export function snapshot() {
   return {
     updateIntervalDays: options.updateIntervalDays,
     showSidebarEntry: options.showSidebarEntry,
+    announceAccessPolicy: options.announceAccessPolicy,
   }
 }
 
 /**
  * Read one option by id ('dbhubPackage' is internal-only).
- * @param id - 'dbhubPackage' | 'updateIntervalDays' | 'showSidebarEntry'.
+ * @param id - 'dbhubPackage' | 'updateIntervalDays' | 'showSidebarEntry' |
+ *   'announceAccessPolicy'.
  * @returns the current value.
  */
 export function get(id) {
@@ -87,6 +101,7 @@ export function get(id) {
 const VALIDATORS = {
   updateIntervalDays: (v) => typeof v === 'number' && Number.isFinite(v) && v >= 0,
   showSidebarEntry: (v) => typeof v === 'boolean',
+  announceAccessPolicy: (v) => typeof v === 'boolean',
 }
 
 /**