@foggy-projects/deepseek-harness-plugin 0.4.0-beta.6 → 0.4.0-beta.8

package/lib/index.js

@@ -1,12 +1,13 @@
 import { execFile } from 'node:child_process'
-import { access, readFile } from 'node:fs/promises'
+import { access, mkdir, readFile, rename, writeFile } from 'node:fs/promises'
 import { constants as fsConstants } from 'node:fs'
 import { dirname, join, delimiter } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { promisify } from 'node:util'
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import { createFoggySkillProvider } from './skill-provider.js'
-import { compatible } from './version.js'
+import { ensurePythonRuntime, probePythonRuntime } from './python-runtime.js'
+import { compatible, compatibleNode } from './version.js'
 
 const execFileAsync = promisify(execFile)
 const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)))
@@ -71,16 +72,6 @@ async function commandVersion(command, args) {
   }
 }
 
-async function pythonCommand() {
-  const configured = process.env.FOGGY_PYTHON
-  const candidates = configured ? [configured] : process.platform === 'win32' ? ['python', 'py'] : ['python3', 'python']
-  for (const command of candidates) {
-    const probe = await commandVersion(command, ['--version'])
-    if (probe.available) return command
-  }
-  throw new Error('Python 3.11+ was not found; set FOGGY_PYTHON to its executable')
-}
-
 function parseOutput(stdout, stderr) {
   const text = String(stdout ?? '').trim()
   if (!text) throw new Error(String(stderr ?? '').trim() || 'Foggy onboarding returned no JSON')
@@ -91,14 +82,34 @@ function parseOutput(stdout, stderr) {
   }
 }
 
