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

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.5` 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.5.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.5
 ```
 
 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.5` at this release). Check the resolved version before
 using this moving tag:
 
 ```powershell
@@ -130,6 +130,27 @@ 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 compact result card below the completed
+reply, outside the folded tool trace. A visible "Generated by Foggy plugin"
+label distinguishes this programmatic record of executed results from the AI
+reply. The card shows the model, namespace, row count, an optional five-row
+result preview with DSL/SQL details, and **View data**. If a turn has more than six
+successful queries, the first six are shown until the user expands the list.
+The detailed DSL and execution record remains in the tool trace. Clicking
+**View data** creates a fresh local preview URL each time; the historical card
+remains usable after an earlier URL expires, as long as the Harness transcript
+and the Runtime/model are still available. Individual URLs are not permanent.
+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. DataViewer currently displays model-backed fields and
+may omit ad-hoc aggregate columns from a query; the Harness card retains the
+complete executed result and makes this limitation explicit.
+The DataViewer page can export the current filtered and sorted model-backed
+result to CSV (up to 10,000 rows). It refuses larger exports rather than
+silently truncating them.
+
 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 +160,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.4.md`](./docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.4.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/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.4.md

@@ -0,0 +1,32 @@
+# Foggy DeepSeek Harness plugin 0.4.2-rc.4
+
+This pre-release targets DeepSeek Harness `0.1.7-rc.2` and remains on the
+`dsh017` npm channel. The `beta`, `rc`, `dsh015`, and `latest` channels are
+unchanged.
+
+## Fixes since 0.4.2-rc.3
+
+- Register `foggy_query` with Harness's existing tool runtime instead of
+  installing a second private `@deepseek-ai/dsh-tools` copy. The duplicate
+  runtime caused `Cannot read properties of undefined (reading 'prepare')`
+  before the DSL query reached Foggy Runtime.
+- Allow a normal Launcher upgrade to replace a same-named asset only when the
+  existing file still matches the SHA-256 recorded for the previous installed
+  version. The previous file is backed up; unexpected file changes remain
+  fail-closed. Downloads are verified before replacing the existing file.
+- Convert Query DSL `groupBy` and `orderBy` string shorthand into equivalent
+  object entries when creating a DataViewer preview. A valid, executed query
+  is no longer incorrectly labeled as ineligible for preview.
+- Warn that the current DataViewer table can omit ad-hoc aggregate columns
+  even though the query card contains the complete result. This is an engine
+  display limitation, not a failed Query DSL execution.
+
+The DSL-only DataViewer behavior from rc.3 is unchanged: a preview URL is
+created only when the user clicks the successful query card's button. CTE
+preview is not included.
+
+Install the exact version with:
+
+```powershell
+dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-plugin@0.4.2-rc.4
+```

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

@@ -0,0 +1,27 @@
+# Foggy DeepSeek Harness plugin 0.4.2-rc.5
+
+This pre-release targets DeepSeek Harness `0.1.7-rc.2` and stays on the
+dedicated `dsh017` npm channel. The `beta`, `rc`, `dsh015`, and `latest`
+channels remain unchanged.
+
+## Changes since 0.4.2-rc.4
+
+- Pin Runtime Launcher `0.1.23`, which includes the lite-profile DataViewer
+  preview page without requiring the Analytics Console or MongoDB.
+- The DataViewer page puts readable query details and the executed DSL side by
+  side, supports copying DSL, and places refresh and CSV export below the
+  details. Query links are created on demand from successful DSL result cards.
+- The table supports local filtering and exports the current filtered result.
+  CTE preview is not included. Preview links are process-local development
+  aids, not durable production shares.
+
+The plugin keeps the current Harness `0.1.7-rc.2` tool integration. The
+Runtime is updated only when the user selects **Update components** or
+**Update and start** in Foggy settings; package installation does not restart
+an existing Runtime.
+
+Install the exact version with:
+
+```powershell
+dsh plugin --profile web add --workspace-root @foggy-projects/deepseek-harness-plugin@0.4.2-rc.5
+```

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.5` 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.5"
 
 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.23;
 - analysis/query Skills 0.1.18;
