@foggy-projects/deepseek-harness-plugin 0.4.2-rc.2 → 0.4.2-rc.3

package/README.md

@@ -7,7 +7,7 @@ are downloaded only when the user selects **Initialize and start** (or the
 equivalent component action). Existing installations are not silently changed
 when the plugin package is upgraded.
 
-The `0.4.2-rc.2` compatibility candidate targets DeepSeek Harness `0.1.7-rc.2`
+The `0.4.2-rc.3` compatibility candidate targets DeepSeek Harness `0.1.7-rc.2`
 and requires a system Node.js `>=24.0.0`. Foggy's Java Launcher uses a system
 Java 17+. Foggy manages its own pinned Python 3.12 runtime
 inside the per-user component directory; it does not require a system Python,
@@ -17,7 +17,7 @@ modify `PATH`, or register Python globally. Advanced users may explicitly set
 ## Local release-candidate installation
 
 ```powershell
-dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.2-rc.2.tgz
+dsh plugin --profile web add --workspace-root ./foggy-projects-deepseek-harness-plugin-0.4.2-rc.3.tgz
 ```
 
 Restart `dsh web`, use the browser it opens (or the complete printed URL,
@@ -28,11 +28,11 @@ Install the exact DSH 0.1.7-rc.2 compatibility candidate
 so the stable `beta` channel is not changed:
 
 ```powershell
-dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-plugin@0.4.2-rc.2
+dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-plugin@0.4.2-rc.3
 ```
 
 The `dsh017` npm dist-tag points to the most recently published DSH 0.1.7
-candidate (`0.4.2-rc.2` at this release). Check the resolved version before
+candidate (`0.4.2-rc.3` at this release). Check the resolved version before
 using this moving tag:
 
 ```powershell
@@ -130,6 +130,15 @@ same wildcard binding used by the Java server, so a conflicting application or W
 port proxy produces an immediate, high-visibility error instead of a readiness timeout.
 The CLI and Skills resolve the resulting stable Runtime URL from managed state.
 
+For a successful standard QueryModel DSL call made through the native
+`foggy_query` tool, Harness shows a query card with the model, namespace,
+row count, DSL, and execution result. Its **Open DataViewer** action creates
+a local preview URL only when clicked; the query itself does not create one.
+The preview re-executes the DSL against the current model and data rather than
+freezing the original rows. In the lite Runtime the preview cache is bounded,
+process-local, and lost on restart. CTE calls are not included in this first
+DataViewer integration.
+
 This beta remains a local dev/test integration. It does not automatically extend
 local credentials or approvals into a formal environment. Production model
 publication should use a separate manual or dedicated deployment workflow with
@@ -139,6 +148,8 @@ rollback plan.
 See [`docs/PUBLIC-BETA-READINESS.md`](./docs/PUBLIC-BETA-READINESS.md) for the
 tested public Beta scope, release gates, and stable-release blockers.
 The DSH 0.1.7-rc.2 compatibility candidate is documented in
+[`docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.3.md`](./docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.3.md).
+The previous DSH 0.1.7-rc.2 candidate is documented in
 [`docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.2.md`](./docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.2.md).
 The earlier DSH 0.1.5-rc.2 candidate is documented in
 [`docs/RELEASE-CANDIDATE-0.4.1-DSH-0.1.5-RC.1.md`](./docs/RELEASE-CANDIDATE-0.4.1-DSH-0.1.5-RC.1.md).

package/docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.3.md

@@ -0,0 +1,34 @@
+# Foggy DeepSeek Harness plugin 0.4.2-rc.3
+
+This pre-release targets DeepSeek Harness `0.1.7-rc.2` on the `dsh017` npm
+channel. It keeps the `beta`, `rc`, and `dsh015` channels unchanged.
+
+## Changes since 0.4.2-rc.2
+
+- Add a native `foggy_query` tool for bounded, read-only standard QueryModel DSL
+  validation and execution. Successful calls render a Harness card with the
+  model, namespace, row count, DSL, SQL, and result.
+- Create a DataViewer preview URL only when the card's **Open DataViewer**
+  action is clicked. Links are short-lived local development previews, not
+  frozen result snapshots. An expired link can be regenerated from the card.
+- Update the managed Launcher to `0.1.22`. Its lite profile serves the existing
+  DataViewer UI using a bounded in-memory cache without MongoDB, and its start
+  scripts bind to loopback. Runtime restarts invalidate preview links.
+- Do not claim CTE preview support in this release. Existing CTE execution
+  remains available through its prior CLI path without a DataViewer card.
+
+## Acceptance scope
+
+- Plugin checks: `npm run check`, Node tests, Python onboarding tests, and an
+  isolated DSH `0.1.7-rc.2` web boot with the Foggy settings tab visible.
+- Launcher: formal release gate, default and Analytics Console smokes, six
+  GitHub assets, and SHA-256 verification.
+- End-to-end DSL: an isolated Java Runtime with SQLite demo data validates and
+  executes a QueryModel query. A click-generated DataViewer link shows actual
+  columns and six rows in the browser.
+
+Install the exact version with:
+
+```powershell
+dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-plugin@0.4.2-rc.3
+```

package/docs/WINDOWS-BETA-ACCEPTANCE.md

@@ -1,7 +1,7 @@
 # Native Windows Beta acceptance
 
 This runbook validates DeepSeek Harness `0.1.7-rc.2` with Foggy plugin
-`0.4.2-rc.2` on a clean 64-bit Windows 10 or Windows 11 machine. Use a local
+`0.4.2-rc.3` on a clean 64-bit Windows 10 or Windows 11 machine. Use a local
 directory that is not synchronized by OneDrive.
 
 ## Prerequisites
@@ -29,7 +29,7 @@ Set-Location C:\FoggyAcceptance
 
 npx --yes --package=@deepseek-ai/dsh@0.1.7-rc.2 --package=pnpm@11.7.0 `
   dsh plugin --profile web add --workspace-root `
-  "@foggy-projects/deepseek-harness-plugin@0.4.2-rc.2"
+  "@foggy-projects/deepseek-harness-plugin@0.4.2-rc.3"
 
 npx --yes --package=@deepseek-ai/dsh@0.1.7-rc.2 --package=pnpm@11.7.0 dsh web
 ```
@@ -66,9 +66,9 @@ Expected component state:
 
 - Python 3.12.13, source `Foggy private`;
 - CLI 0.1.23;
-- Launcher 0.1.21;
+- Launcher 0.1.22;
 - analysis/query Skills 0.1.18;
-- onboarding Skill 0.4.2-rc.2;
+- onboarding Skill 0.4.2-rc.3;
 - Java 17+ available;
 - native DSH Skill registration available.
 

package/experience/linux/prepare.sh

@@ -3,7 +3,7 @@ set -euo pipefail
 
 DSH_VERSION="0.1.7-rc.2"
 PNPM_VERSION="11.7.0"
-PLUGIN_VERSION="0.4.2-rc.2"
+PLUGIN_VERSION="0.4.2-rc.3"
 PLUGIN_REF="v${PLUGIN_VERSION}"
 PLUGIN_REPOSITORY="https://github.com/foggy-projects/foggy-deepseek-harness-plugin.git"
 

package/lib/client.js

@@ -17,6 +17,15 @@ window.__ModuleLoader__.load({
         return { port }
       },
     }
+    const viewerPreviewInputSchema = {
+      parse: (value) => {
+        if (!value || typeof value.model !== 'string' || typeof value.namespace !== 'string'
+            || !value.payload || typeof value.payload !== 'object' || Array.isArray(value.payload)) {
+          throw new Error('Invalid DataViewer preview request')
+        }
+        return value
+      },
+    }
     const descriptor = (method, parameters = []) => ({
       id: `@foggy-projects/deepseek-harness-plugin#foggyIntegration/${method}`,
       service: 'foggyIntegration',
@@ -50,6 +59,15 @@ window.__ModuleLoader__.load({
             create: () => runtimeSettingsInputSchema,
           },
         }]),
+        descriptor('createViewerPreview', [{
+          name: 'input', wire: 'input', source: 'json',
+          codec: {
+            mode: 'strict',
+            typeSymbol: '@foggy-projects/deepseek-harness-plugin#FoggyViewerPreviewInput',
+            schema: viewerPreviewInputSchema,
+            create: () => viewerPreviewInputSchema,
+          },
+        }]),
       ],
     }
 
