@tasksai/install 0.1.39 → 0.1.40

package/runtime/workflows/template.py

@@ -0,0 +1,65 @@
+"""Shared presentation and input contract, independent of hosting and exporters.
+
+Only server-owned definitions may select brands and outputs. This module does
+not select a tenant, authorize access, generate content, or set credit prices.
+"""
+from dataclasses import dataclass
+from .store import JobError
+
+BRANDS = {
+    "realtor": {"name": "RealtorTasksAI", "accent": "#347462"},
+    "law": {"name": "LawTasksAI", "accent": "#375b88"},
+    "farmer": {"name": "FarmerTasksAI", "accent": "#657a39"},
+}
+
+@dataclass(frozen=True)
+class InputField:
+    key: str
+    label: str
+    required: bool = True
+
+@dataclass(frozen=True)
+class OutputFile:
+    kind: str
+    label: str
+
+@dataclass(frozen=True)
+class WorkflowTemplate:
+    workflow_id: str
+    vertical: str
+    title: str
+    inputs: tuple[InputField, ...] | None
+    outputs: tuple[OutputFile, ...]
+
+    def __post_init__(self):
+        if self.vertical not in BRANDS:
+            raise JobError("Unknown workflow vertical")
+        kinds = [output.kind for output in self.outputs]
+        if "word" not in kinds or len(kinds) != len(set(kinds)) or set(kinds) - {"word", "excel"}:
+            raise JobError("Every workflow needs one Word document; Excel is optional")
+        keys = [field.key for field in (self.inputs or ())]
+        if len(keys) != len(set(keys)):
+            raise JobError("Input names must be unique")
+
+    def input_state(self, answers=None):
+        if self.inputs is None:
+            raise JobError("This workflow uses its own structured input adapter")
+        answers = {} if answers is None else answers
+        known = {field.key for field in self.inputs}
+        if not isinstance(answers, dict) or set(answers) - known:
+            raise JobError("Answers must match this workflow's inputs")
+        if any(not isinstance(value, str) for value in answers.values()):
+            raise JobError("Answers must be text")
+        values = {field.key: answers.get(field.key, "").strip() for field in self.inputs}
+        missing = [{"key": field.key, "label": field.label} for field in self.inputs
+                   if field.required and not values[field.key]]
+        return {"answers": values, "missing": missing, "ready": not missing}
+
+    def presentation(self):
+        return {"workflow_id": self.workflow_id, "brand": dict(BRANDS[self.vertical]),
+                "title": self.title, "outputs": [{"kind": out.kind, "label": out.label} for out in self.outputs]}
+
+SELLER_OFFER = WorkflowTemplate("realtor.seller_offer", "realtor", "Offer comparison", None, (
+    OutputFile("word", "Download Word briefing"), OutputFile("excel", "Download Excel comparison")))
+# None delegates input validation to the existing structured offer adapter.
+# An empty tuple represents a workflow requiring no inputs.

package/runtime/workflows/workspace_launch.py