-- onboarding Skill 0.4.2-rc.2;
+- onboarding Skill 0.4.2-rc.5;
 - 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.5"
 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,28 @@ window.__ModuleLoader__.load({
       queryWarningSummary: 'Runtime 在 WARN 模式下忽略了未知的查询属性，查询仍已执行。请检查告警代码与证据后决定是否修正模型或请求。',
       queryWarningCodes: '告警代码',
       queryWarningEvidence: '证据目录',
+      queryCardTitle: 'Foggy DSL 查询',
+      queryCardRunning: '正在校验并执行…',
+      queryCardDone: '校验与查询成功',
+      queryCardFailed: '查询失败；可展开查看错误',
+      queryCardRows: '返回行数',
+      queryCardDetails: '查看 DSL 与执行结果',
+      queryCardOpen: '查看数据',
+      queryCardOpening: '正在生成预览链接…',
+      queryCardPreviewHint: '每次点击都会生成新的预览链接。',
+      queryCardComputedHint: 'DataViewer 可能不显示临时聚合列；请以本次执行结果为准。',
+      queryCardUnsupported: '当前查询不支持 DataViewer 预览，可继续查看查询结果。',
+      queryCardResults: 'Foggy 查询结果',
+      queryCardProvenance: 'Foggy 插件生成',
+      queryCardSource: '来自实际执行结果，非 AI 撰写',
+      queryCardShowAll: '显示全部 {count} 条查询',
+      queryCardShowLess: '收起至前 6 条',
+      queryCardShowResult: '查看结果',
+      queryCardHideResult: '收起结果',
+      queryCardRowUnit: '行',
+      queryCardDsl: 'DSL / SQL',
+      queryCardNoRows: '没有返回数据',
+      queryCardTableMore: '仅预览前 {count} 行',
       stepPlanned: '规划',
       stepDatasourceConfigured: '数据库连接',
       stepDatasourceVerified: '连接验证',
@@ -274,6 +314,28 @@ 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: 'View data',
+      queryCardOpening: 'Creating preview link…',
+      queryCardPreviewHint: 'A fresh preview link is created on every click.',
+      queryCardComputedHint: 'DataViewer may omit ad-hoc aggregate columns; use this execution result as the source of truth.',
+      queryCardUnsupported: 'DataViewer preview is unavailable for this query; the query result remains available.',
+      queryCardResults: 'Foggy query results',
+      queryCardProvenance: 'Generated by Foggy plugin',
+      queryCardSource: 'From executed queries, not AI-written',
+      queryCardShowAll: 'Show all {count} queries',
+      queryCardShowLess: 'Show first 6',
+      queryCardShowResult: 'View result',
+      queryCardHideResult: 'Hide result',
+      queryCardRowUnit: 'rows',
+      queryCardDsl: 'DSL / SQL',
+      queryCardNoRows: 'No rows returned',
+      queryCardTableMore: 'Previewing first {count} rows',
       stepPlanned: 'Plan',
       stepDatasourceConfigured: 'Database connection',
       stepDatasourceVerified: 'Connection test',
@@ -317,6 +379,8 @@ window.__ModuleLoader__.load({
       .foggy-resources{border-top:1px solid var(--dsw-alias-border-l2);padding-top:14px}.foggy-resources h4{margin:0 0 9px;font-size:13px}.foggy-resource-links{display:flex;gap:8px;flex-wrap:wrap}.foggy-resource-link{display:inline-flex;align-items:center;gap:5px;border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:7px 10px;color:var(--dsw-alias-label-secondary);font-size:12px;text-decoration:none}.foggy-resource-link:hover{color:var(--dsw-alias-label-primary);background:var(--dsw-alias-interactive-bg-hover)}.foggy-resource-link:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:2px}
       .foggy-error-panel{border:2px solid var(--dsw-alias-state-error-primary);background:color-mix(in srgb,var(--dsw-alias-state-error-primary) 10%,var(--dsw-alias-bg-layer-3));border-radius:10px;padding:13px 14px;box-shadow:0 6px 18px color-mix(in srgb,var(--dsw-alias-state-error-primary) 13%,transparent)}.foggy-error-panel-head{display:flex;align-items:center;gap:8px;color:var(--dsw-alias-state-error-primary);font-size:14px;font-weight:700}.foggy-error-icon{display:grid;place-items:center;width:22px;height:22px;border-radius:50%;background:var(--dsw-alias-state-error-primary);color:white;font-size:14px}.foggy-error-panel p{margin:7px 0 0;color:var(--dsw-alias-label-primary);font-size:13px;line-height:20px;overflow-wrap:anywhere}.foggy-error-help{color:var(--dsw-alias-state-error-primary)!important;font-weight:600}
       .foggy-message{margin:0;font-size:13px;line-height:20px;color:var(--dsw-alias-label-secondary)}.foggy-message[data-error=true]{color:var(--dsw-alias-state-error-primary)}.foggy-paths,.foggy-next,.foggy-section{border-top:1px solid var(--dsw-alias-border-l2);padding-top:14px}.foggy-paths h4,.foggy-next h4,.foggy-section h4{margin:0 0 8px;font-size:13px}.foggy-paths dl{display:grid;grid-template-columns:100px minmax(0,1fr);gap:6px 10px;margin:0}.foggy-paths dt{color:var(--dsw-alias-label-tertiary);font-size:12px}.foggy-paths dd{margin:0;min-width:0;overflow-wrap:anywhere;font-family:var(--ds-font-family-code);font-size:11px}.foggy-next p,.foggy-section p{margin:0;color:var(--dsw-alias-label-secondary);font-size:13px;line-height:20px}.foggy-section-actions{display:flex;gap:8px;flex-wrap:wrap;margin-top:10px}.foggy-onboarding-head{display:flex;justify-content:space-between;gap:12px;align-items:start}.foggy-onboarding-head code{font-size:11px;color:var(--dsw-alias-label-tertiary);overflow-wrap:anywhere}.foggy-step-list{display:grid;grid-template-columns:repeat(4,minmax(0,1fr));gap:7px;margin-top:10px}.foggy-step{border:1px solid var(--dsw-alias-border-l2);border-radius:8px;padding:8px;font-size:11px;color:var(--dsw-alias-label-tertiary)}.foggy-step[data-state=completed]{border-color:color-mix(in srgb,var(--dsw-alias-state-success-primary) 45%,var(--dsw-alias-border-l2));color:var(--dsw-alias-state-success-primary)}.foggy-step[data-state=failed],.foggy-step[data-state=invalid]{border-color:var(--dsw-alias-state-error-primary);color:var(--dsw-alias-state-error-primary)}.foggy-warning{border:1px solid color-mix(in srgb,var(--dsw-alias-state-warning-primary) 55%,var(--dsw-alias-border-l2));background:color-mix(in srgb,var(--dsw-alias-state-warning-primary) 8%,transparent);border-radius:10px;padding:12px}.foggy-query-warning{margin-top:10px}.foggy-query-warning p+p{margin-top:5px}.foggy-query-warning code{overflow-wrap:anywhere}
+      .foggy-turn-results{margin:10px 0 14px;max-width:100%;border:1px solid var(--dsw-alias-border-l2);border-radius:10px;background:var(--dsw-alias-bg-layer-3);overflow:hidden;color:var(--dsw-alias-label-primary)}.foggy-turn-results-head{display:flex;align-items:center;gap:8px;padding:10px 12px;border-bottom:1px solid var(--dsw-alias-border-l2);font-size:13px;font-weight:600;flex-wrap:wrap}.foggy-turn-results-provenance{padding:2px 7px;border-radius:999px;background:color-mix(in srgb,var(--dsw-alias-state-business-primary) 12%,transparent);color:var(--dsw-alias-state-business-primary);font-size:11px;font-weight:600}.foggy-turn-results-source{color:var(--dsw-alias-label-secondary);font-size:11px;font-weight:400}.foggy-turn-results-count{font-weight:400;color:var(--dsw-alias-label-tertiary);font-variant-numeric:tabular-nums}.foggy-turn-result{padding:9px 12px}.foggy-turn-result+.foggy-turn-result{border-top:1px solid var(--dsw-alias-border-l2)}.foggy-turn-result-head{display:flex;align-items:center;justify-content:space-between;gap:10px;flex-wrap:wrap}.foggy-turn-result-name{min-width:0;overflow-wrap:anywhere;font-size:12px;font-weight:600}.foggy-turn-result-meta{margin-left:8px;color:var(--dsw-alias-label-tertiary);font-size:11px;font-weight:400}.foggy-turn-result-actions{display:flex;align-items:center;gap:8px}.foggy-turn-result-actions button,.foggy-turn-results-toggle{border:0;background:none;color:var(--dsw-alias-state-business-primary);font:inherit;font-size:12px;cursor:pointer;padding:3px 0}.foggy-turn-result-actions button:disabled{opacity:.55;cursor:not-allowed}.foggy-turn-result-actions button:focus-visible,.foggy-turn-results-toggle:focus-visible{outline:2px solid var(--dsw-alias-state-business-primary);outline-offset:2px}.foggy-turn-result-detail{margin-top:9px;overflow:auto;max-height:300px}.foggy-turn-result-detail table{border-collapse:collapse;width:100%;min-width:max-content;font-size:11px}.foggy-turn-result-detail th,.foggy-turn-result-detail td{border:1px solid var(--dsw-alias-border-l2);padding:5px 7px;text-align:left;max-width:240px;overflow-wrap:anywhere}.foggy-turn-result-detail th{background:var(--dsw-alias-bg-layer-2);font-weight:600}.foggy-turn-result-note{margin:6px 0 0;color:var(--dsw-alias-label-tertiary);font-size:11px}.foggy-turn-result-error{margin:6px 0 0;color:var(--dsw-alias-state-error-primary);font-size:11px}.foggy-turn-results-toggle{display:block;width:100%;padding:9px 12px;border-top:1px solid var(--dsw-alias-border-l2);text-align:left}
+      .foggy-turn-result-code{margin-top:9px;font-size:11px}.foggy-turn-result-code summary{cursor:pointer;color:var(--dsw-alias-label-secondary)}.foggy-turn-result-code pre{max-height:220px;overflow:auto;white-space:pre-wrap;overflow-wrap:anywhere;margin:7px 0;padding:8px;border-radius:6px;background:var(--dsw-alias-bg-layer-2)}
       @media (width<=680px){.foggy-grid{grid-template-columns:minmax(0,1fr)}.foggy-runtime-settings-row{grid-template-columns:minmax(0,1fr)}.foggy-runtime-settings-row .foggy-button{width:100%}.foggy-toolbar-main{width:100%}.foggy-toolbar-main .foggy-button{flex:1}.foggy-resource-link{min-height:36px}}
     `
 
@@ -779,7 +843,145 @@ window.__ModuleLoader__.load({
       ] })
     }
 
-    const inject = ['slots', 'locale', 'remote']
+    function queryPreviewSupported(args, result) {
+      const payload = args?.payload
+      return Boolean(result?.execution?.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', 'calculatedFields'].every((key) => !payload[key] || Array.isArray(payload[key]) && payload[key].every((item) => item && typeof item === 'object' && !Array.isArray(item)))
+        && ['groupBy', 'orderBy'].every((key) => !payload[key] || Array.isArray(payload[key]) && payload[key].every((item) => typeof item === 'string' && item.trim() || item && typeof item === 'object' && !Array.isArray(item)))
+    }
+
+    function useViewerPreview(api) {
+      const [preview, setPreview] = useState({ loading: false, error: '' })
+      async function openViewer(args) {
+        const pendingTab = window.open('about:blank', '_blank')
+        setPreview({ loading: true, error: '' })
+        try {
+          const value = unwrap(await api.createViewerPreview({ model: args.model, namespace: args.namespace, payload: args.payload }), 'createViewerPreview')
+          if (pendingTab) pendingTab.location.replace(value.url)
+          else throw new Error('Browser blocked the DataViewer tab')
+          setPreview({ loading: false, error: '' })
+        } catch (error) {
+          if (pendingTab) pendingTab.close()
+          setPreview({ loading: false, error: String(error?.message || error) })
+        }
+      }
+      return { preview, openViewer }
+    }
+
+    function readSuccessfulQuery(block) {
+      if (block?.kind !== 'tool-result' || block.isError || block.call?.name !== 'foggy_query') return null
+      try {
+        const args = JSON.parse(block.call.argsRaw)
+        const text = block.content?.find((item) => item.type === 'text')?.text
+        const result = JSON.parse(text)
+        if (!result?.execution?.success || !args?.model || !args?.namespace || !Array.isArray(result.execution.data?.items)) return null
+        return { callId: block.callId, args, result }
+      } catch { return null }
+    }
+
+    function cellText(value) {
+      const raw = value === null || value === undefined ? '—' : typeof value === 'object' ? JSON.stringify(value) : String(value)
+      return raw.length > 160 ? `${raw.slice(0, 157)}…` : raw
+    }
+
+    function FoggyTurnQuery({ query, api, t }) {
+      const [expanded, setExpanded] = useState(false)
+      const { preview, openViewer } = useViewerPreview(api)
+      const rows = query.result.execution.data.items
+      const fields = rows.length && rows[0] && typeof rows[0] === 'object' ? Object.keys(rows[0]) : []
+      return jsxs('div', { className: 'foggy-turn-result', children: [
+        jsxs('div', { className: 'foggy-turn-result-head', children: [
+          jsxs('div', { className: 'foggy-turn-result-name', children: [
+            query.args.model,
+            jsx('span', { className: 'foggy-turn-result-meta', children: `${query.args.namespace} · ${rows.length} ${t('queryCardRowUnit')}` }),
+          ] }),
+          jsxs('div', { className: 'foggy-turn-result-actions', children: [
+            jsx('button', { type: 'button', 'aria-expanded': expanded, onClick: () => setExpanded((current) => !current), children: t(expanded ? 'queryCardHideResult' : 'queryCardShowResult') }),
+            queryPreviewSupported(query.args, query.result) ? jsx('button', { type: 'button', disabled: preview.loading, onClick: () => openViewer(query.args), children: preview.loading ? t('queryCardOpening') : t('queryCardOpen') }) : null,
+          ] }),
+        ] }),
+        expanded ? jsxs('div', { className: 'foggy-turn-result-detail', children: [
+          rows.length && fields.length ? jsxs('table', { children: [
+            jsx('thead', { children: jsx('tr', { children: fields.map((field) => jsx('th', { scope: 'col', children: field }, field)) }) }),
+            jsx('tbody', { children: rows.slice(0, 5).map((row, index) => jsx('tr', { children: fields.map((field) => jsx('td', { children: cellText(row[field]) }, field)) }, index)) }),
+          ] }) : jsx('p', { className: 'foggy-turn-result-note', children: t('queryCardNoRows') }),
+          rows.length > 5 ? jsx('p', { className: 'foggy-turn-result-note', children: t('queryCardTableMore', { count: 5 }) }) : null,
+          jsxs('details', { className: 'foggy-turn-result-code', children: [
+            jsx('summary', { children: t('queryCardDsl') }),
+            jsx('pre', { children: JSON.stringify(query.args.payload, null, 2) }),
+            query.result.execution.data.debug?.extra?.sql ? jsx('pre', { children: query.result.execution.data.debug.extra.sql }) : null,
+          ] }),
+        ] }) : null,
+        preview.error ? jsx('p', { className: 'foggy-turn-result-error', role: 'alert', children: preview.error }) : null,
+      ] })
+    }
+
+    function FoggyTurnResults({ turn, useQueryCalls, api, t }) {
+      const [showAll, setShowAll] = useState(false)
+      const calls = useQueryCalls(String(turn.turn)) || []
+      const queries = calls.map((item) => readSuccessfulQuery(item.root)).filter(Boolean)
+      if (!queries.length) return null
+      const visible = showAll ? queries : queries.slice(0, 6)
+      return jsxs('section', { className: 'foggy-turn-results', 'aria-label': t('queryCardResults'), children: [
+        jsxs('div', { className: 'foggy-turn-results-head', children: [
+          t('queryCardResults'), jsx('span', { className: 'foggy-turn-results-count', children: queries.length }),
+          jsx('span', { className: 'foggy-turn-results-provenance', children: t('queryCardProvenance') }),
+          jsx('span', { className: 'foggy-turn-results-source', children: t('queryCardSource') }),
+        ] }),
+        ...visible.map((query) => jsx(FoggyTurnQuery, { query, api, t }, query.callId)),
+        queries.length > 6 ? jsx('button', {
+          className: 'foggy-turn-results-toggle', type: 'button', 'aria-expanded': showAll,
+          onClick: () => setShowAll((current) => !current),
+          children: showAll ? t('queryCardShowLess') : t('queryCardShowAll', { count: queries.length }),
+        }) : null,
+      ] })
+    }
+
+    function FoggyQueryCard({ phase, block, api, t }) {
+      const { preview, openViewer } = useViewerPreview(api)
+      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 hasAdHocColumns = payload?.columns?.some((column) => typeof column === 'string' && /\bas\b|\(/i.test(column))
+      const supported = success && queryPreviewSupported(args, result)
+      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(args), children: preview.loading ? t('queryCardOpening') : t('queryCardOpen') }),
+          jsx('p', { style: { margin: '5px 0', color: 'var(--dsw-alias-label-tertiary)', fontSize: 11 }, children: t('queryCardPreviewHint') }),
+          hasAdHocColumns ? jsx('p', { style: { margin: '5px 0', color: 'var(--dsw-alias-state-warning-primary)', fontSize: 11 }, children: t('queryCardComputedHint') }) : 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', 'sessions', 'uiConversation']
 
     async function apply(ctx) {
       const disposeRemote = await ctx.remote.$mount(TYPERT_REMOTE)
@@ -788,6 +990,28 @@ 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('conversation.chat.turnTail', () => remoteCtx.slots.register({
+          name: 'conversation.chat.turnTail',
+          id: 'foggy-query-results',
+          inject: (sessionId) => {
+            const binding = remoteCtx.sessions.binding(sessionId)
+            if (!binding) throw new Error(`Foggy: unknown session ${sessionId}`)
+            const chat = remoteCtx.uiConversation.binding(binding).target('chat')
+            return {
+              api, t,
+              keyedHooks: { queryCalls: (turn) => {
+                const snapshot = chat.getSnapshot()
+                if (!snapshot) throw new Error('Foggy: chat target is unavailable')
+                return snapshot.nodes.turnDataSource(Number(turn), 'tool-call')
+              } },
+            }
+          },
+        }, FoggyTurnResults))
         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,131 @@
+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'
+
+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', '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`)
+    }
+  }
+  const result = Object.fromEntries([...supported].filter((key) => payload[key] !== undefined).map((key) => [key, payload[key]]))
+  if (payload.groupBy !== undefined) {
+    if (!Array.isArray(payload.groupBy) || payload.groupBy.some((item) => typeof item !== 'string' && (!item || typeof item !== 'object' || Array.isArray(item)))) {
+      throw new Error('DataViewer preview requires field names or object-form groupBy entries')
+    }
+    result.groupBy = payload.groupBy.map((item) => typeof item === 'string' ? { field: item } : item)
+  }
+  if (payload.orderBy !== undefined) {
+    if (!Array.isArray(payload.orderBy) || payload.orderBy.some((item) => typeof item !== 'string' && (!item || typeof item !== 'object' || Array.isArray(item)))) {
+      throw new Error('DataViewer preview requires field names or object-form orderBy entries')
+    }
+    result.orderBy = payload.orderBy.map((item) => {
+      if (typeof item !== 'string') return item
+      const shorthand = item.trim().match(/^(-)?(.+?)(?:\s+(asc|desc))?$/i)
+      if (!shorthand || !shorthand[2].trim()) throw new Error('DataViewer preview requires a valid orderBy field')
+      return { field: shorthand[2].trim(), dir: shorthand[1] ? 'desc' : (shorthand[3] || 'asc').toLowerCase() }
+    })
+  }
+  return result
+}
+
+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 {
+    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: {
+      type: 'object',
+      properties: {
+        model: { type: 'string', description: 'Published Foggy QueryModel name' },
+        namespace: { type: 'string', description: 'Foggy namespace' },
+        payload: { type: 'object', additionalProperties: true, description: 'Standard QueryModel DSL, including explicit columns and bounded limit' },
+      },
+      required: ['model', 'namespace', 'payload'],
+    },
+    output: {
+      schema: {
+        type: 'object',
+        additionalProperties: false,
+        properties: {
+          model: { type: 'string' },
+          namespace: { type: 'string' },
+          validation: {},
+          execution: {},
+        },
+        required: ['model', 'namespace', 'validation', 'execution'],
+      },
+      render: (_args, value) => [{ type: 'text', text: JSON.stringify(value) }],
+    },
+    timeoutMs: 150_000,
+    async execute(args, exec) {
+      const { model, namespace, payload } = args || {}
+      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 }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foggy-projects/deepseek-harness-plugin",
-  "version": "0.4.2-rc.2",
+  "version": "0.4.2-rc.5",
   "description": "Foggy Java data analysis engine integration for DeepSeek Harness",
   "keywords": [
     "deepseek-harness",
@@ -41,6 +41,9 @@
     "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.4.md",
+    "docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.5.md",
     "docs/RELEASE-CANDIDATE-0.4.2-DSH-0.1.7-RC.1.md",
     "docs/COMMUNITY-MARKETPLACES.md",
     "docs/WINDOWS-BETA-ACCEPTANCE.md",
@@ -61,7 +64,11 @@
         "@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",
+        "@deepseek-ai/dsh-client-ui-conversation",
+        "@deepseek-ai/dsh-client-ui-chat",
+        "@deepseek-ai/dsh-api-session-controller"
       ]
     }
   },