@@ -149,6 +167,16 @@ window.__ModuleLoader__.load({
       queryWarningSummary: 'Runtime 在 WARN 模式下忽略了未知的查询属性，查询仍已执行。请检查告警代码与证据后决定是否修正模型或请求。',
       queryWarningCodes: '告警代码',
       queryWarningEvidence: '证据目录',
+      queryCardTitle: 'Foggy DSL 查询',
+      queryCardRunning: '正在校验并执行…',
+      queryCardDone: '校验与查询成功',
+      queryCardFailed: '查询失败；可展开查看错误',
+      queryCardRows: '返回行数',
+      queryCardDetails: '查看 DSL 与执行结果',
+      queryCardOpen: '打开 DataViewer 数据页',
+      queryCardOpening: '正在生成预览链接…',
+      queryCardPreviewHint: '链接仅在点击时生成，默认有效期 60 分钟；Runtime 重启后失效。这是开发预览，非结果快照。',
+      queryCardUnsupported: '当前查询不支持 DataViewer 预览，可继续查看查询结果。',
       stepPlanned: '规划',
       stepDatasourceConfigured: '数据库连接',
       stepDatasourceVerified: '连接验证',
@@ -274,6 +302,16 @@ window.__ModuleLoader__.load({
       queryWarningSummary: 'In WARN mode, Runtime ignored unknown query properties and continued. Review the warning codes and evidence before deciding whether to change the model or request.',
       queryWarningCodes: 'Warning codes',
       queryWarningEvidence: 'Evidence directory',
+      queryCardTitle: 'Foggy DSL query',
+      queryCardRunning: 'Validating and executing…',
+      queryCardDone: 'Validation and query succeeded',
+      queryCardFailed: 'Query failed; expand for details',
+      queryCardRows: 'Rows',
+      queryCardDetails: 'Show DSL and execution result',
+      queryCardOpen: 'Open DataViewer',
+      queryCardOpening: 'Creating preview link…',
+      queryCardPreviewHint: 'The link is created on click, expires after 60 minutes or a Runtime restart, and is a development preview rather than a result snapshot.',
+      queryCardUnsupported: 'DataViewer preview is unavailable for this query; the query result remains available.',
       stepPlanned: 'Plan',
       stepDatasourceConfigured: 'Database connection',
       stepDatasourceVerified: 'Connection test',
@@ -779,6 +817,62 @@ window.__ModuleLoader__.load({
       ] })
     }
 
+    function FoggyQueryCard({ phase, block, api, t }) {
+      const [preview, setPreview] = useState({ loading: false, url: '', expiresAt: 0, error: '' })
+      let args = null
+      let result = null
+      let outputText = ''
+      try {
+        const raw = phase === 'result' ? block.call?.argsRaw : phase === 'start' ? block.argsRaw : null
+        if (raw) args = JSON.parse(raw)
+        if (phase === 'result') {
+          outputText = block.content?.find((item) => item.type === 'text')?.text || ''
+          if (outputText) result = JSON.parse(outputText)
+        }
+      } catch {}
+      const success = phase === 'result' && !block.isError && Boolean(result?.execution?.success)
+      const rows = result?.execution?.data?.items?.length
+      const sql = result?.execution?.data?.debug?.extra?.sql
+      const payload = args?.payload
+      const supported = success && payload && Array.isArray(payload.columns) && payload.columns.length > 0
+        && !('executable_plan' in payload) && !('executablePlan' in payload) && payload.route !== 'DSL_CTE'
+        && Object.keys(payload).every((key) => ['columns', 'slice', 'groupBy', 'orderBy', 'calculatedFields', 'extData', 'start', 'limit', 'returnTotal'].includes(key))
+        && ['slice', 'groupBy', 'orderBy', 'calculatedFields'].every((key) => !payload[key] || Array.isArray(payload[key]) && payload[key].every((item) => item && typeof item === 'object' && !Array.isArray(item)))
+      async function openViewer() {
+        const pendingTab = window.open('about:blank', '_blank')
+        setPreview({ loading: true, url: '', expiresAt: 0, error: '' })
+        try {
+          const value = unwrap(await api.createViewerPreview({ model: args.model, namespace: args.namespace, payload }), 'createViewerPreview')
+          setPreview({ loading: false, url: value.url, expiresAt: Date.now() + value.expiresInMinutes * 60_000, error: '' })
+          if (pendingTab) pendingTab.location.replace(value.url)
+        } catch (error) {
+          if (pendingTab) pendingTab.close()
+          setPreview({ loading: false, url: '', expiresAt: 0, error: String(error?.message || error) })
+        }
+      }
+      const box = { border: '1px solid var(--dsw-alias-border-l2)', borderRadius: 10, padding: 12, margin: '8px 0', fontSize: 13 }
+      return jsxs('section', { style: box, children: [
+        jsx('strong', { children: `${t('queryCardTitle')}${args?.model ? ` · ${args.model}` : ''}` }),
+        jsx('p', { style: { margin: '6px 0', color: 'var(--dsw-alias-label-secondary)' }, children: success ? `${t('queryCardDone')}${Number.isInteger(rows) ? ` · ${t('queryCardRows')} ${rows}` : ''}` : phase === 'result' ? t('queryCardFailed') : t('queryCardRunning') }),
+        args?.namespace ? jsx('code', { children: `namespace: ${args.namespace}` }) : null,
+        success ? jsxs('details', { style: { marginTop: 8 }, children: [
+          jsx('summary', { style: { cursor: 'pointer' }, children: t('queryCardDetails') }),
+          sql ? jsx('pre', { style: { maxHeight: 180, overflow: 'auto', whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: sql }) : null,
+          jsx('pre', { style: { maxHeight: 260, overflow: 'auto', whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: JSON.stringify({ dsl: payload, validation: result.validation, execution: result.execution }, null, 2).slice(0, 30000) }),
+        ] }) : null,
+        phase === 'result' && !success ? jsxs('details', { style: { marginTop: 8 }, children: [
+          jsx('summary', { style: { cursor: 'pointer' }, children: t('queryCardFailed') }),
+          jsx('pre', { style: { maxHeight: 260, overflow: 'auto', whiteSpace: 'pre-wrap', overflowWrap: 'anywhere' }, children: (outputText || JSON.stringify(block)).slice(0, 6000) }),
+        ] }) : null,
+        supported ? jsxs('div', { style: { marginTop: 10 }, children: [
+          jsx('button', { type: 'button', disabled: preview.loading, onClick: openViewer, children: preview.loading ? t('queryCardOpening') : t('queryCardOpen') }),
+          jsx('p', { style: { margin: '5px 0', color: 'var(--dsw-alias-label-tertiary)', fontSize: 11 }, children: t('queryCardPreviewHint') }),
+          preview.url && Date.now() < preview.expiresAt ? jsx('a', { href: preview.url, target: '_blank', rel: 'noopener noreferrer', children: preview.url }) : null,
+          preview.error ? jsx('p', { role: 'alert', style: { color: 'var(--dsw-alias-state-error-primary)' }, children: preview.error }) : null,
+        ] }) : success ? jsx('p', { style: { margin: '8px 0 0', color: 'var(--dsw-alias-label-tertiary)' }, children: t('queryCardUnsupported') }) : null,
+      ] })
+    }
+
     const inject = ['slots', 'locale', 'remote']
 
     async function apply(ctx) {
@@ -788,6 +882,11 @@ window.__ModuleLoader__.load({
       const t = ctx.locale.bind(NS)
       ctx.inject(['remote.foggyIntegration'], (remoteCtx) => {
         const api = remoteCtx.remote.foggyIntegration
+        remoteCtx.slots.inject('tool.call.toolview', () => remoteCtx.slots.register({
+          name: 'tool.call.toolview',
+          key: 'foggy_query',
+          inject: () => ({ api, t }),
+        }, FoggyQueryCard))
         remoteCtx.slots.inject('settings.plugins.tab', () => remoteCtx.slots.register({
           name: 'settings.plugins.tab',
           id: 'foggy',

package/lib/index.js

@@ -10,6 +10,8 @@ import { writeJsonAtomic } from './atomic-json.js'
 import { ensurePythonRuntime, probePythonRuntime } from './python-runtime.js'
 import { compatible, compatibleNode } from './version.js'
 import { enrichRuntimeStartFailure } from './diagnostics.js'
+import { createFoggyQueryTool, managedConnection } from './query-tool.js'
+import { createViewerPreview } from './viewer-preview.js'
 import {
   DEFAULT_RUNTIME_PORT,
   readRuntimeSettings,
@@ -210,7 +212,7 @@ function operationView(operation) {
 }
 
 export class FoggyIntegrationGateway extends TypertRemoteService {
-  static inject = ['skills']
+  static inject = ['skills', 'tools']
 
   operation = null
   skillProviderControl = null
@@ -222,9 +224,15 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       this.skillProviderControl = control
       return createFoggySkillProvider({ installRoot: roots.installRoot, versionsFile })
     })
+    ctx.tools.register(createFoggyQueryTool(roots))
     for (const initialize of markerInitializers) initialize.call(this)
   }
 
+  async createViewerPreview(input) {
+    const { runtimeUrl } = await managedConnection(defaultRoots())
+    return createViewerPreview(input, runtimeUrl)
+  }
+
   async status() {
     const roots = defaultRoots()
     const statePath = join(roots.installRoot, 'install-state.json')
@@ -672,6 +680,7 @@ for (const method of [
   'status', 'plan', 'initialize', 'initializeAndStart', 'repair', 'updateComponents', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill', 'repairSemanticQuerySkill',
   'migrateProfiles', 'diagnostics', 'runtimeStart', 'runtimeStop',
   'saveRuntimeSettings',
+  'createViewerPreview',
 ]) {
   Remote(method)(FoggyIntegrationGateway.prototype[method], {
     kind: 'method',

package/lib/query-tool.js

@@ -0,0 +1,104 @@
+import { execFile } from 'node:child_process'
+import { mkdtemp, readFile, rmdir, unlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { promisify } from 'node:util'
+import { defineTool } from '@deepseek-ai/dsh-tools'
+
+const execFileAsync = promisify(execFile)
+const identifier = /^[A-Za-z0-9_.-]{1,128}$/
+
+export function assertStandardDsl(payload) {
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) throw new Error('Query DSL must be a JSON object')
+  if (payload.route === 'DSL_CTE' || 'executable_plan' in payload || 'executablePlan' in payload) {
+    throw new Error('CTE preview is not supported in this release; use a standard QM DSL query')
+  }
+  if (!Array.isArray(payload.columns) || payload.columns.length === 0 || !payload.columns.every((item) => typeof item === 'string')) {
+    throw new Error('Standard QM DSL requires non-empty columns')
+  }
+}
+
+export function previewPayload(payload) {
+  assertStandardDsl(payload)
+  const supported = new Set(['columns', 'slice', 'groupBy', 'orderBy', 'calculatedFields', 'extData'])
+  const unsupported = Object.keys(payload).filter((key) => !supported.has(key) && !['start', 'limit', 'returnTotal'].includes(key))
+  if (unsupported.length) throw new Error(`DataViewer preview does not support: ${unsupported.join(', ')}`)
+  for (const key of ['slice', 'groupBy', 'orderBy', 'calculatedFields']) {
+    if (payload[key] !== undefined && (!Array.isArray(payload[key]) || payload[key].some((item) => !item || typeof item !== 'object' || Array.isArray(item)))) {
+      throw new Error(`DataViewer preview requires object-form ${key} entries`)
+    }
+  }
+  return Object.fromEntries([...supported].filter((key) => payload[key] !== undefined).map((key) => [key, payload[key]]))
+}
+
+export function safeRuntimeUrl(value) {
+  const url = new URL(value)
+  if (url.protocol !== 'http:' || !['127.0.0.1', 'localhost', '[::1]'].includes(url.hostname)
+      || url.username || url.password || url.pathname !== '/' || url.search || url.hash) {
+    throw new Error('Managed Runtime URL must be a plain loopback HTTP origin')
+  }
+  return url.origin
+}
+
+export async function managedConnection(roots) {
+  const install = JSON.parse(await readFile(join(roots.installRoot, 'install-state.json'), 'utf8'))
+  const runtime = JSON.parse(await readFile(join(roots.dataRoot, 'runtime-state.json'), 'utf8'))
+  if (!install.cli?.command) throw new Error('Foggy CLI is not installed')
+  return { cli: install.cli.command, runtimeUrl: safeRuntimeUrl(runtime.runtimeUrl) }
+}
+
+async function cliJson(cli, runtimeUrl, namespace, command, signal) {
+  const { stdout } = await execFileAsync(cli, ['--base-url', runtimeUrl, '--namespace', namespace, '--output', 'json', ...command], {
+    signal,
+    windowsHide: true,
+    timeout: 120_000,
+    maxBuffer: 8 * 1024 * 1024,
+  })
+  const value = JSON.parse(stdout.trim())
+  if (value?.success !== true) throw new Error(value?.error?.message || value?.error?.code || 'Foggy query failed')
+  return value
+}
+
+export function createFoggyQueryTool(roots) {
+  return defineTool({
+    name: 'foggy_query',
+    description: 'Validate and execute a bounded, read-only standard Foggy QueryModel DSL query against the managed local Runtime. On success Harness shows a query card; its DataViewer preview link is created only if the user clicks Open DataViewer. CTE is not supported here.',
+    parameters: {
+      model: { type: 'string', required: true, description: 'Published Foggy QueryModel name' },
+      namespace: { type: 'string', required: true, description: 'Foggy namespace' },
+      payload: { type: 'object', additionalProperties: true, required: true, description: 'Standard QueryModel DSL, including explicit columns and bounded limit' },
+    },
+    output: {
+      schema: { type: 'object', additionalProperties: false, properties: {
+        model: { type: 'string', required: true },
+        namespace: { type: 'string', required: true },
+        validation: { type: 'json', required: true },
+        execution: { type: 'json', required: true },
+      } },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    timeoutMs: 150_000,
+    async execute({ model, namespace, payload }, exec) {
+      if (!identifier.test(model) || !identifier.test(namespace)) throw new Error('Invalid model or namespace')
+      assertStandardDsl(payload)
+      if (!Number.isInteger(payload.limit) || payload.limit < 1 || payload.limit > 100) {
+        throw new Error('Query DSL limit must be an integer from 1 to 100')
+      }
+      const { cli, runtimeUrl } = await managedConnection(roots)
+      const directory = await mkdtemp(join(tmpdir(), 'foggy-dsh-query-'))
+      const payloadPath = join(directory, 'query.json')
+      try {
+        await writeFile(payloadPath, JSON.stringify(payload), { encoding: 'utf8', flag: 'wx' })
+        const validation = await cliJson(cli, runtimeUrl, namespace, ['query', 'validate', model, '--payload', payloadPath], exec.signal)
+        const execution = await cliJson(cli, runtimeUrl, namespace, ['query', 'execute', model, '--payload', payloadPath], exec.signal)
+        return { model, namespace, validation, execution }
+      } finally {
+        await unlink(payloadPath).catch(() => {})
+        await rmdir(directory).catch(() => {})
+      }
+    },
+    presentCall({ model }) {
+      return { card: 'generic', title: `Foggy DSL · ${model}`, kind: 'read' }
+    },
+  })
+}

package/lib/remote-descriptor.js

@@ -4,6 +4,11 @@ const resultSchema = z.unknown()
 const runtimeSettingsInputSchema = z.object({
   port: z.number().int().min(1024).max(65535),
 }).strict()
+const viewerPreviewInputSchema = z.object({
+  model: z.string(),
+  namespace: z.string(),
+  payload: z.record(z.string(), z.unknown()),
+}).strict()
 
 function strictCodec(typeSymbol, schema) {
   return {
@@ -45,4 +50,10 @@ export const descriptors = [
     source: 'json',
     codec: strictCodec('@foggy-projects/deepseek-harness-plugin#FoggyRuntimeSettingsInput', runtimeSettingsInputSchema),
   }]),
+  descriptor('createViewerPreview', [{
+    name: 'input',
+    wire: 'input',
+    source: 'json',
+    codec: strictCodec('@foggy-projects/deepseek-harness-plugin#FoggyViewerPreviewInput', viewerPreviewInputSchema),
+  }]),
 ]

package/lib/viewer-preview.js

@@ -0,0 +1,27 @@
+import { previewPayload, safeRuntimeUrl } from './query-tool.js'
+
+const identifier = /^[A-Za-z0-9_.-]{1,128}$/
+
+export async function createViewerPreview({ model, namespace, payload }, runtimeUrl, fetcher = fetch) {
+  if (!identifier.test(model) || !identifier.test(namespace)) throw new Error('Invalid model or namespace')
+  const origin = safeRuntimeUrl(runtimeUrl)
+  const body = { model, namespace, title: `${model} · Harness preview`, payload: previewPayload(payload) }
+  const response = await fetcher(`${origin}/data-viewer/api/query/create`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json' },
+    body: JSON.stringify(body),
+    signal: AbortSignal.timeout(12_000),
+  })
+  if (!response.ok) throw new Error(`DataViewer unavailable (HTTP ${response.status}); update and restart the managed Runtime`)
+  const envelope = await response.json()
+  const result = envelope?.data
+  if (envelope?.code !== 200 || result?.success !== true || typeof result.viewerUrl !== 'string') {
+    throw new Error(envelope?.msg || result?.error || 'DataViewer did not return a preview link')
+  }
+  const url = new URL(result.viewerUrl, origin)
+  if (url.origin !== origin || !url.pathname.startsWith(`/data-viewer/view/${encodeURIComponent(model)}/`)
+      || url.username || url.password || url.search || url.hash) {
+    throw new Error('DataViewer returned an unexpected preview URL')
+  }
+  return { success: true, url: url.href, queryId: result.queryId, expiresInMinutes: 60 }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foggy-projects/deepseek-harness-plugin",
-  "version": "0.4.2-rc.2",
+  "version": "0.4.2-rc.3",
   "description": "Foggy Java data analysis engine integration for DeepSeek Harness",
   "keywords": [
     "deepseek-harness",
@@ -41,6 +41,7 @@
     "docs/RELEASE-CANDIDATE-0.4.0-RC.3.md",
     "docs/RELEASE-CANDIDATE-0.4.1-DSH-0.1.5-RC.1.md",
     "docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.2.md",
+    "docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.3.md",
     "docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.1.md",
     "docs/COMMUNITY-MARKETPLACES.md",
     "docs/WINDOWS-BETA-ACCEPTANCE.md",
@@ -61,11 +62,13 @@
         "@deepseek-ai/dsh-api-remotes",
         "@deepseek-ai/dsh-client-locale",
         "@deepseek-ai/dsh-client-ui-settings",
-        "@deepseek-ai/dsh-client-ui-settings-plugins"
+        "@deepseek-ai/dsh-client-ui-settings-plugins",
+        "@deepseek-ai/dsh-client-ui-tool"
       ]
     }
   },
   "dependencies": {
+    "@deepseek-ai/dsh-tools": "0.1.7-rc.2",
     "zod": "^4.4.3"
   },
   "peerDependencies": {
@@ -74,11 +77,12 @@
     "@deepseek-ai/dsh-client-locale": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-client-ui-settings": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-tool": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-skill": "^0.1.7-rc.2",
     "@deepseek-ai/dsh-typert-protocol": "^0.1.7-rc.2"
   },
   "scripts": {
-    "check": "node --check lib/index.js && node --check lib/atomic-json.js && node --check lib/diagnostics.js && node --check lib/python-runtime.js && node --check lib/runtime-settings.js && node --check lib/skill-provider.js && node --check lib/client.js && node --check lib/typert.js && node --check lib/remote.js",
-    "test": "node --test test/package.test.js && node test/run-onboarding-tests.js"
+    "check": "node --check lib/index.js && node --check lib/query-tool.js && node --check lib/viewer-preview.js && node --check lib/atomic-json.js && node --check lib/diagnostics.js && node --check lib/python-runtime.js && node --check lib/runtime-settings.js && node --check lib/skill-provider.js && node --check lib/client.js && node --check lib/typert.js && node --check lib/remote.js",
+    "test": "node --test test/package.test.js test/viewer-preview.test.js && node test/run-onboarding-tests.js"
   }
 }

package/skills/foggy-deepseek-onboarding/SKILL.md

@@ -60,6 +60,12 @@ are authoritative; do not copy the Skill into the current workspace.
 6. Iterate through model validation, Bundle registration/update, model refresh/describe, query
    validation, and bounded query execution. Development publication means making the local model
    directory effective in this local Runtime; it is not a production release.
+   For the final user-facing standard DSL query in Harness, use the native `foggy_query` tool when
+   available (explicit namespace, published QM, `columns`, and `limit` of 1–100). It validates and
+   executes, then displays a query card. The card creates a DataViewer preview link only if the user
+   clicks its button; never pre-create links for every query. This first version does not support
+   `DSL_CTE` or `executable_plan` in the native tool. Continue using the documented CLI route for
+   CTE queries and do not claim they have a DataViewer preview.
    A successful response may still contain Runtime `warnings`. Preserve and report their stable facts
    (`code`, `path`, `message`, `suggestedNextAction`, `safeToAutoRepair`, `normalizedFragment`,
    `docsRef`, and `details.allowedProperties`)

package/skills/foggy-deepseek-onboarding/assets/versions.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "foggy-deepseek-onboarding-versions/v1",
-  "packageVersion": "0.4.2-rc.2",
-  "validatedAt": "2026-09-27",
+  "packageVersion": "0.4.2-rc.3",
+  "validatedAt": "2026-09-28",
   "components": {
     "deepseekHarness": {
       "version": "0.1.7-rc.2",
@@ -66,39 +66,39 @@
       }
     },
     "launcher": {
-      "version": "0.1.21",
+      "version": "0.1.22",
       "minimumJavaVersion": "17.0.0",
       "runtimeApiContract": "foggy-runtime-api/v1",
       "assets": [
         {
-          "file": "foggy-runtime-launcher-0.1.21.jar",
-          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.21/foggy-runtime-launcher-0.1.21.jar",
-          "sha256": "0b5002e40633f4606b0f5d3adbcd734ad4a11d8204decab162bb53b6ab28b3b3"
+          "file": "foggy-runtime-launcher-0.1.22.jar",
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.22/foggy-runtime-launcher-0.1.22.jar",
+          "sha256": "c26d21ff50323d6adc3124e084462f8381407c6f79802cefac90f4ddafa00dca"
         },
         {
           "file": "start-foggy-runtime.ps1",
-          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.21/start-foggy-runtime.ps1",
-          "sha256": "8609f8c60bad9e56460b132e1bd6c699d4ebf47cf591c3e6bc37bc8563d7de5a"
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.22/start-foggy-runtime.ps1",
+          "sha256": "dcfaa3d4e512e72f16e6d44dda00ae27f0cfc164763cac73c0ee63fd4b7236bc"
         },
         {
           "file": "start-foggy-runtime.sh",
-          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.21/start-foggy-runtime.sh",
-          "sha256": "fa844f422473ba00a31cf801092b0fe4ef93fe8697656a9063e0ec27dacef715"
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.22/start-foggy-runtime.sh",
+          "sha256": "fa304f66679f0323157ea7948fd95fb1082264f115b9b4d688b1995c24b3c1d7"
         },
         {
           "file": "README-foggy-runtime-launcher.md",
-          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.21/README-foggy-runtime-launcher.md",
-          "sha256": "6b63cafe798e19c255a043e15e64109f6fb3252aee3fb9c37ab6a66d9adbf3cf"
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.22/README-foggy-runtime-launcher.md",
+          "sha256": "43711229b425f13fa242d58916ef17cbd3dcebe4fc18b951aa9bf4befc056c26"
         },
         {
           "file": "runtime-launcher-manifest.json",
-          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.21/runtime-launcher-manifest.json",
-          "sha256": "1591804035bbf589912907195c74746bf97edff3b9e6ebd7d569ecc0e5aebed7"
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.22/runtime-launcher-manifest.json",
+          "sha256": "2b9efb82e8f954f2407f36ae419984068d384e1e0b86796ccfad0981dc7b2a30"
         },
         {
           "file": "SHA256SUMS",
-          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.21/SHA256SUMS",
-          "sha256": "6e03f8861176d73be22c4c7c6f6345a68e49aacfb5375cd5cf2c54f1dc4cbe5d"
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.22/SHA256SUMS",
+          "sha256": "51dc530e275bc1c9e9c73e9fce13d236fd0c5e3bfcebd9b03b837c5bc05e59f8"
         }
       ]
     },