-async function runOnboarding(args, timeout = 15 * 60_000) {
-  const python = await pythonCommand()
+async function runOnboarding(args, timeout = 15 * 60_000, options = {}) {
+  const roots = defaultRoots()
+  const manifest = await readJson(versionsFile)
+  const cacheDirs = (process.env.FOGGY_ASSET_CACHE_DIRS || '').split(delimiter).filter(Boolean)
+  const python = options.ensurePython
+    ? await ensurePythonRuntime({
+        installRoot: roots.installRoot,
+        manifest,
+        cacheDirs,
+        force: options.forcePython,
+        onProgress: options.onPythonProgress,
+      })
+    : await probePythonRuntime({ installRoot: roots.installRoot, manifest })
+  if (!python.available) {
+    throw new Error('Foggy managed Python is unavailable; initialize or repair the Python component')
+  }
+  await options.flushPythonProgress?.()
   try {
-    const { stdout, stderr } = await execFileAsync(python, [onboardingScript, ...args], {
+    const { stdout, stderr } = await execFileAsync(python.path, [onboardingScript, ...args], {
       windowsHide: true,
       timeout,
       maxBuffer: 4 * 1024 * 1024,
       cwd: process.env.FOGGY_PROJECT_ROOT || process.cwd(),
+      env: {
+        ...process.env,
+        FOGGY_ONBOARDING_PYTHON: python.path,
+        FOGGY_ONBOARDING_PYTHON_SOURCE: python.source,
+      },
     })
     return parseOutput(stdout, stderr)
   } catch (error) {
@@ -107,6 +118,51 @@ async function runOnboarding(args, timeout = 15 * 60_000) {
   }
 }
 
+async function assertSystemPrerequisites(kind) {
+  if (kind === 'initialize' && !compatibleNode(process.versions.node)) {
+    throw new Error(`DeepSeek Harness requires Node.js ^22.19.0 or >=24.0.0; detected ${process.versions.node}`)
+  }
+  if (kind === 'initialize' || kind === 'runtime-start') {
+    const java = compatible(await commandVersion(process.env.JAVA_EXE || 'java', ['-version']), '17.0')
+    if (!java.available) throw new Error('Java 17+ is required; install a system JRE/JDK or set JAVA_EXE')
+  }
+}
+
+async function writeJsonAtomic(path, payload) {
+  await mkdir(dirname(path), { recursive: true })
+  const temporary = `${path}.${process.pid}.${Date.now()}.tmp`
+  await writeFile(temporary, `${JSON.stringify(payload, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+  await rename(temporary, path)
+}
+
+function createPythonProgressReporter(operation, path) {
+  let pending = Promise.resolve()
+  return {
+    update(detail) {
+      const fraction = Math.max(0, Math.min(1, Number(detail.fraction) || 0))
+      const payload = {
+        schemaVersion: 'foggy-deepseek-onboarding-progress/v1',
+        operationId: operation.id,
+        kind: operation.kind,
+        state: 'running',
+        phase: 'python',
+        message: detail.message || 'Preparing managed Python',
+        currentFile: detail.currentFile || null,
+        percent: Math.round(((1 + fraction) / 7) * 100),
+        step: { index: 2, total: 7 },
+        startedAt: operation.startedAt,
+        updatedAt: new Date().toISOString(),
+      }
+      if (detail.bytes) payload.bytes = detail.bytes
+      operation.progress = payload
+      pending = pending.then(() => writeJsonAtomic(path, payload))
+    },
+    flush() {
+      return pending
+    },
+  }
+}
+
 function processRunning(pid) {
   if (!Number.isInteger(pid) || pid <= 0) return false
   try {
@@ -145,18 +201,22 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     const runtimeStatePath = join(roots.dataRoot, 'runtime-state.json')
     const progressPath = join(roots.dataRoot, 'operation-progress.json')
     const manifest = await readJson(versionsFile)
-    let pythonProbe
-    try {
-      pythonProbe = await commandVersion(await pythonCommand(), ['--version'])
-    } catch (error) {
-      pythonProbe = { available: false, output: '', error: String(error.message ?? error) }
-    }
-    const python = compatible(pythonProbe, '3.11')
+    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
     try { state = await readJson(statePath) } catch {}
     try { runtime = await readJson(runtimeStatePath) } catch {}
+    let onboarding = { success: true, profiles: [], profileCount: 0 }
+    let profileMigration = { success: true, entries: [], pendingCount: 0, conflictCount: 0, profileStore: roots.profileStore }
+    if (state) {
+      try { onboarding = await runOnboarding(['onboard-list']) } catch (error) {
+        onboarding = { success: false, profiles: [], profileCount: 0, error: String(error.message ?? error) }
+      }
+      try { profileMigration = await runOnboarding(['profile-migration-status']) } catch (error) {
+        profileMigration = { success: false, entries: [], pendingCount: 0, conflictCount: 0, profileStore: roots.profileStore, error: String(error.message ?? error) }
+      }
+    }
     const cliPath = state?.cli?.command
     const launcherPath = state?.launcher?.path
     const analysisSkillPath = state?.skills?.analysis?.path || join(roots.installRoot, 'skills', 'foggy-ai-analysis')
@@ -187,7 +247,8 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         provider: 'foggy-managed-skills',
       },
     }
-    const installed = components.cli.installed
+    const installed = components.python.available
+      && components.cli.installed
       && components.launcher.installed
       && components.analysisSkill.installed
       && components.onboardingSkill.installed
@@ -218,6 +279,8 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       roots,
       components,
       operation,
+      onboarding,
+      profileMigration,
       next: installed ? (running ? 'configure-database' : 'start-runtime') : 'initialize',
     }
   }
@@ -231,6 +294,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       workspaceMode: 'dsh-session-cwd',
       versions: Object.fromEntries(Object.entries(manifest.components).map(([name, value]) => [name, value.version])),
       operations: [
+        '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',
@@ -249,6 +313,56 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     return this.startOperation('repair', true)
   }
 
+  async repairCli() {
+    return this.startOperation('repair-cli', false, ['install', '--repair-component', 'cli'])
+  }
+
+  async repairPython() {
+    return this.startOperation('repair-python', false, ['install'])
+  }
+
+  async repairLauncher() {
+    return this.startOperation('repair-launcher', false, ['install', '--repair-component', 'launcher'])
+  }
+
+  async repairAnalysisSkill() {
+    return this.startOperation('repair-analysis-skill', true, ['install', '--repair-component', 'analysis-skill'])
+  }
+
+  async migrateProfiles() {
+    return this.startOperation('profile-migration', false, ['profile-migrate', '--approve'])
+  }
+
+  async diagnostics() {
+    const roots = defaultRoots()
+    const status = await this.status()
+    let doctor
+    try {
+      doctor = await runOnboarding(['doctor', '--no-fail'])
+    } catch (error) {
+      doctor = { success: false, error: String(error.message ?? error), bootstrapOnly: true }
+    }
+    const report = {
+      schemaVersion: 'foggy-deepseek-diagnostics/v1',
+      generatedAt: new Date().toISOString(),
+      packageVersion: status.packageVersion,
+      state: status.state,
+      installed: status.installed,
+      running: status.running,
+      runtimeUrl: status.runtimeUrl,
+      roots: status.roots,
+      components: status.components,
+      onboarding: status.onboarding,
+      profileMigration: status.profileMigration,
+      doctor,
+    }
+    const directory = join(roots.dataRoot, 'diagnostics')
+    await mkdir(directory, { recursive: true })
+    const path = join(directory, `diagnostics-${Date.now()}.json`)
+    await writeFile(path, `${JSON.stringify(report, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+    return { success: true, path, report }
+  }
+
   async runtimeStart() {
     return this.startOperation('runtime-start', false, ['runtime-start'])
   }
@@ -263,7 +377,8 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
     }
     const id = `${Date.now()}-${Math.random().toString(16).slice(2, 10)}`
     const args = explicitArgs ?? ['install']
-    if (!explicitArgs) {
+    const reportsProgress = args[0] === 'install'
+    if (reportsProgress) {
       const roots = defaultRoots()
       args.push('--progress-file', join(roots.dataRoot, 'operation-progress.json'), '--operation-id', id, '--operation-kind', kind)
     }
@@ -279,7 +394,7 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
       finishedAt: null,
       result: null,
       error: null,
-      progress: !explicitArgs ? {
+      progress: reportsProgress ? {
         schemaVersion: 'foggy-deepseek-onboarding-progress/v1',
         operationId: id,
         kind,
@@ -288,11 +403,22 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
         message: 'Starting Foggy initialization',
         currentFile: null,
         percent: 0,
-        step: { index: 1, total: 6 },
+        step: { index: 1, total: 7 },
       } : null,
       promise: null,
     }
-    operation.promise = runOnboarding(args)
+    const pythonProgress = reportsProgress
+      ? createPythonProgressReporter(operation, join(defaultRoots().dataRoot, 'operation-progress.json'))
+      : null
+    operation.promise = (async () => {
+      await assertSystemPrerequisites(kind)
+      return runOnboarding(args, 15 * 60_000, {
+        ensurePython: true,
+        forcePython: kind === 'repair-python',
+        onPythonProgress: (detail) => pythonProgress?.update(detail),
+        flushPythonProgress: () => pythonProgress?.flush(),
+      })
+    })()
       .then((result) => {
         operation.state = result.success === false ? 'failed' : 'succeeded'
         operation.result = result
@@ -327,7 +453,10 @@ export class FoggyIntegrationGateway extends TypertRemoteService {
 }
 
 const markerInitializers = []
-for (const method of ['status', 'plan', 'initialize', 'repair', 'runtimeStart', 'runtimeStop']) {
+for (const method of [
+  'status', 'plan', 'initialize', 'repair', 'repairPython', 'repairCli', 'repairLauncher', 'repairAnalysisSkill',
+  'migrateProfiles', 'diagnostics', 'runtimeStart', 'runtimeStop',
+]) {
   Remote(method)(FoggyIntegrationGateway.prototype[method], {
     kind: 'method',
     name: method,

package/lib/python-runtime.js

@@ -0,0 +1,339 @@
+import { execFile } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import {
+  access,
+  copyFile,
+  mkdir,
+  open,
+  readFile,
+  rename,
+  rm,
+  stat,
+  writeFile,
+} from 'node:fs/promises'
+import { constants as fsConstants } from 'node:fs'
+import { dirname, isAbsolute, join } from 'node:path'
+import { promisify } from 'node:util'
+import { compatible, versionParts } from './version.js'
+
+const execFileAsync = promisify(execFile)
+const MARKER_SCHEMA = 'foggy-managed-python/v1'
+
+async function exists(path) {
+  try {
+    await access(path, fsConstants.F_OK)
+    return true
+  } catch {
+    return false
+  }
+}
+
+async function commandVersion(command) {
+  try {
+    const { stdout, stderr } = await execFileAsync(command, ['--version'], {
+      windowsHide: true,
+      timeout: 15_000,
+      maxBuffer: 256 * 1024,
+    })
+    return {
+      available: true,
+      output: `${stdout}\n${stderr}`.trim().split(/\r?\n/)[0] ?? '',
+      command,
+    }
+  } catch (error) {
+    return { available: false, output: '', command, error: error.code ?? 'COMMAND_FAILED' }
+  }
+}
+
+async function sha256(path) {
+  const file = await open(path, 'r')
+  const hash = createHash('sha256')
+  try {
+    for await (const chunk of file.readableWebStream()) hash.update(Buffer.from(chunk))
+  } finally {
+    await file.close()
+  }
+  return hash.digest('hex')
+}
+
+function pythonComponent(manifest) {
+  const component = manifest?.components?.python
+  if (!component?.version || !component?.assets) {
+    throw new Error('The Foggy component manifest does not define a managed Python runtime')
+  }
+  return component
+}
+
+export function pythonAssetKey(platform = process.platform, arch = process.arch) {
+  return `${platform}-${arch}`
+}
+
+export function selectPythonAsset(manifest, platform = process.platform, arch = process.arch) {
+  const component = pythonComponent(manifest)
+  const key = pythonAssetKey(platform, arch)
+  const asset = component.assets[key]
+  if (!asset) {
+    throw new Error(`Managed Python is not published for ${platform}/${arch}; set FOGGY_PYTHON to a compatible Python executable`)
+  }
+  if (!asset.file || !asset.url || !/^[a-f0-9]{64}$/.test(asset.sha256 || '')) {
+    throw new Error(`Managed Python asset ${key} is incomplete or has an invalid SHA256`)
+  }
+  return { ...asset, key }
+}
+
+export function managedPythonHome(installRoot, manifest) {
+  return join(installRoot, 'python', pythonComponent(manifest).version)
+}
+
+export function managedPythonExecutable(installRoot, manifest, platform = process.platform) {
+  const home = managedPythonHome(installRoot, manifest)
+  return platform === 'win32' ? join(home, 'python.exe') : join(home, 'bin', 'python3')
+}
+
+function markerPath(installRoot, manifest) {
+  return join(managedPythonHome(installRoot, manifest), '.foggy-managed-python.json')
+}
+
+async function readMarker(installRoot, manifest) {
+  try {
+    return JSON.parse(await readFile(markerPath(installRoot, manifest), 'utf8'))
+  } catch {
+    return null
+  }
+}
+
+function exactVersion(probe, expected) {
+  const actualParts = versionParts(probe.output)
+  const expectedParts = versionParts(expected)
+  return expectedParts.every((part, index) => actualParts[index] === part)
+}
+
+export async function probePythonRuntime({ installRoot, manifest, env = process.env } = {}) {
+  const minimum = manifest.components.cli.minimumPythonVersion
+  if (env.FOGGY_PYTHON) {
+    const probe = compatible(await commandVersion(env.FOGGY_PYTHON), minimum)
+    const isPython = /^Python\s+\d+/i.test(probe.output)
+    return {
+      ...probe,
+      available: probe.available && isPython,
+      source: 'override',
+      managed: false,
+      path: env.FOGGY_PYTHON,
+      version: probe.available && isPython ? versionParts(probe.output).slice(0, 3).join('.') : null,
+      error: probe.available && !isPython ? 'Configured executable is not Python' : probe.error,
+    }
+  }
+
+  const component = pythonComponent(manifest)
+  const command = managedPythonExecutable(installRoot, manifest)
+  const marker = await readMarker(installRoot, manifest)
+  if (!marker || marker.schemaVersion !== MARKER_SCHEMA || marker.version !== component.version) {
+    return {
+      available: false,
+      detected: false,
+      output: '',
+      error: 'Managed Python is not installed or its marker is invalid',
+      source: 'managed',
+      managed: true,
+      path: command,
+      version: component.version,
+      minimum,
+    }
+  }
+  const probe = compatible(await commandVersion(command), minimum)
+  const valid = probe.available && exactVersion(probe, component.version)
+  return {
+    ...probe,
+    available: valid,
+    detected: probe.detected,
+    ...(valid ? {} : { error: probe.error || `Expected Python ${component.version}` }),
+    source: 'managed',
+    managed: true,
+    path: command,
+    home: managedPythonHome(installRoot, manifest),
+    version: component.version,
+    asset: marker.asset,
+  }
+}
+
+async function safeRenameCorrupt(path) {
+  if (!await exists(path)) return null
+  const corrupt = `${path}.corrupt-${Date.now()}`
+  await rename(path, corrupt)
+  return corrupt
+}
+
+async function cachedAsset(asset, cacheDirs) {
+  for (const directory of cacheDirs) {
+    const candidate = join(directory, asset.file)
+    try {
+      if ((await stat(candidate)).isFile() && await sha256(candidate) === asset.sha256) return candidate
+    } catch {}
+  }
+  return null
+}
+
+async function materializeAsset(asset, destination, cacheDirs, onProgress) {
+  await mkdir(dirname(destination), { recursive: true })
+  if (await exists(destination) && await sha256(destination) === asset.sha256) {
+    onProgress?.({ fraction: 0.82, message: 'Using verified managed Python archive', currentFile: asset.file })
+    return { path: destination, source: 'existing' }
+  }
+  await safeRenameCorrupt(destination)
+  const temporary = `${destination}.download`
+  const cached = await cachedAsset(asset, cacheDirs)
+  if (cached) {
+    onProgress?.({ fraction: 0.35, message: 'Copying managed Python from verified cache', currentFile: asset.file })
+    await rm(temporary, { force: true })
+    await copyFile(cached, temporary)
+  } else {
+    let resumeBytes = 0
+    try {
+      resumeBytes = (await stat(temporary)).size
+    } catch {}
+    if (resumeBytes >= Number(asset.size || Number.MAX_SAFE_INTEGER)) {
+      if (await sha256(temporary) === asset.sha256) {
+        await rename(temporary, destination)
+        return { path: destination, source: 'resumed' }
+      }
+      await rm(temporary, { force: true })
+      resumeBytes = 0
+    }
+    const controller = new AbortController()
+    const timeout = setTimeout(() => controller.abort(), 20 * 60_000)
+    try {
+      const headers = resumeBytes > 0 ? { Range: `bytes=${resumeBytes}-` } : undefined
+      const response = await fetch(asset.url, { redirect: 'follow', signal: controller.signal, headers })
+      if (!response.ok || !response.body) throw new Error(`Managed Python download failed: HTTP ${response.status}`)
+      const resumed = resumeBytes > 0 && response.status === 206
+      if (!resumed) {
+        await rm(temporary, { force: true })
+        resumeBytes = 0
+      }
+      const expectedSize = Number(asset.size || (Number(response.headers.get('content-length')) + resumeBytes) || 0)
+      const file = await open(temporary, resumed ? 'a' : 'w')
+      let received = resumeBytes
+      try {
+        const reader = response.body.getReader()
+        while (true) {
+          const { done, value } = await reader.read()
+          if (done) break
+          const chunk = Buffer.from(value)
+          await file.write(chunk)
+          received += chunk.length
+          const fraction = expectedSize > 0 ? Math.min(received / expectedSize, 1) : 0
+          onProgress?.({
+            fraction: 0.05 + fraction * 0.72,
+            message: resumed ? 'Resuming managed Python download' : 'Downloading managed Python',
+            currentFile: asset.file,
+            bytes: { received, total: expectedSize || null },
+          })
+        }
+        await file.sync()
+      } finally {
+        await file.close()
+      }
+    } finally {
+      clearTimeout(timeout)
+    }
+  }
+  if (await sha256(temporary) !== asset.sha256) {
+    await rm(temporary, { force: true })
+    throw new Error(`Managed Python SHA256 mismatch for ${asset.file}`)
+  }
+  await rename(temporary, destination)
+  return { path: destination, source: cached ? 'cache' : 'download' }
+}
+
+function validateArchiveEntries(text) {
+  const entries = text.split(/\r?\n/).map((entry) => entry.trim()).filter(Boolean)
+  if (!entries.length) throw new Error('Managed Python archive is empty')
+  for (const entry of entries) {
+    const normalized = entry.replaceAll('\\', '/')
+    if (isAbsolute(entry) || normalized.startsWith('/') || normalized.includes('../') || !normalized.startsWith('python/')) {
+      throw new Error(`Managed Python archive contains an unsafe entry: ${entry}`)
+    }
+  }
+}
+
+async function extractArchive(archive, installRoot, manifest, asset, onProgress) {
+  const pythonRoot = join(installRoot, 'python')
+  const target = managedPythonHome(installRoot, manifest)
+  const staging = join(pythonRoot, `.staging-${process.pid}-${Date.now()}`)
+  const backup = `${target}.previous-${Date.now()}`
+  await mkdir(staging, { recursive: true })
+  try {
+    onProgress?.({ fraction: 0.84, message: 'Inspecting managed Python archive', currentFile: asset.file })
+    const listed = await execFileAsync('tar', ['-tzf', archive], {
+      windowsHide: true,
+      timeout: 2 * 60_000,
+      maxBuffer: 16 * 1024 * 1024,
+    })
+    validateArchiveEntries(listed.stdout)
+    onProgress?.({ fraction: 0.88, message: 'Extracting managed Python', currentFile: asset.file })
+    await execFileAsync('tar', ['-xzf', archive, '-C', staging], {
+      windowsHide: true,
+      timeout: 5 * 60_000,
+      maxBuffer: 4 * 1024 * 1024,
+    })
+    const extracted = join(staging, 'python')
+    const executable = process.platform === 'win32' ? join(extracted, 'python.exe') : join(extracted, 'bin', 'python3')
+    if (!await exists(executable)) throw new Error('Managed Python archive did not contain the expected interpreter')
+    await writeFile(join(extracted, '.foggy-managed-python.json'), `${JSON.stringify({
+      schemaVersion: MARKER_SCHEMA,
+      version: pythonComponent(manifest).version,
+      distribution: pythonComponent(manifest).distribution,
+      buildRelease: pythonComponent(manifest).buildRelease,
+      platform: process.platform,
+      arch: process.arch,
+      asset: { file: asset.file, sha256: asset.sha256 },
+      installedAt: new Date().toISOString(),
+    }, null, 2)}\n`, { encoding: 'utf8', mode: 0o600 })
+
+    let movedPrevious = false
+    if (await exists(target)) {
+      await rename(target, backup)
+      movedPrevious = true
+    }
+    try {
+      await rename(extracted, target)
+    } catch (error) {
+      if (movedPrevious && !await exists(target)) await rename(backup, target)
+      throw error
+    }
+    if (movedPrevious) await rm(backup, { recursive: true, force: true })
+  } finally {
+    await rm(staging, { recursive: true, force: true })
+  }
+}
+
+export async function ensurePythonRuntime({
+  installRoot,
+  manifest,
+  cacheDirs = [],
+  force = false,
+  env = process.env,
+  onProgress,
+} = {}) {
+  if (env.FOGGY_PYTHON) {
+    const override = await probePythonRuntime({ installRoot, manifest, env })
+    if (!override.available) throw new Error(`FOGGY_PYTHON is not compatible: ${override.path}`)
+    onProgress?.({ fraction: 1, message: 'Using FOGGY_PYTHON override', currentFile: override.path })
+    return override
+  }
+
+  const current = await probePythonRuntime({ installRoot, manifest, env })
+  if (current.available && !force) {
+    onProgress?.({ fraction: 1, message: 'Managed Python is ready', currentFile: current.path })
+    return current
+  }
+
+  const asset = selectPythonAsset(manifest)
+  const archive = join(installRoot, 'downloads', 'python', asset.file)
+  const materialized = await materializeAsset(asset, archive, cacheDirs, onProgress)
+  await extractArchive(materialized.path, installRoot, manifest, asset, onProgress)
+  const installed = await probePythonRuntime({ installRoot, manifest, env })
+  if (!installed.available) throw new Error(installed.error || 'Managed Python verification failed')
+  onProgress?.({ fraction: 1, message: 'Managed Python is ready', currentFile: installed.path })
+  return installed
+}

package/lib/remote-descriptor.js

@@ -24,6 +24,7 @@ export const descriptors = [
   descriptor('plan'),
   descriptor('initialize'),
   descriptor('repair'),
+  descriptor('repairPython'),
   descriptor('runtimeStart'),
   descriptor('runtimeStop'),
 ]

package/lib/version.js

@@ -13,3 +13,8 @@ export function compatible(probe, minimum) {
   }
   return { ...probe, detected: true, available: true, minimum }
 }
+
+export function compatibleNode(version) {
+  const [major, minor] = String(version).split('.').map(Number)
+  return (major === 22 && minor >= 19) || major >= 24
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@foggy-projects/deepseek-harness-plugin",
-  "version": "0.4.0-beta.6",
+  "version": "0.4.0-beta.8",
   "description": "Foggy Java data analysis engine integration for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",
@@ -19,11 +19,14 @@
     "!skills/**/*.pyc",
     "cordis.patch.yml",
     "experience/linux/**",
+    "docs/PUBLIC-BETA-READINESS.md",
+    "docs/WINDOWS-BETA-ACCEPTANCE.md",
+    "THIRD-PARTY-RUNTIME-NOTICES.md",
     "README.md"
   ],
   "license": "Apache-2.0",
   "engines": {
-    "node": ">=22.19.0"
+    "node": "^22.19.0 || >=24.0.0"
   },
   "dsh": {
     "bundle": {
@@ -54,7 +57,7 @@
     "@deepseek-ai/dsh-typert-protocol": "^0.1.1-rc.2"
   },
   "scripts": {
-    "check": "node --check lib/index.js && node --check lib/skill-provider.js && node --check lib/client.js && node --check lib/typert.js && node --check lib/remote.js",
+    "check": "node --check lib/index.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"
   }
 }