@@ -74,11 +81,15 @@
     "@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-client-ui-conversation": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-client-ui-chat": "^0.1.7-rc.2",
+    "@deepseek-ai/dsh-api-session-controller": "^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.5",
+  "validatedAt": "2026-09-28",
   "components": {
     "deepseekHarness": {
       "version": "0.1.7-rc.2",
@@ -66,39 +66,39 @@
       }
     },
     "launcher": {
-      "version": "0.1.21",
+      "version": "0.1.23",
       "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.23.jar",
+          "url": "https://github.com/foggy-projects/foggy-data-mcp-bridge/releases/download/foggy-runtime-launcher-v0.1.23/foggy-runtime-launcher-0.1.23.jar",
+          "sha256": "e3575c51e457d6b88740ef5949d7e206d5d6046d960fc8ef0884765bf3be8c66"
         },
         {
           "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.23/start-foggy-runtime.ps1",
+          "sha256": "e6e2ac995a2a84c3de53878e8e0db4d701eab8b3a7ca6dbe9d4fb4ad15b00ae4"
         },
         {
           "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.23/start-foggy-runtime.sh",
+          "sha256": "562ef5614e02c4635c21d5fa9d6c2edc0dfb69d8da0ae57c4247c0c8202d50ae"
         },
         {
           "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.23/README-foggy-runtime-launcher.md",
+          "sha256": "759e3be46eb97a8f62b7ffb1dc5a977c52d0b91d1d31860e4e799125ce25e376"
         },
         {
           "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.23/runtime-launcher-manifest.json",
+          "sha256": "d25a9a0026495fd47e6ca03c957bf9999df9cffe73c6d6b0fc5c7dfc3931d317"
         },
         {
           "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.23/SHA256SUMS",
+          "sha256": "49354e281c9f854651074b292aa003710334ae2f5494b3c07eafddf1d08a7dac"
         }
       ]
     },

