@foggy-projects/deepseek-harness-plugin 0.4.0-beta.9 → 0.4.0-rc.2

package/lib/index.js

@@ -9,6 +9,12 @@ import { createFoggySkillProvider } from './skill-provider.js'
 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 {
+  DEFAULT_RUNTIME_PORT,
+  readRuntimeSettings,
+  writeRuntimeSettings,
+} from './runtime-settings.js'
 
 const execFileAsync = promisify(execFile)
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
@@ -131,6 +137,8 @@ async function assertSystemPrerequisites(kind) {
 
 function createPythonProgressReporter(operation, path) {
   let pending = Promise.resolve()
+  const runtimeStart = operation.kind === 'runtime-start'
+  const totalSteps = runtimeStart ? 6 : 7
   return {
     update(detail) {
       const fraction = Math.max(0, Math.min(1, Number(detail.fraction) || 0))
@@ -139,11 +147,11 @@ function createPythonProgressReporter(operation, path) {
         operationId: operation.id,
         kind: operation.kind,
         state: 'running',
-        phase: 'python',
-        message: detail.message || 'Preparing managed Python',
+        phase: runtimeStart ? 'runtime-preflight' : 'python',
+        message: runtimeStart ? 'Preparing the Foggy Runtime controller' : detail.message || 'Preparing managed Python',
         currentFile: detail.currentFile || null,
-        percent: Math.round(((1 + fraction) / 7) * 100),
-        step: { index: 2, total: 7 },
+        percent: runtimeStart ? Math.round(fraction * 3) : Math.round(((1 + fraction) / totalSteps) * 100),
+        step: { index: runtimeStart ? 1 : 2, total: totalSteps },
         startedAt: operation.startedAt,
         updatedAt: new Date().toISOString(),
       }
@@ -194,13 +202,19 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     const statePath = join(roots.installRoot, 'install-state.json')
     const runtimeStatePath = join(roots.dataRoot, 'runtime-state.json')
     const progressPath = join(roots.dataRoot, 'operation-progress.json')
+    const portConflictPath = join(roots.dataRoot, 'last-runtime-port-conflict.json')
     const manifest = await readJson(versionsFile)
+    const runtimeSettings = await readRuntimeSettings(roots.dataRoot, {
+      defaultPort: manifest.defaults?.port ?? DEFAULT_RUNTIME_PORT,
+    })
     const python = await probePythonRuntime({ installRoot: roots.installRoot, manifest })
     const java = compatible(await commandVersion(process.env.JAVA_EXE || 'java', ['-version']), '17.0')
     let state = null
     let runtime = null
+    let lastRuntimePortConflict = null
     try { state = await readJson(statePath) } catch {}
     try { runtime = await readJson(runtimeStatePath) } catch {}
+    try { lastRuntimePortConflict = await readJson(portConflictPath) } catch {}
     let onboarding = { success: true, profiles: [], profileCount: 0 }
     let profileMigration = { success: true, entries: [], pendingCount: 0, conflictCount: 0, profileStore: roots.profileStore }
     if (state) {
@@ -214,8 +228,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     const cliPath = state?.cli?.command
     const launcherPath = state?.launcher?.path
     const analysisSkillPath = state?.skills?.analysis?.path || join(roots.installRoot, 'skills', 'foggy-ai-analysis')
+    const semanticQuerySkillPath = state?.skills?.semanticQuery?.path || join(roots.installRoot, 'skills', 'foggy-semantic-query')
     const onboardingSkillPath = join(packageRoot, 'skills', 'foggy-deepseek-onboarding')
     const analysisMarker = await readOptionalJson(join(analysisSkillPath, '.foggy-managed-skill.json'))
+    const semanticQueryMarker = await readOptionalJson(join(semanticQuerySkillPath, '.foggy-managed-skill.json'))
     const components = {
       python,
       java,
@@ -235,6 +251,14 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         ),
         version: state?.skills?.analysis?.version ?? manifest.components.analysisSkill.version,
       },
+      semanticQuerySkill: {
+        installed: Boolean(
+          await exists(join(semanticQuerySkillPath, 'SKILL.md'))
+          && semanticQueryMarker?.schemaVersion === 'foggy-managed-skill/v1'
+          && semanticQueryMarker?.componentVersion === manifest.components.semanticQuerySkill.version
+        ),
+        version: state?.skills?.semanticQuery?.version ?? manifest.components.semanticQuerySkill.version,
+      },
       onboardingSkill: {
         installed: await exists(join(onboardingSkillPath, 'SKILL.md')),
         version: manifest.packageVersion,
@@ -245,8 +269,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       && components.cli.installed
       && components.launcher.installed
       && components.analysisSkill.installed
+      && components.semanticQuerySkill.installed
       && components.onboardingSkill.installed
     const running = Boolean(runtime && processRunning(Number(runtime.pid)))
+    const activePort = running && Number.isInteger(Number(runtime?.port)) ? Number(runtime.port) : null
     const progress = await readOptionalJson(progressPath)
     let operation = operationView(this.operation)
     if (operation.state === 'running' && progress?.operationId === operation.id) {
@@ -270,6 +296,14 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       installed,
       running,
       runtimeUrl: running ? runtime.runtimeUrl ?? null : null,
+      runtimeSettings: {
+        ...runtimeSettings,
+        activePort,
+        activeRuntimeUrl: running ? runtime.runtimeUrl ?? null : null,
+        pendingRestart: Boolean(running && activePort && activePort !== runtimeSettings.port),
+        lastConflict: lastRuntimePortConflict,
+        conflictApplies: Number(lastRuntimePortConflict?.port) === runtimeSettings.port,
+      },
       roots,
       components,
       operation,
@@ -291,8 +325,8 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         'download and verify a pinned private Python runtime',
         'create isolated Python environment',
         'download and verify pinned CLI and Launcher assets',
-        'install the Foggy analysis Skill into the global managed component directory',
-        'register onboarding and analysis Skills through the native DSH Skill registry',
+        'install the Foggy analysis and semantic-query Skills into the global managed component directory',
+        'register onboarding, analysis, and semantic-query Skills through the native DSH Skill registry',
         'write global install state; resolve each workspace from the DSH session cwd',
       ],
       secretsInDshSettings: false,
@@ -323,6 +357,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     return this.startOperation('repair-analysis-skill', true, ['install', '--repair-component', 'analysis-skill'])
   }
 
+  async repairSemanticQuerySkill() {
+    return this.startOperation('repair-semantic-query-skill', true, ['install', '--repair-component', 'semantic-query-skill'])
+  }
+
   async migrateProfiles() {
     return this.startOperation('profile-migration', false, ['profile-migrate', '--approve'])
   }
@@ -330,6 +368,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
   async diagnostics() {
     const roots = defaultRoots()
     const status = await this.status()
+    const lastRuntimeStartFailure = await enrichRuntimeStartFailure(
+      await readOptionalJson(join(roots.dataRoot, 'last-runtime-start-failure.json')),
+      roots.dataRoot,
+    )
     let doctor
     try {
       doctor = await runOnboarding(['doctor', '--no-fail'])
@@ -348,6 +390,8 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       components: status.components,
       onboarding: status.onboarding,
       profileMigration: status.profileMigration,
+      runtimeSettings: status.runtimeSettings,
+      lastRuntimeStartFailure,
       doctor,
     }
     const directory = join(roots.dataRoot, 'diagnostics')
@@ -358,11 +402,61 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
   }
 
   async runtimeStart() {
-    return this.startOperation('runtime-start', false, ['runtime-start'])
+    const roots = defaultRoots()
+    const manifest = await readJson(versionsFile)
+    const settings = await readRuntimeSettings(roots.dataRoot, {
+      defaultPort: manifest.defaults?.port ?? DEFAULT_RUNTIME_PORT,
+    })
+    if (!settings.valid) {
+      return {
+        success: false,
+        accepted: false,
+        error: {
+          code: 'RUNTIME_SETTINGS_INVALID',
+          message: `Runtime settings are invalid: ${settings.error}. Save a valid port in Foggy plugin settings.`,
+        },
+      }
+    }
+    return this.startOperation('runtime-start', false, [
+      'runtime-start', '--install-root', roots.installRoot, '--data-root', roots.dataRoot,
+      '--port', String(settings.port),
+    ])
   }
 
   async runtimeStop() {
-    return this.startOperation('runtime-stop', false, ['runtime-stop'])
+    const roots = defaultRoots()
+    return this.startOperation('runtime-stop', false, [
+      'runtime-stop', '--install-root', roots.installRoot, '--data-root', roots.dataRoot,
+    ])
+  }
+
+  async saveRuntimeSettings(input) {
+    const roots = defaultRoots()
+    if (this.operation?.state === 'running') {
+      return {
+        success: false,
+        error: { code: 'OPERATION_RUNNING', message: 'Wait for the current Foggy operation to finish before changing the Runtime port.' },
+      }
+    }
+    const runtime = await readOptionalJson(join(roots.dataRoot, 'runtime-state.json'))
+    if (runtime && processRunning(Number(runtime.pid))) {
+      return {
+        success: false,
+        error: { code: 'RUNTIME_RUNNING', message: 'Stop Foggy Runtime before changing its port.' },
+      }
+    }
+    try {
+      const settings = await writeRuntimeSettings(roots.dataRoot, input)
+      if (this.operation?.state === 'failed' && this.operation.result?.error?.code === 'RUNTIME_PORT_UNAVAILABLE') {
+        this.operation = null
+      }
+      return { success: true, settings }
+    } catch (error) {
+      return {
+        success: false,
+        error: { code: 'RUNTIME_PORT_INVALID', message: String(error?.message ?? error) },
+      }
+    }
   }
 
   startOperation(kind, replaceSkill, explicitArgs) {
@@ -371,7 +465,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     }
     const id = `${Date.now()}-${Math.random().toString(16).slice(2, 10)}`
     const args = explicitArgs ?? ['install']
-    const reportsProgress = args[0] === 'install'
+    const reportsProgress = args[0] === 'install' || args[0] === 'runtime-start'
     if (reportsProgress) {
       const roots = defaultRoots()
       args.push('--progress-file', join(roots.dataRoot, 'operation-progress.json'), '--operation-id', id, '--operation-kind', kind)
@@ -380,6 +474,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     for (const cacheDir of (process.env.FOGGY_ASSET_CACHE_DIRS || '').split(delimiter).filter(Boolean)) {
       args.push('--asset-cache-dir', cacheDir)
     }
+    const runtimeStart = kind === 'runtime-start'
     const operation = {
       id,
       kind,
@@ -394,10 +489,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         kind,
         state: 'running',
         phase: 'preflight',
-        message: 'Starting Foggy initialization',
+        message: runtimeStart ? 'Starting Foggy Runtime' : 'Starting Foggy initialization',
         currentFile: null,
         percent: 0,
-        step: { index: 1, total: 7 },
+        step: { index: 1, total: runtimeStart ? 6 : 7 },
       } : null,
       promise: null,
     }
@@ -422,8 +517,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
           operation.progress = {
             ...operation.progress,
             state: operation.state,
-            phase: operation.state === 'succeeded' ? 'complete' : operation.progress.phase,
-            message: operation.state === 'succeeded' ? 'Foggy initialization completed' : 'Foggy initialization failed',
+            phase: operation.state === 'succeeded' ? (runtimeStart ? 'runtime-complete' : 'complete') : operation.progress.phase,
+            message: operation.state === 'succeeded'
+              ? (runtimeStart ? 'Foggy Runtime is ready' : 'Foggy initialization completed')
+              : (runtimeStart ? 'Foggy Runtime startup failed' : 'Foggy initialization failed'),
             percent: operation.state === 'succeeded' ? 100 : operation.progress.percent,
           }
         }
@@ -437,7 +534,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
           operation.progress = {
             ...operation.progress,
             state: 'failed',
-            message: 'Foggy initialization failed',
+            message: runtimeStart ? 'Foggy Runtime startup failed' : 'Foggy initialization failed',
           }
         }
       })