@@ -0,0 +1,76 @@
+"""Start or reuse the installed local workspace after licensed delivery."""
+import hashlib
+from contextlib import contextmanager
+import json
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+from urllib.parse import urlparse
+from urllib.request import urlopen
+from .licensed_delivery import safe_directory
+from .store import JobError
+
+
+def workspace_identity(root,owner):
+    return hashlib.sha256((str(Path(root).resolve())+'\n'+owner).encode()).hexdigest()
+
+
+def runtime_fingerprint():
+    runtime=Path(__file__).resolve().parents[1]
+    paths=[runtime/'document_renderer.py',runtime/'software_use.py']+sorted((runtime/'workflows').rglob('*.py'))+sorted((runtime/'workflows'/'embedded').glob('*.html'))+[runtime/'workflows'/'realtor-release-registry.json']
+    return hashlib.sha256(json.dumps({str(p.relative_to(runtime)):hashlib.sha256(p.read_bytes()).hexdigest() for p in paths},sort_keys=True).encode()).hexdigest()
+
+
+def existing_url(root,owner):
+    try:
+        record=json.loads((Path(root)/'workspace-connection.json').read_text(encoding="utf-8"));url=record['url'];parsed=urlparse(url)
+        if parsed.scheme!='http' or parsed.hostname!='127.0.0.1' or not parsed.port or not parsed.path.startswith('/workspace/') or parsed.query or parsed.fragment:return None
+        with urlopen(url+'/health',timeout=1) as response: health=json.load(response)
+        return url if not health.get('closing') and health.get('workspace_id')==workspace_identity(root,owner) and health.get('runtime_fingerprint')==runtime_fingerprint() else None
+    except (OSError,ValueError,KeyError):return None
+
+
+def _launch(root,owner):
+    root=safe_directory(root)
+    url=existing_url(root,owner)
+    if url:return url
+    # Each spawned app uses a distinct ephemeral port. Concurrent starts cannot
+    # overwrite customer data; a fresh health check only accepts this workspace.
+    runtime=Path(__file__).resolve().parents[1]
+    env={**os.environ,'PYTHONPATH':str(runtime)+os.pathsep+os.environ.get('PYTHONPATH','')}
+    flags={'creationflags':subprocess.CREATE_NO_WINDOW} if os.name=='nt' else {'start_new_session':True}
+    log=root/'workspace-server.log'
+    if log.is_symlink():raise JobError('Workspace log must not be a symbolic link')
+    with log.open('ab') as output:
+        process=subprocess.Popen([sys.executable,'-m','workflows.catalog_app','--root',str(root),'--owner',owner],cwd=runtime,env=env,stdin=subprocess.DEVNULL,stdout=output,stderr=output,**flags)
+    for _ in range(50):
+        url=existing_url(root,owner)
+        if url:return url
+        if process.poll() is not None:break
+        time.sleep(.1)
+    raise JobError('The local workspace could not start; the delivered skill remains available')
+
+
+@contextmanager
+def startup_lock(root):
+    path=root/'workspace-startup.lock'
+    if path.is_symlink():raise JobError('Workspace lock must not be a symbolic link')
+    with path.open('a+b') as stream:
+        if os.name=='nt':
+            import msvcrt
+            if path.stat().st_size==0:stream.write(b'0');stream.flush()
+            stream.seek(0);msvcrt.locking(stream.fileno(),msvcrt.LK_LOCK,1)
+        else:
+            import fcntl
+            fcntl.flock(stream.fileno(),fcntl.LOCK_EX)
+        try:yield
+        finally:
+            if os.name=='nt':stream.seek(0);msvcrt.locking(stream.fileno(),msvcrt.LK_UNLCK,1)
+            else:fcntl.flock(stream.fileno(),fcntl.LOCK_UN)
+
+
+def launch(root,owner):
+    root=safe_directory(root)
+    with startup_lock(root):return _launch(root,owner)

package/src/index.js

@@ -1,8 +1,10 @@
 #!/usr/bin/env node
 
 import fs from "node:fs";
+import { requirePython, ensurePython, setPythonInstallRoot } from "./python-runtime.js";
+import { withLock } from "./operation-lock.js";
 import fsp from "node:fs/promises";
-import { randomUUID } from "node:crypto";
+import { randomUUID, createHash } from "node:crypto";
 import https from "node:https";
 import os from "node:os";
 import path from "node:path";