package/skills/foggy-deepseek-onboarding/scripts/onboarding.py

@@ -506,28 +506,27 @@ def materialize(
     progress_total: int = 1,
     progress_message: str = "Downloading and verifying asset",
     replace_corrupt: bool = False,
+    previous_sha256: str | None = None,
 ) -> dict:
     destination.parent.mkdir(parents=True, exist_ok=True)
+    previous_valid = False
     if destination.is_file():
         try:
             verify_asset(destination, asset["sha256"])
             return {"file": asset["file"], "path": str(destination), "source": "existing", "sha256": asset["sha256"]}
         except OnboardingError:
-            if not replace_corrupt:
+            previous_valid = bool(previous_sha256 and sha256(destination).lower() == previous_sha256.lower())
+            if not previous_valid and not replace_corrupt:
                 raise
-            quarantine = destination.with_name(
-                destination.name + f".corrupt-{dt.datetime.now().strftime('%Y%m%d-%H%M%S-%f')}"
-            )
-            destination.replace(quarantine)
-    cached = cached_asset(asset["file"], asset["sha256"], cache_dirs)
-    if cached:
-        shutil.copy2(cached, destination)
-        source = "cache"
-    else:
-        temporary = destination.with_name(destination.name + ".download")
-        if temporary.exists():
-            temporary.unlink()
-        try:
+    temporary = destination.with_name(destination.name + ".download")
+    if temporary.exists():
+        temporary.unlink()
+    try:
+        cached = cached_asset(asset["file"], asset["sha256"], cache_dirs)
+        if cached:
+            shutil.copy2(cached, temporary)
+            source = "cache"
+        else:
             def reporthook(block_count: int, block_size: int, total_size: int) -> None:
                 if progress is None or not progress_phase or total_size <= 0:
                     return