@@ -448,8 +545,9 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
 
 const markerInitializers = []
 for (const method of [
-  'status', 'plan', 'initialize', 'repair', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill',
+  'status', 'plan', 'initialize', 'repair', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill', 'repairSemanticQuerySkill',
   'migrateProfiles', 'diagnostics', 'runtimeStart', 'runtimeStop',
+  'saveRuntimeSettings',
 ]) {
   Remote(method)(FoggyIntegrationGateway.prototype[method], {
     kind: 'method',

package/lib/remote-descriptor.js

@@ -1,15 +1,18 @@
 import { z } from 'zod'
 
 const resultSchema = z.unknown()
+const runtimeSettingsInputSchema = z.object({
+  port: z.number().int().min(1024).max(65535),
+}).strict()
 
-function descriptor(method) {
+function descriptor(method, parameters = []) {
   return {
     id: `@foggy-projects/deepseek-harness-plugin#foggyIntegration/${method}`,
     service: 'foggyIntegration',
     namespace: 'foggyIntegration',
     method,
     invocation: { kind: 'direct' },
-    parameters: [],
+    parameters,
     result: {
       mode: 'strict',
       typeSymbol: '@foggy-projects/deepseek-harness-plugin#FoggyIntegrationResult',
@@ -25,6 +28,17 @@ export const descriptors = [
   descriptor('initialize'),
   descriptor('repair'),
   descriptor('repairPython'),
+  descriptor('repairSemanticQuerySkill'),
   descriptor('runtimeStart'),
   descriptor('runtimeStop'),
+  descriptor('saveRuntimeSettings', [{
+    name: 'input',
+    wire: 'input',
+    source: 'json',
+    codec: {
+      mode: 'strict',
+      typeSymbol: '@foggy-projects/deepseek-harness-plugin#FoggyRuntimeSettingsInput',
+      schema: runtimeSettingsInputSchema,
+    },
+  }]),
 ]

package/lib/runtime-settings.js

@@ -0,0 +1,89 @@
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { writeJsonAtomic } from './atomic-json.js'
+
+export const RUNTIME_SETTINGS_SCHEMA = 'foggy-deepseek-runtime-settings/v1'
+export const DEFAULT_RUNTIME_PORT = 18166
+export const MIN_RUNTIME_PORT = 1024
+export const MAX_RUNTIME_PORT = 65535
+
+export function normalizeRuntimePort(value) {
+  const port = typeof value === 'string' && value.trim() !== '' ? Number(value) : value
+  if (!Number.isInteger(port) || port < MIN_RUNTIME_PORT || port > MAX_RUNTIME_PORT) {
+    throw new Error(`Runtime port must be an integer between ${MIN_RUNTIME_PORT} and ${MAX_RUNTIME_PORT}`)
+  }
+  return port
+}
+
+export function runtimeUrlForPort(port) {
+  return `http://127.0.0.1:${normalizeRuntimePort(port)}`
+}
+
+export function runtimeSettingsPath(dataRoot) {
+  return join(dataRoot, 'runtime-settings.json')
+}
+
+export async function readRuntimeSettings(dataRoot, { defaultPort = DEFAULT_RUNTIME_PORT } = {}) {
+  const path = runtimeSettingsPath(dataRoot)
+  const fallbackPort = normalizeRuntimePort(defaultPort)
+  try {
+    const payload = JSON.parse(await readFile(path, 'utf8'))
+    if (payload?.schemaVersion !== RUNTIME_SETTINGS_SCHEMA) {
+      throw new Error(`expected schemaVersion ${RUNTIME_SETTINGS_SCHEMA}`)
+    }
+    const port = normalizeRuntimePort(payload.runtimePort)
+    return {
+      valid: true,
+      source: 'configured',
+      schemaVersion: RUNTIME_SETTINGS_SCHEMA,
+      port,
+      runtimeUrl: runtimeUrlForPort(port),
+      updatedAt: payload.updatedAt ?? null,
+      path,
+      error: null,
+    }
+  } catch (error) {
+    if (error?.code === 'ENOENT') {
+      return {
+        valid: true,
+        source: 'default',
+        schemaVersion: RUNTIME_SETTINGS_SCHEMA,
+        port: fallbackPort,
+        runtimeUrl: runtimeUrlForPort(fallbackPort),
+        updatedAt: null,
+        path,
+        error: null,
+      }
+    }
+    return {
+      valid: false,
+      source: 'invalid',
+      schemaVersion: RUNTIME_SETTINGS_SCHEMA,
+      port: fallbackPort,
+      runtimeUrl: runtimeUrlForPort(fallbackPort),
+      updatedAt: null,
+      path,
+      error: String(error?.message ?? error),
+    }
+  }
+}
+
+export async function writeRuntimeSettings(dataRoot, input) {
+  const runtimePort = normalizeRuntimePort(input?.port)
+  const payload = {
+    schemaVersion: RUNTIME_SETTINGS_SCHEMA,
+    runtimePort,
+    updatedAt: new Date().toISOString(),
+  }
+  const path = runtimeSettingsPath(dataRoot)
+  await writeJsonAtomic(path, payload)
+  return {
+    valid: true,
+    source: 'configured',
+    ...payload,
+    port: runtimePort,
+    runtimeUrl: runtimeUrlForPort(runtimePort),
+    path,
+    error: null,
+  }
+}

package/lib/skill-provider.js

@@ -56,15 +56,15 @@ function candidate(name, description, path, source) {
   }
 }
 
-async function managedAnalysisSkill(installRoot, manifest) {
+async function managedSkill(installRoot, manifest, { stateKey, componentKey, kind }) {
   const state = await readOptionalJson(join(installRoot, 'install-state.json'))
-  const path = state?.skills?.analysis?.path
+  const path = state?.skills?.[stateKey]?.path
   if (!path || !await exists(join(path, 'SKILL.md'))) return null
   const marker = await readOptionalJson(join(path, '.foggy-managed-skill.json'))
   if (
     marker?.schemaVersion !== 'foggy-managed-skill/v1'
-    || marker?.kind !== 'analysis'
-    || marker?.componentVersion !== manifest.components.analysisSkill.version
+    || marker?.kind !== kind
+    || marker?.componentVersion !== manifest.components[componentKey].version
   ) return null
   return join(path, 'SKILL.md')
 }
@@ -83,10 +83,15 @@ export function createFoggySkillProvider({ installRoot, versionsFile }) {
         'bundled',
       )]
       if (!manifest) return result
-      const analysisPath = await managedAnalysisSkill(installRoot, manifest)
-      if (analysisPath) {
-        const analysis = parseSkill(await readFile(analysisPath, 'utf8'), 'foggy-ai-analysis')
-        result.push(candidate('foggy-ai-analysis', analysis.metadata.description, analysisPath, 'bundled'))
+      const managedSkills = [
+        { name: 'foggy-ai-analysis', stateKey: 'analysis', componentKey: 'analysisSkill', kind: 'analysis' },
+        { name: 'foggy-semantic-query', stateKey: 'semanticQuery', componentKey: 'semanticQuerySkill', kind: 'semantic-query' },
+      ]
+      for (const spec of managedSkills) {
+        const path = await managedSkill(installRoot, manifest, spec)
+        if (!path) continue
+        const skill = parseSkill(await readFile(path, 'utf8'), spec.name)
+        result.push(candidate(spec.name, skill.metadata.description, path, 'bundled'))
       }
       return result
     },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foggy-projects/deepseek-harness-plugin",
-  "version": "0.4.0-beta.9",
+  "version": "0.4.0-rc.2",
   "description": "Foggy Java data analysis engine integration for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -20,6 +20,7 @@
     "cordis.patch.yml",
     "experience/linux/**",
     "docs/PUBLIC-BETA-READINESS.md",
+    "docs/RELEASE-CANDIDATE-0.4.0-RC.2.md",
     "docs/WINDOWS-BETA-ACCEPTANCE.md",
     "THIRD-PARTY-RUNTIME-NOTICES.md",
     "README.md"
@@ -48,16 +49,16 @@
   },
   "peerDependencies": {
     "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-api-remotes": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-locale": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-runtime": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-skill": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2"
+    "@deepseek-ai/dsh-api-remotes": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-locale": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-runtime": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-client-ui-settings-plugins": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-skill": "^0.1.2-rc.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.2-rc.1"
   },
   "scripts": {
-    "check": "node --check lib/index.js && node --check lib/atomic-json.js && node --check lib/python-runtime.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 && python test/onboarding_unit.py"
+    "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"
   }
 }