@@ -123,18 +125,31 @@ function isMainModule() {
 }
 
 async function main() {
+  if (process.argv[2] === "private-workflow") {
+    const { installPrivateWorkflow } = await import("./private-workflow.js");
+    await installPrivateWorkflow(process.argv.slice(3));
+    return;
+  }
   const options = parseArgs(process.argv.slice(2));
 
   if (!options.productId) {
     printUsage();
     process.exit(1);
   }
+  setPythonInstallRoot(getInstallDir(options.productId, options));
 
   if (options.command === "doctor") {
     await doctor(options);
     return;
   }
 
+  if (options.command === "recover") {
+    const { recoverInstallation } = await import("./recover-installation.js");
+    const result = await recoverInstallation(getInstallDir(options.productId, options));
+    console.log(result.status === "not_needed" ? "No unfinished software update was found." : "Previous TasksAI software restored. Restart your AI app, then run the loader doctor check before resuming work. Recovery copies have been retained.");
+    return;
+  }
+
   if (options.command === "update") {
     await install(options, { updateOnly: true });
     return;
@@ -187,7 +202,7 @@ function parseArgs(argv) {
 
   options.productId = positionals[0] || null;
   if (positionals[1]) options.command = positionals[1];
-  if (!["install", "doctor", "update", "uninstall"].includes(options.command)) {
+  if (!["install", "doctor", "update", "uninstall", "recover"].includes(options.command)) {
     throw new Error(`Unsupported command: ${options.command}`);
   }
   if (!["browser", "license-key"].includes(options.auth)) {
@@ -205,6 +220,7 @@ function printUsage() {
   tasksai-install <product-id> [install] [--source <repo-url>] [--ref <branch>] [--client claude-desktop|cursor|windsurf|codex|all] [--auth browser|license-key] [--install-dir <path>]
   tasksai-install <product-id> doctor [--client claude-desktop|cursor|windsurf|codex|all] [--install-dir <path>]
   tasksai-install <product-id> update [--install-dir <path>]
+  tasksai-install <product-id> recover [--install-dir <path>]
   tasksai-install <product-id> uninstall [--client claude-desktop|cursor|windsurf|codex|all] [--install-dir <path>]
 
 Examples:
@@ -239,58 +255,79 @@ async function install(options, { updateOnly = false } = {}) {
   const clients = updateOnly ? [] : resolveClients(options.client);
   await preflightWriteAccess({ operation: updateOnly ? "update" : "install", installDir, clients, options, vertical, source });
 
-  await fsp.mkdir(runtimeDir, { recursive: true });
-  await fsp.mkdir(path.join(installDir, "logs"), { recursive: true });
-  await logEvent(installDir, "install_start", {
-    productId: options.productId,
-    source: source.repoUrl,
-    client: options.client,
-    updateOnly
-  });
-
-  await writeJson(path.join(installDir, "agent-install.json"), manifest);
-  await writeJson(path.join(installDir, "vertical.json"), vertical);
-  await downloadRuntime(source, runtimeDir, manifest);
-
-  const licenseKey = await resolveLicenseKey(options, vertical, installDir);
-  const existingEnvPath = path.join(installDir, ".env");
-  const existingEnv = fs.existsSync(existingEnvPath)
-    ? parseEnv(await fsp.readFile(existingEnvPath, "utf8"))
-    : {};
-  const installId = firstValue(existingEnv.TASKSAI_INSTALL_ID, process.env.TASKSAI_INSTALL_ID) || randomUUID();
-
-  if (!options.skipPythonDeps) {
-    installPythonDeps(runtimeDir, vendorDir);
-  }
+  await fsp.mkdir(installDir, { recursive: true });
+  return withLock(path.join(installDir, ".installer-operation.lock"), async () => {
+    await fsp.mkdir(runtimeDir, { recursive: true });
+    await fsp.mkdir(path.join(installDir, "logs"), { recursive: true });
+    await logEvent(installDir, "install_start", {
+      productId: options.productId,
+      source: source.repoUrl,
+      client: options.client,
+      updateOnly
+    });
 
-  const envEntries = {
-    TASKSAI_LICENSE_KEY: licenseKey,
-    LAWTASKSAI_LICENSE_KEY: licenseKey,
-    TASKSAI_PRODUCT_ID: vertical.product_id,
-    TASKSAI_API_BASE: vertical.api_base_url,
-    LAWTASKSAI_API_BASE: vertical.api_base_url,
-    TASKSAI_INSTALL_ID: installId
-  };
-  await writeEnvFile(path.join(installDir, ".env"), envEntries);
-  await writeEnvFile(path.join(runtimeDir, ".env"), envEntries);
+    const licenseKey = await resolveLicenseKey(options, vertical, installDir);
+    await ensurePython(installDir);
+    const existingEnvPath = path.join(installDir, ".env");
+    const existingEnv = fs.existsSync(existingEnvPath)
+      ? parseEnv(await fsp.readFile(existingEnvPath, "utf8"))
+      : {};
+    const installId = firstValue(existingEnv.TASKSAI_INSTALL_ID, process.env.TASKSAI_INSTALL_ID) || randomUUID();
+
+    const envEntries = {
+      TASKSAI_LICENSE_KEY: licenseKey,
+      LAWTASKSAI_LICENSE_KEY: licenseKey,
+      TASKSAI_PRODUCT_ID: vertical.product_id,
+      TASKSAI_API_BASE: vertical.api_base_url,
+      LAWTASKSAI_API_BASE: vertical.api_base_url,
+      TASKSAI_INSTALL_ID: installId
+    };
+    if (manifest.local_workspace === true && vertical.product_id === "realtor") {
+      const accountScope = createHash("sha256").update(licenseKey).digest("hex").slice(0, 24);
+      envEntries.TASKSAI_WORKSPACE_DIR = path.join(installDir, "workspaces", accountScope);
+    }
+    const { preparedUpdate } = await import("./prepared-update.js");
+    const prepared = await preparedUpdate(installDir, {
+      skipDependencies: options.skipPythonDeps,
+      installDependencies: installPythonDeps,
+      validate: async (stagedRuntime, stagedVendor) => {
+        if (!options.skipPythonDeps) await verifyRuntimeHealth({
+          serverPath: path.join(stagedRuntime, "server.py"), vendorDir: stagedVendor,
+          isolated: true, workspace: manifest.local_workspace === true
+        });
+        if (updateOnly && !options.skipPythonDeps) await verifyUpdateClientPython({
+          productId: vertical.product_id, serverPath: path.join(stagedRuntime, "server.py"),
+          vendorDir: stagedVendor, workspace: manifest.local_workspace === true
+        });
+      },
+      prepare: async (staging, stagedRuntime) => {
+        await downloadRuntime(source, stagedRuntime, manifest);
+        await writeJson(path.join(staging, "agent-install.json"), manifest);
+        await writeJson(path.join(staging, "vertical.json"), vertical);
+        await writeEnvFile(path.join(staging, ".env"), envEntries);
+        await writeEnvFile(path.join(stagedRuntime, ".env"), envEntries);
+      }
+    });
+    await logEvent(installDir, "software_prepared", { previousSoftware: prepared.previousSoftware });
 
-  if (updateOnly) {
-    await logEvent(installDir, "update_complete", { productId: options.productId });
-    console.log(`${vertical.display_name} runtime updated at ${installDir}`);
-    return;
-  }
+    if (updateOnly) {
+      await logEvent(installDir, "update_complete", { productId: options.productId });
+      console.log(`${vertical.display_name} runtime updated at ${installDir}`);
+      return;
+    }
 
-  for (const client of clients) {
-    await configureMcpClient({ client, vertical, installDir, runtimeDir, vendorDir });
-  }
+    for (const client of clients) {
+      await configureMcpClient({ client, vertical, installDir, runtimeDir, vendorDir });
+    }
 
-  await doctor(options, { quietSuccess: true });
-  await logEvent(installDir, "install_complete", {
-    productId: options.productId,
-    clients: clients.map((client) => client.id)
+    await doctor(options, { quietSuccess: true });
+    await logEvent(installDir, "install_complete", {
+      productId: options.productId,
+      clients: clients.map((client) => client.id)
+    });
+    console.log(`${vertical.display_name} is installed. Restart ${clients.map((client) => client.displayName).join(", ")} to see the tools.`);
+    console.log(`After restart, ask: "${vertical.first_prompt}"`);
   });
-  console.log(`${vertical.display_name} is installed. Restart ${clients.map((client) => client.displayName).join(", ")} to see the tools.`);
-  console.log(`After restart, ask: "${vertical.first_prompt}"`);
 }
 
 async function doctor(options, {
@@ -308,6 +345,7 @@ async function doctor(options, {
   const clients = clientsOverride || resolveClients(options.client);
 
   const problems = [];
+  const configuredCommands = new Map();
   if (!fs.existsSync(verticalPath)) problems.push(`Missing ${verticalPath}`);
   if (!fs.existsSync(envPath)) problems.push(`Missing ${envPath}`);
   if (!fs.existsSync(serverPath)) problems.push(`Missing ${serverPath}`);
@@ -322,6 +360,11 @@ async function doctor(options, {
         ? await codexConfigHasServer(configPath, vertical.product_id)
         : await jsonConfigHasServer(configPath, vertical.product_id);
       if (!hasServer) problems.push(`${client.displayName} config does not contain mcpServers.${vertical.product_id}`);
+      else {
+        const command = await configuredPythonCommand(configPath, client.configFormat, vertical.product_id);
+        if (!command) problems.push(`${client.displayName} Python connection could not be verified; rerun the installer for this client`);
+        else configuredCommands.set(command, client.displayName);
+      }
     } else {
       problems.push(`${client.displayName} config not found at ${configPath}`);
     }
@@ -333,6 +376,13 @@ async function doctor(options, {
     } catch (error) {
       problems.push(`Runtime health check failed (${healthErrorSummary(error)})`);
     }
+    for (const [python, clientName] of configuredCommands) {
+      try {
+        await runtimeHealthImpl({ serverPath, vendorDir, python });
+      } catch (error) {
+        problems.push(`${clientName} configured Python connection failed (${healthErrorSummary(error)}); rerun the installer for this client`);
+      }
+    }
   }
 
   const productId = String(vertical.product_id || options.productId || "").trim().toLowerCase();
@@ -425,42 +475,45 @@ async function uninstall(options) {
   const installDir = getInstallDir(options.productId, options);
   const clients = resolveClients(options.client);
   await preflightWriteAccess({ operation: "uninstall", installDir, clients, options });
+  await fsp.mkdir(installDir, { recursive: true });
+  return withLock(path.join(installDir, ".installer-operation.lock"), async () => {
 
-  for (const client of clients) {
-    const configPath = client.configPath();
-    if (!fs.existsSync(configPath)) {
-      console.log(`${client.displayName} config not found; nothing to remove.`);
-      continue;
-    }
+    for (const client of clients) {
+      const configPath = client.configPath();
+      if (!fs.existsSync(configPath)) {
+        console.log(`${client.displayName} config not found; nothing to remove.`);
+        continue;
+      }
 
-    await withLock(`${configPath}.lock`, async () => {
-      const keys = mcpServerKeysForProduct(options.productId);
-      if (client.configFormat === "toml") {
-        const text = await fsp.readFile(configPath, "utf8");
-        if (!tomlHasAnyMcpServer(text, keys)) {
-          console.log(`${client.displayName} does not have a ${options.productId} MCP entry.`);
-          return;
-        }
-        await backupFile(configPath);
-        await atomicWriteText(configPath, removeTomlSections(text, tomlSectionNamesForProduct(options.productId)));
-      } else {
-        const config = await readJson(configPath);
-        if (!keys.some((key) => config.mcpServers?.[key])) {
-          console.log(`${client.displayName} does not have a ${options.productId} MCP entry.`);
-          return;
+      await withLock(`${configPath}.lock`, async () => {
+        const keys = mcpServerKeysForProduct(options.productId);
+        if (client.configFormat === "toml") {
+          const text = await fsp.readFile(configPath, "utf8");
+          if (!tomlHasAnyMcpServer(text, keys)) {
+            console.log(`${client.displayName} does not have a ${options.productId} MCP entry.`);
+            return;
+          }
+          await backupFile(configPath);
+          await atomicWriteText(configPath, removeTomlSections(text, tomlSectionNamesForProduct(options.productId)));
+        } else {
+          const config = await readJson(configPath);
+          if (!keys.some((key) => config.mcpServers?.[key])) {
+            console.log(`${client.displayName} does not have a ${options.productId} MCP entry.`);
+            return;
+          }
+          await backupFile(configPath);
+          for (const key of keys) delete config.mcpServers[key];
+          await atomicWriteJson(configPath, config);
         }
-        await backupFile(configPath);
-        for (const key of keys) delete config.mcpServers[key];
-        await atomicWriteJson(configPath, config);
-      }
-    });
+      });
 
-    console.log(`${options.productId} was removed from ${client.displayName}.`);
-  }
+      console.log(`${options.productId} was removed from ${client.displayName}.`);
+    }
 
-  await logEvent(installDir, "uninstall_complete", {
-    productId: options.productId,
-    clients: clients.map((client) => client.id)
+    await logEvent(installDir, "uninstall_complete", {
+      productId: options.productId,
+      clients: clients.map((client) => client.id)
+    });
   });
 }
 
@@ -487,7 +540,7 @@ async function configureMcpClient({ client, vertical, installDir, runtimeDir, ve
 
 function buildMcpServerConfig({ client, vertical, installDir, runtimeDir, vendorDir }) {
   return {
-    command: pythonCommandForPlatform(),
+    command: requirePython(),
     args: [path.join(runtimeDir, "server.py")],
     env: {
       TASKSAI_PRODUCT_ID: vertical.product_id,
@@ -513,6 +566,57 @@ function pythonVendorPaths(vendorDir, platform = process.platform) {
   ];
 }
 
+async function configuredPythonCommand(configPath, format, productId) {
+  let command;
+  if (format === "toml") {
+    let selected = false;
+    const commands = [];
+    for (const line of (await fsp.readFile(configPath, "utf8")).split(/\r?\n/)) {
+      const section = line.match(/^\s*\[([^\]]+)\]\s*(?:#.*)?$/);
+      if (section) { selected = section[1] === `mcp_servers.${productId}`; continue; }
+      if (!selected) continue;
+      const match = line.match(/^\s*command\s*=\s*("(?:\\.|[^"\\])*"|'[^']*')\s*(?:#.*)?$/);
+      if (match) {
+        try { commands.push(match[1].startsWith("'") ? match[1].slice(1, -1) : JSON.parse(match[1])); }
+        catch { return null; }
+      }
+    }
+    if (commands.length !== 1) return null;
+    command = commands[0];
+  } else {
+    command = (await readJson(configPath)).mcpServers?.[productId]?.command;
+  }
+  // Inspect direct Python connections only. Do not execute arbitrary wrappers
+  // from an unrecognized client configuration as part of a health check.
+  if (typeof command !== "string" || !/^(?:python(?:3(?:\.\d+)?)?)(?:\.exe)?$/i.test(command.split(/[\\/]/).pop())) return null;
+  return command;
+}
+
+async function verifyUpdateClientPython({ productId, serverPath, vendorDir, workspace,
+  clients = Object.values(CLIENTS), runtimeHealthImpl = verifyRuntimeHealth }) {
+  // Check every existing connection for this product, including legacy names.
+  // Read only: unrelated connections and user configuration are never rewritten.
+  const verified = new Set();
+  for (const client of clients) {
+    const configPath = client.configPath();
+    if (!fs.existsSync(configPath)) continue;
+    for (const key of mcpServerKeysForProduct(productId)) {
+      const present = client.configFormat === "toml"
+        ? await codexConfigHasServer(configPath, key) : await jsonConfigHasServer(configPath, key);
+      if (!present) continue;
+      const python = await configuredPythonCommand(configPath, client.configFormat, key);
+      if (!python) throw new Error(`${client.displayName} connection cannot be checked before updating; rerun the installer for this client. The previous software remains in place.`);
+      if (verified.has(python)) continue;
+      try {
+        await runtimeHealthImpl({ serverPath, vendorDir, python, isolated: true, workspace });
+      } catch (error) {
+        throw new Error(`${client.displayName} connection cannot run the updated software (${healthErrorSummary(error)}); rerun the installer for this client. The previous software remains in place.`);
+      }
+      verified.add(python);
+    }
+  }
+}
+
 async function jsonConfigHasServer(configPath, productId) {
   const config = await readJson(configPath);
   return Boolean(config.mcpServers?.[productId]);
@@ -768,10 +872,17 @@ async function downloadRuntime(source, runtimeDir, manifest = {}) {
   const useBundledRuntime = manifest.runtime?.source === "shared_installer";
   const serverText = await loadRuntimeText(source, "server.py", { useBundledRuntime });
   const matcherText = await loadRuntimeText(source, "skill_matcher.py", { useBundledRuntime });
+  const rendererText = await loadRuntimeText(source, "document_renderer.py", { useBundledRuntime });
   const requirementsText = await loadRuntimeText(source, "requirements.txt", { useBundledRuntime });
+  await fsp.copyFile(path.join(BUNDLED_RUNTIME_DIR, "software_use.py"), path.join(runtimeDir, "software_use.py"));
   await fsp.writeFile(path.join(runtimeDir, "server.py"), serverText, "utf8");
   await fsp.writeFile(path.join(runtimeDir, "skill_matcher.py"), matcherText, "utf8");
+  await fsp.writeFile(path.join(runtimeDir, "document_renderer.py"), rendererText, "utf8");
   await fsp.writeFile(path.join(runtimeDir, "requirements.txt"), requirementsText, "utf8");
+  if (useBundledRuntime && manifest.local_workspace === true) {
+    const { installWorkspaceRuntime } = await import("./workspace-runtime.js");
+    await installWorkspaceRuntime(BUNDLED_RUNTIME_DIR, runtimeDir);
+  }
 }
 
 async function loadRuntimeText(source, filePath, { useBundledRuntime = false } = {}) {
@@ -789,8 +900,7 @@ async function loadRuntimeText(source, filePath, { useBundledRuntime = false } =
 }
 
 function installPythonDeps(runtimeDir, vendorDir) {
-  const python = findPython();
-  if (!python) throw new Error("Python 3 is required but was not found on PATH.");
+  const python = requirePython();
   fs.mkdirSync(vendorDir, { recursive: true });
   const result = spawnSync(python, [
     "-m",
@@ -807,16 +917,6 @@ function installPythonDeps(runtimeDir, vendorDir) {
   }
 }
 
-function findPython() {
-  for (const candidate of ["python3", "python"]) {
-    const result = spawnSync(candidate, ["--version"], { encoding: "utf8" });
-    if (result.status === 0 && /Python 3\./.test(`${result.stdout}${result.stderr}`)) {
-      return candidate;
-    }
-  }
-  return null;
-}
-
 async function resolveLicenseKey(options, vertical, installDir) {
   const envNames = ["TASKSAI_LICENSE_KEY", "LAWTASKSAI_LICENSE_KEY"];
   for (const name of envNames) {
@@ -988,9 +1088,9 @@ function getInstaller(manifest) {
 
 function parseSource(source, ref) {
   if (source.startsWith("file://")) {
-    return { kind: "file", root: source.slice("file://".length), ref, repoUrl: source };
+    return { kind: "file", root: fileURLToPath(source), ref, repoUrl: source };
   }
-  if (source.startsWith("/") || source.startsWith(".")) {
+  if (path.isAbsolute(source) || source.startsWith(".")) {
     return { kind: "file", root: path.resolve(source), ref, repoUrl: source };
   }
   const rawMatch = source.match(/^https:\/\/raw\.githubusercontent\.com\/([^/]+)\/([^/]+)\/([^/]+)\/(.+)$/);
@@ -1194,18 +1294,19 @@ async function safeReportDoctorPassed({
   }
 }
 
-async function verifyRuntimeHealth({ serverPath, vendorDir }) {
-  const python = findPython();
-  if (!python) throw new Error("Python 3 is unavailable");
-  const pythonPath = [...pythonVendorPaths(vendorDir), process.env.PYTHONPATH]
+async function verifyRuntimeHealth({ serverPath, vendorDir, isolated = false, workspace = false, python = requirePython() }) {
+  const pythonPath = [...pythonVendorPaths(vendorDir), ...(isolated ? [path.dirname(serverPath)] : [process.env.PYTHONPATH])]
     .filter(Boolean)
     .join(path.delimiter);
   const check = [
     "import ast, pathlib, sys",
+    "assert sys.version_info >= (3, 10), 'Python 3.10 or newer is required'",
     "ast.parse(pathlib.Path(sys.argv[1]).read_text(encoding='utf-8'), filename=sys.argv[1])",
-    "import httpx, dotenv, mcp, docx"
+    "import httpx, dotenv, mcp, docx",
+    ...(isolated ? ["[ast.parse(p.read_text(encoding='utf-8'), filename=str(p)) for p in pathlib.Path(sys.argv[1]).parent.rglob('*.py')]"] : []),
+    ...(workspace ? ["import jsonschema, pypdf, xlsxwriter"] : [])
   ].join("; ");
-  const result = spawnSync(python, ["-c", check, serverPath], {
+  const result = spawnSync(python, [...(isolated ? ["-S"] : []), "-c", check, serverPath], {
     encoding: "utf8",
     timeout: 10000,
     env: { ...process.env, PYTHONPATH: pythonPath }
@@ -1289,23 +1390,6 @@ function findExistingAncestor(targetPath) {
   return current;
 }
 
-async function withLock(lockPath, callback) {
-  let handle;
-  try {
-    handle = await fsp.open(lockPath, "wx");
-    await handle.writeFile(String(process.pid));
-    return await callback();
-  } catch (error) {
-    if (error.code === "EEXIST") {
-      throw new Error(`Another TasksAI installer is already editing this config (${lockPath}).`);
-    }
-    throw error;
-  } finally {
-    if (handle) await handle.close();
-    await fsp.rm(lockPath, { force: true });
-  }
-}
-
 async function backupFile(filePath) {
   if (!fs.existsSync(filePath)) return null;
   const stamp = new Date().toISOString().replace(/[-:]/g, "").replace(/\..+/, "").replace("T", "-");
@@ -1380,6 +1464,7 @@ function redact(text) {
 export {
   INSTALLER_VERSION,
   authenticatedHeaders,
+  buildMcpServerConfig,
   doctor,
   parseArgs,
   parseEnv,
@@ -1389,5 +1474,7 @@ export {
   safeReportDoctorPassed,
   verifyProductionSource,
   verifyRuntimeHealth,
+  configuredPythonCommand,
+  verifyUpdateClientPython,
   verifySource
 };