@@ -540,12 +539,18 @@ def materialize(
                 )
 
             urllib.request.urlretrieve(asset["url"], temporary, reporthook=reporthook)
-            verify_asset(temporary, asset["sha256"])
-            os.replace(temporary, destination)
-        finally:
-            if temporary.exists():
-                temporary.unlink()
-        source = "network"
+            source = "network"
+        verify_asset(temporary, asset["sha256"])
+        if destination.is_file():
+            suffix = "previous" if previous_valid else "corrupt"
+            backup = destination.with_name(
+                destination.name + f".{suffix}-{dt.datetime.now().strftime('%Y%m%d-%H%M%S-%f')}"
+            )
+            shutil.copy2(destination, backup)
+        os.replace(temporary, destination)
+    finally:
+        if temporary.exists():
+            temporary.unlink()
     verify_asset(destination, asset["sha256"])
     return {"file": asset["file"], "path": str(destination), "source": source, "sha256": asset["sha256"]}
 
@@ -1345,6 +1350,16 @@ def install_command(args: argparse.Namespace) -> dict:
     progress.update("cli", 2, "CLI ready", fraction=1.0)
 
     launcher_dir = install_root / "launcher"
+    previous_state = read_install_state(install_root, required=False)
+    previous_launcher_assets = {}
+    if previous_state and previous_state.get("launcher", {}).get("version") != components["launcher"]["version"]:
+        previous_launcher_assets = {
+            item["file"]: item["sha256"]
+            for item in previous_state.get("verifiedAssets", [])
+            if item.get("file") and item.get("sha256")
+            and item.get("path")
+            and normalized(item["path"]) == normalized(launcher_dir / item["file"])
+        }
     launcher_assets = components["launcher"]["assets"]
     for index, asset in enumerate(launcher_assets):
         progress.update(
@@ -1358,6 +1373,7 @@ def install_command(args: argparse.Namespace) -> dict:
             progress_index=index, progress_total=len(launcher_assets),
             progress_message="Downloading and verifying Launcher",
             replace_corrupt=repair_component == "launcher",
+            previous_sha256=previous_launcher_assets.get(asset["file"]),
         ))
         progress.update(
             "launcher", 3, "Downloading and verifying Launcher",