WIP: AdvancedPaste ViewModel and test updates

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

doc/devdocs/modules/advancedpaste-python-scripts.md

@@ -0,0 +1,203 @@
+# Advanced Paste – Python Scripts
+
+Advanced Paste supports user-defined Python scripts that transform clipboard content. Scripts are
+discovered automatically from a configurable folder and appear as actions in the Advanced Paste UI.
+
+## Quick start
+
+1. Open the scripts folder — by default `%LOCALAPPDATA%\Microsoft\PowerToys\AdvancedPaste\Scripts`.
+   You can change this in **Settings → Advanced Paste → Python scripts → Scripts folder**.
+2. Drop a `.py` file into the folder.
+3. Add the required header comments at the top (see [Header format](#header-format)).
+4. Open the Advanced Paste UI (`Win+Shift+V`) — your script will appear in the action list.
+
+## Header format
+
+Every script must start with one or more **header comment lines**. Each line follows the pattern:
+
+```
+# @advancedpaste:<tag>   <value>
+```
+
+The parser reads the first 50 lines of each file; only lines beginning with `#` are inspected.
+
+### Supported tags
+
+| Tag | Required | Description |
+|-----|----------|-------------|
+| `name` | **Yes** | Display name shown in the Advanced Paste UI. |
+| `desc` | No | Short description / tooltip. |
+| `formats` | No | Comma-separated list of supported clipboard formats. Defaults to **all** formats when omitted. |
+| `platform` | No | `windows` (default) or `linux`. Determines the execution mode (see below). |
+| `version` | No | Free-form version string (reserved for future use). |
+| `requires` | No | Space-separated Python package requirements. See [Declaring dependencies](#declaring-dependencies). |
+
+### Formats
+
+| Value | Clipboard content |
+|-------|--------------------|
+| `text` | Plain or Unicode text (`CF_UNICODETEXT`) |
+| `html` | HTML fragment (`CF_HTML`) |
+| `image` | Bitmap / PNG image |
+| `audio` | Audio file(s) |
+| `video` | Video file(s) |
+| `files` or `file` | File paths (`CF_HDROP` / `StorageItems`) |
+| `any` | All of the above |
+
+Multiple values can be combined with commas:
+
+```python
+# @advancedpaste:formats text,html
+```
+
+## Execution modes
+
+### Windows mode (`platform windows`)
+
+The script runs directly on Windows via the configured Python interpreter.
+It **owns the clipboard** — use a library like `pywin32` (`win32clipboard`) to read
+and write clipboard data.
+
+**Invocation:**
+
+```
+python.exe "<script.py>" --format <detected_format> --work-dir "<temp_dir>"
+```
+
+**Minimal example — reverse text:**
+
+```python
+# @advancedpaste:name   Reverse text
+# @advancedpaste:formats text
+# @advancedpaste:platform windows
+import win32clipboard
+
+win32clipboard.OpenClipboard()
+text = win32clipboard.GetClipboardData(win32clipboard.CF_UNICODETEXT)
+win32clipboard.EmptyClipboard()
+win32clipboard.SetClipboardData(win32clipboard.CF_UNICODETEXT, text[::-1])
+win32clipboard.CloseClipboard()
+```
+
+After the script exits with code 0, Advanced Paste re-reads the clipboard and pastes
+the result. A non-zero exit code signals failure; stderr is shown in the error UI.
+
+### WSL / Linux mode (`platform linux`)
+
+The script runs inside WSL via `wsl.exe bash -l -c "python3 -X utf8 <script>"`.
+Instead of direct clipboard access, data is exchanged via **JSON**:
+
+| Direction | Channel | Schema |
+|-----------|---------|--------|
+| **Input** (C# → Python) | `stdin` (JSON) | See [Input payload](#input-payload) |
+| **Output** (Python → C#) | `stdout` (JSON) | See [Output payload](#output-payload) |
+
+#### Input payload
+
+```jsonc
+{
+  "version": 2,
+  "format": ["text"],           // array of detected clipboard format names
+  "work_dir": "/mnt/c/...",     // writable temp directory (WSL path)
+  "text": "Hello, world!",      // present when clipboard has text
+  "html": "<b>Hello</b>",       // present when clipboard has HTML
+  "image_path": "/mnt/c/.../input.png",  // present when clipboard has an image
+  "file_paths": ["/mnt/c/.../file.txt"]  // present when clipboard has files
+}
+```
+
+#### Output payload
+
+```jsonc
+{
+  "result_type": "text",        // "text" | "html" | "image" | "file" | "files"
+  "text": "HELLO, WORLD!",     // for result_type "text"
+  "html": "<b>HELLO</b>",      // for result_type "html"
+  "image_path": "/mnt/c/.../output.png",  // for result_type "image"
+  "file_paths": ["/mnt/c/.../out.txt"]    // for result_type "file"/"files"
+}
+```
+
+> **Note:** File paths in the output must use `/mnt/<drive>/...` format so that
+> Advanced Paste can map them back to Windows paths.
+
+**Minimal example — uppercase text (WSL):**
+
+```python
+# @advancedpaste:name   WSL Upper Case
+# @advancedpaste:formats text
+# @advancedpaste:platform linux
+import sys, json
+
+data = json.load(sys.stdin)
+text = data.get("text", "")
+json.dump({"result_type": "text", "text": text.upper()}, sys.stdout)
+```
+
+## Declaring dependencies
+
+Use `requires` to declare Python packages the script needs:
+
+```python
+# @advancedpaste:requires markitdown='markitdown[all]'
+# @advancedpaste:requires cv2=opencv-python-headless numpy requests
+```
+
+Each token is either:
+
+- **`import_name`** — the pip package is assumed to have the same name (e.g. `requests`).
+- **`import_name=pip_package`** — when the import name differs from the pip package
+  (e.g. `cv2=opencv-python-headless`, `PIL=Pillow`).
+
+Multiple tokens on one line are space-separated. You can also use multiple `requires` lines.
+
+### Automatic import detection
+
+Advanced Paste also scans the script body for `import` and `from ... import` statements
+and cross-references them against the Python standard library. Any non-stdlib import
+that is not already installed triggers a prompt to install it automatically.
+
+A built-in mapping table handles common mismatches (e.g. `win32clipboard` → `pywin32`,
+`cv2` → `opencv-python`, `PIL` → `Pillow`). For uncommon packages where the import name
+differs from the pip name, add an explicit `requires` entry.
+
+## Security — script trust
+
+The first time a script is executed (or after it has been modified), Advanced Paste
+shows a confirmation dialog. Upon approval the SHA-256 hash of the script is stored.
+Subsequent runs of the unchanged file skip the dialog.
+
+## Error handling
+
+When a script fails, Advanced Paste extracts the Python traceback from stderr and
+displays a user-friendly summary in the UI:
+
+- **ModuleNotFoundError** — identifies the missing module and suggests installing it.
+- **SyntaxError** — shows the file and line number.
+- **Timeout** — shows the configured timeout value (default 30 s; configurable in Settings).
+- **Other errors** — shows the last line of the traceback as a summary, with the full
+  traceback available in the expandable *Details* section.
+
+## Settings
+
+The following settings are available under **Settings → Advanced Paste → Python scripts**:
+
+| Setting | Description | Default |
+|---------|-------------|---------|
+| Python interpreter | Path to the Python executable. Leave blank for auto-detection. | *(auto-detect)* |
+| Scripts folder | Folder to scan for `.py` scripts. | `%LOCALAPPDATA%\Microsoft\PowerToys\AdvancedPaste\Scripts` |
+
+## Tips
+
+- Put reusable helper functions in a separate `.py` file without a `# @advancedpaste:name`
+  header — it will be ignored by the script discovery and can be imported by other scripts.
+- For complex WSL scripts that need packages not available via `apt`, consider using
+  a virtual environment. The script can re-exec itself with the venv interpreter:
+  ```python
+  import os, sys
+  venv = os.path.expanduser("~/my_env/bin/python3")
+  if os.path.exists(venv) and sys.executable != venv:
+      os.execv(venv, [venv] + sys.argv)
+  ```
+- The `--work-dir` argument (Windows mode) and `work_dir` JSON field (WSL mode) point to
+  a temporary directory that is cleaned up after execution. Use it for intermediate files.

src/modules/AdvancedPaste/AdvancedPaste.UnitTests/Mocks/IntegrationTestUserSettings.cs

@@ -57,6 +57,16 @@ internal sealed class IntegrationTestUserSettings : IUserSettings
 
     public PasteAIConfiguration PasteAIConfiguration => _configuration;
 
+    public IReadOnlyList<AdvancedPastePythonScriptAction> PythonScriptActions => Array.Empty<AdvancedPastePythonScriptAction>();
+
+    public string PythonScriptsFolder => string.Empty;
+
+    public string PythonExecutablePath => string.Empty;
+
+    public int PythonScriptTimeoutSeconds => 30;
+
+    public IReadOnlyDictionary<string, string> TrustedScriptHashes => new Dictionary<string, string>();
+
     public event EventHandler Changed;
 
     public Task SetActiveAIProviderAsync(string providerId)
@@ -65,4 +75,8 @@ internal sealed class IntegrationTestUserSettings : IUserSettings
         Changed?.Invoke(this, EventArgs.Empty);
         return Task.CompletedTask;
     }
+
+    public void StoreTrustedScriptHash(string scriptPath, string hash)
+    {
+    }
 }

src/modules/AdvancedPaste/AdvancedPaste.UnitTests/ServicesTests/PythonScriptServiceTests.cs

@@ -0,0 +1,378 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+
+using AdvancedPaste.Services.PythonScripts;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace AdvancedPaste.UnitTests.ServicesTests;
+
+[TestClass]
+public sealed class PythonScriptServiceTests
+{
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_DetectsSimpleImports()
+    {
+        var lines = new[]
+        {
+            "# @advancedpaste:name test",
+            "import requests",
+            "import numpy",
+            "import os",
+            "import sys",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(2, result.Count); // requests + numpy; os and sys are stdlib
+        Assert.IsTrue(result.Any(r => r.ImportName == "requests" && r.PipPackage == "requests"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "numpy" && r.PipPackage == "numpy"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_DetectsFromImports()
+    {
+        var lines = new[]
+        {
+            "from PIL import Image",
+            "from markitdown import MarkItDown",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(2, result.Count);
+        Assert.IsTrue(result.Any(r => r.ImportName == "PIL" && r.PipPackage == "Pillow"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "markitdown" && r.PipPackage == "markitdown"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_WellKnownMappings()
+    {
+        var lines = new[]
+        {
+            "import cv2",
+            "import win32clipboard",
+            "import yaml",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(3, result.Count);
+        Assert.IsTrue(result.Any(r => r.ImportName == "cv2" && r.PipPackage == "opencv-python"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "win32clipboard" && r.PipPackage == "pywin32"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "yaml" && r.PipPackage == "PyYAML"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_ExplicitRequirementsTakePrecedence()
+    {
+        var lines = new[]
+        {
+            "import cv2",
+            "import requests",
+        };
+
+        var explicitReqs = new List<PythonRequirement>
+        {
+            new("cv2", "opencv-python-headless"),
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, explicitReqs);
+
+        Assert.AreEqual(2, result.Count);
+
+        // cv2 should use the explicit pip package name, not the well-known mapping
+        var cv2Req = result.First(r => r.ImportName == "cv2");
+        Assert.AreEqual("opencv-python-headless", cv2Req.PipPackage);
+
+        // requests should be auto-detected
+        Assert.IsTrue(result.Any(r => r.ImportName == "requests"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_SkipsStdlib()
+    {
+        var lines = new[]
+        {
+            "import os",
+            "import sys",
+            "import json",
+            "import io",
+            "import pathlib",
+            "import tempfile",
+            "import subprocess",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(0, result.Count);
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_SkipsComments()
+    {
+        var lines = new[]
+        {
+            "# import requests",
+            "# from PIL import Image",
+            "import json",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(0, result.Count);
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_HandlesMultipleImportsOnOneLine()
+    {
+        var lines = new[]
+        {
+            "import requests, numpy, pandas",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(3, result.Count);
+        Assert.IsTrue(result.Any(r => r.ImportName == "requests"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "numpy"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "pandas"));
+    }
+
+    [TestMethod]
+    public void MergeWithAutoDetectedImports_HandlesSubmoduleImport()
+    {
+        var lines = new[]
+        {
+            "import win32com.client",
+            "from llama_cpp import Llama",
+        };
+
+        var result = PythonScriptService.MergeWithAutoDetectedImports(lines, []);
+
+        Assert.AreEqual(2, result.Count);
+        Assert.IsTrue(result.Any(r => r.ImportName == "win32com" && r.PipPackage == "pywin32"));
+        Assert.IsTrue(result.Any(r => r.ImportName == "llama_cpp" && r.PipPackage == "llama-cpp-python"));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_ModuleNotFoundError()
+    {
+        var stderr = """
+            Traceback (most recent call last):
+              File "C:\scripts\reverse.py", line 4, in <module>
+                import win32clipboard
+            ModuleNotFoundError: No module named 'win32clipboard'
+            """;
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("reverse.py"), $"Summary should mention the script: {summary}");
+        Assert.IsTrue(summary.Contains("line 4"), $"Summary should mention the line: {summary}");
+        Assert.IsTrue(summary.Contains("win32clipboard"), $"Summary should mention the module: {summary}");
+        Assert.IsTrue(summary.Contains("pywin32"), $"Summary should suggest pip package: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(details));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_SyntaxError()
+    {
+        var stderr = """
+            File "test.py", line 5
+                def foo(
+                       ^
+            SyntaxError: unexpected EOF while parsing
+            """;
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("test.py"), $"Summary should mention the script: {summary}");
+        Assert.IsTrue(summary.Contains("line 5"), $"Summary should mention the line: {summary}");
+        Assert.IsTrue(summary.Contains("Python syntax error:"), $"Summary: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(details));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_SyntaxErrorWithColumn()
+    {
+        var stderr = "  File \"script.py\", line 3\n    x = (1 +\n        ^\nSyntaxError: '(' was never closed\n";
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("script.py"), $"Summary should mention the script: {summary}");
+        Assert.IsTrue(summary.Contains("line 3"), $"Summary should mention the line: {summary}");
+        Assert.IsTrue(summary.Contains("col"), $"Summary should mention the column: {summary}");
+        Assert.IsTrue(summary.Contains("Python syntax error:"), $"Summary: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(details));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_GenericError()
+    {
+        var stderr = """
+            Traceback (most recent call last):
+              File "test.py", line 10, in <module>
+                result = 1 / 0
+            ZeroDivisionError: division by zero
+            """;
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("test.py"), $"Summary should mention the script: {summary}");
+        Assert.IsTrue(summary.Contains("line 10"), $"Summary should mention the line: {summary}");
+        Assert.IsTrue(summary.Contains("ZeroDivisionError"), $"Summary: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(details));
+    }
+
+    [TestMethod]
+    public void ParsePythonError_NestedTraceback_ShowsLastFrame()
+    {
+        var stderr = """
+            Traceback (most recent call last):
+              File "main.py", line 5, in <module>
+                helper()
+              File "helper.py", line 12, in helper
+                do_work()
+              File "worker.py", line 8, in do_work
+                raise RuntimeError("bad state")
+            RuntimeError: bad state
+            """;
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        Assert.IsTrue(summary.Contains("worker.py"), $"Summary should mention the last script in the chain: {summary}");
+        Assert.IsTrue(summary.Contains("line 8"), $"Summary should mention the line of the last frame: {summary}");
+        Assert.IsTrue(summary.Contains("bad state"), $"Summary should contain the error message: {summary}");
+    }
+
+    [TestMethod]
+    public void ParsePythonError_EmptyStderr()
+    {
+        var (summary, details) = PythonScriptService.ParsePythonError(string.Empty);
+
+        Assert.IsTrue(!string.IsNullOrEmpty(summary));
+        Assert.AreEqual(string.Empty, details);
+    }
+
+    [TestMethod]
+    public void ParsePythonError_NoTraceback_PlainStderr()
+    {
+        var stderr = "Something went wrong in the script\n";
+
+        var (summary, details) = PythonScriptService.ParsePythonError(stderr);
+
+        // No File "..." reference, so no location — just the message
+        Assert.IsTrue(summary.Contains("Something went wrong"), $"Summary: {summary}");
+        Assert.IsFalse(summary.Contains("line"), $"Summary should not contain 'line' without a traceback: {summary}");
+    }
+
+    [TestMethod]
+    public void ExtractLastTracebackLocation_BasicTraceback()
+    {
+        var lines = new[]
+        {
+            "Traceback (most recent call last):",
+            "  File \"script.py\", line 10, in <module>",
+            "    result = 1 / 0",
+            "ZeroDivisionError: division by zero",
+        };
+
+        var location = PythonScriptService.ExtractLastTracebackLocation(lines);
+
+        Assert.IsNotNull(location);
+        Assert.AreEqual("script.py", location.Value.FileName);
+        Assert.AreEqual(10, location.Value.Line);
+        Assert.IsNull(location.Value.Column);
+    }
+
+    [TestMethod]
+    public void ExtractLastTracebackLocation_WithCaret()
+    {
+        var lines = new[]
+        {
+            "  File \"test.py\", line 5",
+            "    def foo(",
+            "           ^",
+            "SyntaxError: unexpected EOF while parsing",
+        };
+
+        var location = PythonScriptService.ExtractLastTracebackLocation(lines);
+
+        Assert.IsNotNull(location);
+        Assert.AreEqual("test.py", location.Value.FileName);
+        Assert.AreEqual(5, location.Value.Line);
+        Assert.IsNotNull(location.Value.Column);
+    }
+
+    [TestMethod]
+    public void ExtractLastTracebackLocation_FullPath_ReturnsBasename()
+    {
+        var lines = new[]
+        {
+            "Traceback (most recent call last):",
+            "  File \"C:\\Users\\user\\scripts\\my_script.py\", line 42, in <module>",
+            "    some_call()",
+            "ValueError: invalid value",
+        };
+
+        var location = PythonScriptService.ExtractLastTracebackLocation(lines);
+
+        Assert.IsNotNull(location);
+        Assert.AreEqual("my_script.py", location.Value.FileName);
+        Assert.AreEqual(42, location.Value.Line);
+    }
+
+    [TestMethod]
+    public void ExtractLastTracebackLocation_NoFileLine_ReturnsNull()
+    {
+        var lines = new[]
+        {
+            "Some random error output",
+            "No traceback here",
+        };
+
+        var location = PythonScriptService.ExtractLastTracebackLocation(lines);
+
+        Assert.IsNull(location);
+    }
+
+    [TestMethod]
+    public void ParsePipInstallError_ExtractsErrorLine()
+    {
+        var stderr = """
+            Collecting some-package
+              Downloading some-package-1.0.tar.gz (15 kB)
+            ERROR: Could not find a version that satisfies the requirement some-package (from versions: none)
+            ERROR: No matching distribution found for some-package
+            """;
+
+        var (summary, fullStderr) = PythonScriptService.ParsePipInstallError(stderr);
+
+        Assert.IsTrue(summary.Contains("No matching distribution"), $"Summary should contain the last ERROR line: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(fullStderr));
+    }
+
+    [TestMethod]
+    public void ParsePipInstallError_NoErrorPrefix_UsesLastLine()
+    {
+        var stderr = "permission denied: /usr/lib/python3/dist-packages\n";
+
+        var (summary, fullStderr) = PythonScriptService.ParsePipInstallError(stderr);
+
+        Assert.IsTrue(summary.Contains("permission denied"), $"Summary: {summary}");
+        Assert.IsTrue(!string.IsNullOrEmpty(fullStderr));
+    }
+
+    [TestMethod]
+    public void ParsePipInstallError_EmptyStderr()
+    {
+        var (summary, fullStderr) = PythonScriptService.ParsePipInstallError(string.Empty);
+
+        Assert.AreEqual("unknown error", summary);
+        Assert.AreEqual(string.Empty, fullStderr);
+    }
+}

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/App.xaml.cs

@@ -14,6 +14,7 @@ using AdvancedPaste.Helpers;
 using AdvancedPaste.Models;
 using AdvancedPaste.Services;
 using AdvancedPaste.Services.CustomActions;
+using AdvancedPaste.Services.PythonScripts;
 using AdvancedPaste.Settings;
 using AdvancedPaste.ViewModels;
 using ManagedCommon;
@@ -83,6 +84,8 @@ namespace AdvancedPaste
                 services.AddSingleton<IPasteAIProviderFactory, PasteAIProviderFactory>();
                 services.AddSingleton<ICustomActionTransformService, CustomActionTransformService>();
                 services.AddSingleton<IKernelService, AdvancedAIKernelService>();
+                services.AddSingleton<IPythonScriptService, PythonScriptService>();
+                services.AddSingleton<IPythonScriptTrustService, PythonScriptTrustService>();
                 services.AddSingleton<IPasteFormatExecutor, PasteFormatExecutor>();
                 services.AddSingleton<OptionsViewModel>();
             }).Build();

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/Controls/PromptBox.xaml

@@ -755,63 +755,7 @@
                 <animations:OpacityAnimation To="0.0" Duration="0:0:0.167" />
             </animations:Implicit.HideAnimations>
         </TextBlock>
-        <Grid
-            x:Name="ErrorMessageGrid"
-            x:Uid="ErrorMessageGrid"
-            Grid.Row="1"
-            Margin="8,8,0,0"
-            ColumnSpacing="8"
-            Visibility="Collapsed">
-            <Grid.ColumnDefinitions>
-                <ColumnDefinition Width="Auto" />
-                <ColumnDefinition Width="*" />
-            </Grid.ColumnDefinitions>
-            <StackPanel Grid.Column="0" Orientation="Horizontal">
-                <ToolTipService.ToolTip>
-                    <ToolTip VerticalOffset="-105" Visibility="{x:Bind ViewModel.PasteActionError.HasDetails, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}">
-                        <StackPanel
-                            MinWidth="300"
-                            HorizontalAlignment="Stretch"
-                            Orientation="Vertical">
-                            <TextBox
-                                x:Name="AIErrorMessage"
-                                x:Uid="AIErrorMessage"
-                                FontSize="12"
-                                IsReadOnly="True"
-                                Text="{x:Bind ViewModel.PasteActionError.Details, Mode=OneWay}"
-                                TextWrapping="Wrap" />
-                        </StackPanel>
-                    </ToolTip>
-                </ToolTipService.ToolTip>
-                <FontIcon
-                    Margin="0,3,3,0"
-                    VerticalAlignment="Top"
-                    FontSize="12"
-                    Foreground="{ThemeResource AccentTextFillColorPrimaryBrush}"
-                    Glyph="&#xE946;"
-                    Visibility="{x:Bind ViewModel.PasteActionError.HasDetails, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}" />
-                <TextBlock
-                    FontWeight="SemiBold"
-                    Foreground="{ThemeResource SystemFillColorCriticalBrush}"
-                    Style="{StaticResource CaptionTextBlockStyle}"
-                    Text="{x:Bind ViewModel.PasteActionError.Text, Mode=OneWay}" />
-            </StackPanel>
-            <HyperlinkButton
-                x:Uid="SettingsBtn"
-                Grid.Column="1"
-                Margin="0,-1,0,0"
-                Padding="0"
-                HorizontalAlignment="Left"
-                VerticalAlignment="Top"
-                Command="{x:Bind ViewModel.OpenSettingsCommand}"
-                FontSize="12" />
-            <animations:Implicit.ShowAnimations>
-                <animations:OpacityAnimation To="1.0" Duration="0:0:0.6" />
-            </animations:Implicit.ShowAnimations>
-            <animations:Implicit.HideAnimations>
-                <animations:OpacityAnimation To="0.0" Duration="0:0:0.167" />
-            </animations:Implicit.HideAnimations>
-        </Grid>
+        <!--  Error message grid moved to MainPage.xaml so it remains enabled when PromptBox is disabled  -->
         <VisualStateManager.VisualStateGroups>
             <VisualStateGroup x:Name="CommonStates">
                 <VisualState x:Name="DefaultState" />
@@ -832,7 +776,6 @@
                     <VisualState.Setters>
                         <Setter Target="InputTxtBox.BorderBrush" Value="{ThemeResource SystemFillColorCriticalBrush}" />
                         <Setter Target="DisclaimerPresenter.Visibility" Value="Collapsed" />
-                        <Setter Target="ErrorMessageGrid.Visibility" Value="Visible" />
                     </VisualState.Setters>
                 </VisualState>
             </VisualStateGroup>

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/MainWindow.xaml.cs

@@ -43,7 +43,8 @@ namespace AdvancedPaste
                 double GetHeight(int maxCustomActionCount) =>
                     baseHeight +
                     new PasteFormatsToHeightConverter().GetHeight(coreActionCount + _userSettings.AdditionalActions.Count) +
-                    new PasteFormatsToHeightConverter() { MaxItems = maxCustomActionCount }.GetHeight(_optionsViewModel.IsCustomAIServiceEnabled ? _userSettings.CustomActions.Count : 0);
+                    new PasteFormatsToHeightConverter() { MaxItems = maxCustomActionCount }.GetHeight(_optionsViewModel.IsCustomAIServiceEnabled ? _userSettings.CustomActions.Count : 0) +
+                    new PasteFormatsToHeightConverter() { MaxItems = maxCustomActionCount }.GetHeight(_optionsViewModel.PythonScriptPasteFormats.Count);
 
                 MinHeight = GetHeight(1);
                 Height = GetHeight(5);
@@ -59,6 +60,7 @@ namespace AdvancedPaste
                     UpdateHeight();
                 }
             };
+            _optionsViewModel.PythonScriptPasteFormats.CollectionChanged += (_, _) => UpdateHeight();
 
             AppWindow.SetIcon("Assets/AdvancedPaste/AdvancedPaste.ico");
             this.ExtendsContentIntoTitleBar = true;

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/Pages/MainPage.xaml

@@ -144,6 +144,7 @@
     </Page.KeyboardAccelerators>
     <Grid>
         <Grid.RowDefinitions>
+            <RowDefinition Height="Auto" />
             <RowDefinition Height="Auto" />
             <RowDefinition Height="Auto" />
             <RowDefinition Height="*" />
@@ -299,13 +300,65 @@
                 </StackPanel>
             </controls:PromptBox.Footer>
         </controls:PromptBox>
-        <ScrollViewer Grid.Row="2">
+        <Grid
+            x:Name="ErrorMessageGrid"
+            Grid.Row="2"
+            Margin="20,4,20,0"
+            ColumnSpacing="8"
+            Visibility="{x:Bind ViewModel.PasteActionError.HasText, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}">
+            <Grid.ColumnDefinitions>
+                <ColumnDefinition Width="Auto" />
+                <ColumnDefinition Width="*" />
+                <ColumnDefinition Width="Auto" />
+                <ColumnDefinition Width="Auto" />
+            </Grid.ColumnDefinitions>
+            <FontIcon
+                Grid.Column="0"
+                Margin="0,3,3,0"
+                VerticalAlignment="Top"
+                FontSize="12"
+                Foreground="{ThemeResource AccentTextFillColorPrimaryBrush}"
+                Glyph="&#xE946;"
+                Visibility="{x:Bind ViewModel.PasteActionError.HasDetails, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}" />
+            <TextBlock
+                Grid.Column="1"
+                FontWeight="SemiBold"
+                Foreground="{ThemeResource SystemFillColorCriticalBrush}"
+                Style="{StaticResource CaptionTextBlockStyle}"
+                MaxLines="2"
+                TextTrimming="CharacterEllipsis"
+                TextWrapping="Wrap"
+                Text="{x:Bind ViewModel.PasteActionError.Text, Mode=OneWay}" />
+            <HyperlinkButton
+                x:Name="ShowErrorDetailsBtn"
+                x:Uid="ShowErrorDetailsBtn"
+                Grid.Column="2"
+                Margin="4,-1,0,0"
+                Padding="0"
+                HorizontalAlignment="Left"
+                VerticalAlignment="Top"
+                Click="ShowErrorDetailsBtn_Click"
+                FontSize="12"
+                Visibility="{x:Bind ViewModel.PasteActionError.HasDetails, Mode=OneWay, Converter={StaticResource BoolToVisibilityConverter}}" />
+            <HyperlinkButton
+                x:Uid="SettingsBtn"
+                Grid.Column="3"
+                Margin="0,-1,0,0"
+                Padding="0"
+                HorizontalAlignment="Left"
+                VerticalAlignment="Top"
+                Command="{x:Bind ViewModel.OpenSettingsCommand}"
+                FontSize="12" />
+        </Grid>
+        <ScrollViewer Grid.Row="3">
             <Grid RowSpacing="4">
                 <Grid.RowDefinitions>
                     <RowDefinition Height="{x:Bind ViewModel.StandardPasteFormats.Count, Mode=OneWay, Converter={StaticResource standardPasteFormatsToHeightConverter}}" />
                     <RowDefinition Height="Auto" />
                     <RowDefinition Height="*" MinHeight="{x:Bind ViewModel.CustomActionPasteFormats.Count, Mode=OneWay, Converter={StaticResource customActionsToMinHeightConverter}}" />
                     <RowDefinition Height="Auto" />
+                    <RowDefinition Height="*" MinHeight="{x:Bind ViewModel.PythonScriptPasteFormats.Count, Mode=OneWay, Converter={StaticResource customActionsToMinHeightConverter}}" />
+                    <RowDefinition Height="Auto" />
                     <RowDefinition Height="Auto" />
                 </Grid.RowDefinitions>
                 <ListView
@@ -341,6 +394,27 @@
                     ScrollViewer.VerticalScrollMode="Disabled"
                     SelectionMode="None"
                     TabIndex="2" />
+
+                <Rectangle
+                    Grid.Row="3"
+                    Height="1"
+                    HorizontalAlignment="Stretch"
+                    Fill="{ThemeResource DividerStrokeColorDefaultBrush}"
+                    Visibility="{x:Bind ViewModel.PythonScriptPasteFormats.Count, Mode=OneWay, Converter={StaticResource countToVisibilityConverter}}" />
+
+                <ListView
+                    x:Name="PythonScriptsListView"
+                    Grid.Row="4"
+                    VerticalAlignment="Top"
+                    IsItemClickEnabled="True"
+                    ItemClick="PasteFormat_ItemClick"
+                    ItemContainerTransitions="{x:Null}"
+                    ItemTemplateSelector="{StaticResource PasteFormatTemplateSelector}"
+                    ItemsSource="{x:Bind ViewModel.PythonScriptPasteFormats, Mode=OneWay}"
+                    ScrollViewer.VerticalScrollBarVisibility="Disabled"
+                    ScrollViewer.VerticalScrollMode="Disabled"
+                    SelectionMode="None"
+                    TabIndex="3" />
             </Grid>
         </ScrollViewer>
     </Grid>

src/modules/AdvancedPaste/AdvancedPaste/AdvancedPasteXAML/Pages/MainPage.xaml.cs

@@ -208,5 +208,43 @@ namespace AdvancedPaste.Pages
                 Clipboard.SetHistoryItemAsContent(item.Item);
             }
         }
+
+        private async void ShowErrorDetailsBtn_Click(object sender, RoutedEventArgs e)
+        {
+            var details = ViewModel.PasteActionError?.Details;
+            if (string.IsNullOrEmpty(details))
+            {
+                return;
+            }
+
+            var scrollViewer = new ScrollViewer
+            {
+                MaxHeight = 400,
+                MinWidth = 400,
+                HorizontalScrollBarVisibility = ScrollBarVisibility.Disabled,
+                VerticalScrollBarVisibility = ScrollBarVisibility.Auto,
+            };
+
+            var textBlock = new TextBlock
+            {
+                Text = details,
+                TextWrapping = TextWrapping.Wrap,
+                FontFamily = new Microsoft.UI.Xaml.Media.FontFamily("Consolas"),
+                FontSize = 12,
+                IsTextSelectionEnabled = true,
+            };
+
+            scrollViewer.Content = textBlock;
+
+            var dialog = new ContentDialog
+            {
+                Title = ResourceLoaderInstance.ResourceLoader.GetString("ErrorDetailsDialogTitle"),
+                CloseButtonText = ResourceLoaderInstance.ResourceLoader.GetString("ErrorDetailsDialogClose"),
+                Content = scrollViewer,
+                XamlRoot = this.XamlRoot,
+            };
+
+            await dialog.ShowAsync();
+        }
     }
 }

src/modules/AdvancedPaste/AdvancedPaste/Helpers/IUserSettings.cs

@@ -27,8 +27,22 @@ namespace AdvancedPaste.Settings
 
         public PasteAIConfiguration PasteAIConfiguration { get; }
 
+        public IReadOnlyList<AdvancedPastePythonScriptAction> PythonScriptActions { get; }
+
+        public bool IsPythonScriptsEnabled { get; }
+
+        public string PythonScriptsFolder { get; }
+
+        public string PythonExecutablePath { get; }
+
+        public int PythonScriptTimeoutSeconds { get; }
+
+        public IReadOnlyDictionary<string, string> TrustedScriptHashes { get; }
+
         public event EventHandler Changed;
 
         Task SetActiveAIProviderAsync(string providerId);
+
+        void StoreTrustedScriptHash(string scriptPath, string hash);
     }
 }

src/modules/AdvancedPaste/AdvancedPaste/Helpers/UserSettings.cs

@@ -4,6 +4,7 @@
 
 using System;
 using System.Collections.Generic;
+using System.IO;
 using System.IO.Abstractions;
 using System.Linq;
 using System.Threading;
@@ -25,6 +26,10 @@ namespace AdvancedPaste.Settings
         private readonly Lock _loadingSettingsLock = new();
         private readonly List<PasteFormats> _additionalActions;
         private readonly List<AdvancedPasteCustomAction> _customActions;
+        private readonly List<AdvancedPastePythonScriptAction> _pythonScriptActions;
+        private FileSystemWatcher _scriptFolderWatcher;
+        private CancellationTokenSource _scriptFolderDebounce;
+        private string _watchedScriptsFolder = string.Empty;
 
         private const string AdvancedPasteModuleName = "AdvancedPaste";
         private const int MaxNumberOfRetry = 5;
@@ -48,6 +53,18 @@ namespace AdvancedPaste.Settings
 
         public PasteAIConfiguration PasteAIConfiguration { get; private set; }
 
+        public IReadOnlyList<AdvancedPastePythonScriptAction> PythonScriptActions => _pythonScriptActions;
+
+        public string PythonScriptsFolder { get; private set; }
+
+        public bool IsPythonScriptsEnabled { get; private set; }
+
+        public string PythonExecutablePath { get; private set; }
+
+        public int PythonScriptTimeoutSeconds { get; private set; } = 30;
+
+        public IReadOnlyDictionary<string, string> TrustedScriptHashes { get; private set; } = new Dictionary<string, string>();
+
         public UserSettings(IFileSystem fileSystem)
         {
             _settingsUtils = new SettingsUtils(fileSystem);
@@ -57,8 +74,12 @@ namespace AdvancedPaste.Settings
             CloseAfterLosingFocus = false;
             EnableClipboardPreview = true;
             PasteAIConfiguration = new PasteAIConfiguration();
+            PythonScriptsFolder = GetDefaultScriptsFolder();
+            PythonExecutablePath = string.Empty;
+            PythonScriptTimeoutSeconds = 30;
             _additionalActions = [];
             _customActions = [];
+            _pythonScriptActions = [];
             _taskScheduler = TaskScheduler.FromCurrentSynchronizationContext();
 
             LoadSettingsFromJson();
@@ -66,6 +87,14 @@ namespace AdvancedPaste.Settings
             _watcher = Helper.GetFileWatcher(AdvancedPasteModuleName, "settings.json", OnSettingsFileChanged, fileSystem);
         }
 
+        private static string GetDefaultScriptsFolder() =>
+            System.IO.Path.Combine(
+                Environment.GetFolderPath(Environment.SpecialFolder.LocalApplicationData),
+                "Microsoft",
+                "PowerToys",
+                "AdvancedPaste",
+                "Scripts");
+
         private void OnSettingsFileChanged()
         {
             lock (_loadingSettingsLock)
@@ -131,6 +160,22 @@ namespace AdvancedPaste.Settings
                                 _customActions.Clear();
                                 _customActions.AddRange(properties.CustomActions.Value.Where(customAction => customAction.IsShown && customAction.IsValid));
 
+                                var pythonScripts = properties.PythonScripts ?? new AdvancedPastePythonScriptSettings();
+                                IsPythonScriptsEnabled = pythonScripts.IsEnabled;
+                                PythonScriptsFolder = string.IsNullOrWhiteSpace(pythonScripts.ScriptsFolder)
+                                    ? GetDefaultScriptsFolder()
+                                    : pythonScripts.ScriptsFolder;
+                                PythonExecutablePath = pythonScripts.PythonExecutablePath ?? string.Empty;
+                                PythonScriptTimeoutSeconds = pythonScripts.TimeoutSeconds > 0 ? pythonScripts.TimeoutSeconds : 30;
+                                TrustedScriptHashes = new Dictionary<string, string>(
+                                    pythonScripts.TrustedScriptHashes ?? new Dictionary<string, string>(),
+                                    StringComparer.OrdinalIgnoreCase);
+
+                                _pythonScriptActions.Clear();
+                                _pythonScriptActions.AddRange(pythonScripts.Value.Where(a => a.IsShown));
+
+                                UpdateScriptFolderWatcher(PythonScriptsFolder);
+
                                 Changed?.Invoke(this, EventArgs.Empty);
                             }
 
@@ -295,6 +340,102 @@ namespace AdvancedPaste.Settings
             return string.IsNullOrWhiteSpace(filtered) ? "default" : filtered.ToLowerInvariant();
         }
 
+        private void UpdateScriptFolderWatcher(string folderPath)
+        {
+            if (string.Equals(_watchedScriptsFolder, folderPath, StringComparison.OrdinalIgnoreCase))
+            {
+                return;
+            }
+
+            _scriptFolderWatcher?.Dispose();
+            _scriptFolderWatcher = null;
+            _watchedScriptsFolder = folderPath;
+
+            if (string.IsNullOrWhiteSpace(folderPath))
+            {
+                return;
+            }
+
+            try
+            {
+                if (!System.IO.Directory.Exists(folderPath))
+                {
+                    System.IO.Directory.CreateDirectory(folderPath);
+                }
+
+                _scriptFolderWatcher = new FileSystemWatcher(folderPath, "*.py")
+                {
+                    NotifyFilter = NotifyFilters.FileName | NotifyFilters.LastWrite | NotifyFilters.CreationTime,
+                    EnableRaisingEvents = true,
+                    IncludeSubdirectories = false,
+                };
+
+                _scriptFolderWatcher.Changed += OnScriptFolderChanged;
+                _scriptFolderWatcher.Created += OnScriptFolderChanged;
+                _scriptFolderWatcher.Deleted += OnScriptFolderChanged;
+                _scriptFolderWatcher.Renamed += OnScriptFolderChanged;
+            }
+            catch (Exception ex)
+            {
+                Logger.LogError($"Failed to set up script folder watcher for {folderPath}", ex);
+            }
+        }
+
+        private void OnScriptFolderChanged(object sender, FileSystemEventArgs e)
+        {
+            lock (_loadingSettingsLock)
+            {
+                _scriptFolderDebounce?.Cancel();
+                _scriptFolderDebounce = new CancellationTokenSource();
+
+                Task.Delay(TimeSpan.FromMilliseconds(500))
+                    .ContinueWith(
+                        _ =>
+                        {
+                            Task.Factory
+                                .StartNew(
+                                    () => Changed?.Invoke(this, EventArgs.Empty),
+                                    CancellationToken.None,
+                                    TaskCreationOptions.None,
+                                    _taskScheduler)
+                                .Wait();
+                        },
+                        _scriptFolderDebounce.Token,
+                        TaskContinuationOptions.NotOnCanceled,
+                        TaskScheduler.Default);
+            }
+        }
+
+        public void StoreTrustedScriptHash(string scriptPath, string hash)
+        {
+            lock (_loadingSettingsLock)
+            {
+                try
+                {
+                    var settings = _settingsUtils.GetSettingsOrDefault<AdvancedPasteSettings>(AdvancedPasteModuleName);
+                    if (settings?.Properties?.PythonScripts is null)
+                    {
+                        return;
+                    }
+
+                    settings.Properties.PythonScripts.TrustedScriptHashes ??= new Dictionary<string, string>();
+                    settings.Properties.PythonScripts.TrustedScriptHashes[scriptPath] = hash;
+                    settings.Save(_settingsUtils);
+
+                    // Update in-memory cache.
+                    var updated = new Dictionary<string, string>(TrustedScriptHashes, StringComparer.OrdinalIgnoreCase)
+                    {
+                        [scriptPath] = hash,
+                    };
+                    TrustedScriptHashes = updated;
+                }
+                catch (Exception ex)
+                {
+                    Logger.LogError("Failed to store trusted script hash", ex);
+                }
+            }
+        }
+
         public async Task SetActiveAIProviderAsync(string providerId)
         {
             if (string.IsNullOrWhiteSpace(providerId))
@@ -387,6 +528,8 @@ namespace AdvancedPaste.Settings
                 if (disposing)
                 {
                     _cancellationTokenSource?.Dispose();
+                    _scriptFolderDebounce?.Dispose();
+                    _scriptFolderWatcher?.Dispose();
                     _watcher?.Dispose();
                 }
 

src/modules/AdvancedPaste/AdvancedPaste/Models/PasteFormat.cs

@@ -40,6 +40,14 @@ public sealed class PasteFormat
             IsSavedQuery = isSavedQuery,
         };
 
+    public static PasteFormat CreatePythonScriptFormat(string name, string scriptPath, ClipboardFormat availableFormats) =>
+        new(PasteFormats.PythonScript, availableFormats, isAIServiceEnabled: false)
+        {
+            Name = name,
+            Prompt = scriptPath,
+            IsSavedQuery = true,
+        };
+
     public PasteFormatMetadataAttribute Metadata => MetadataDict[Format];
 
     public string IconGlyph => Metadata.IconGlyph;

src/modules/AdvancedPaste/AdvancedPaste/Models/PasteFormats.cs

@@ -122,4 +122,13 @@ public enum PasteFormats
         KernelFunctionDescription = "Takes user instructions and applies them to the current clipboard content (text or image). Use this function for image analysis, description, or transformation tasks beyond simple OCR.",
         RequiresPrompt = true)]
     CustomTextTransformation,
+
+    [PasteFormatMetadata(
+        IsCoreAction = false,
+        IconGlyph = "\uE943",
+        RequiresAIService = false,
+        CanPreview = true,
+        SupportedClipboardFormats = ClipboardFormat.Text | ClipboardFormat.Html | ClipboardFormat.Image | ClipboardFormat.Audio | ClipboardFormat.Video | ClipboardFormat.File,
+        KernelFunctionDescription = "Runs a user-provided Python script on clipboard content.")]
+    PythonScript,
 }

src/modules/AdvancedPaste/AdvancedPaste/Services/PasteFormatExecutor.cs

@@ -1,4 +1,4 @@
-// Copyright (c) Microsoft Corporation
+// Copyright (c) Microsoft Corporation
 // The Microsoft Corporation licenses this file to you under the MIT license.
 // See the LICENSE file in the project root for more information.
 
@@ -9,15 +9,23 @@ using System.Threading.Tasks;
 using AdvancedPaste.Helpers;
 using AdvancedPaste.Models;
 using AdvancedPaste.Services.CustomActions;
+using AdvancedPaste.Services.PythonScripts;
+using ManagedCommon;
 using Microsoft.PowerToys.Telemetry;
 using Windows.ApplicationModel.DataTransfer;
 
 namespace AdvancedPaste.Services;
 
-public sealed class PasteFormatExecutor(IKernelService kernelService, ICustomActionTransformService customActionTransformService) : IPasteFormatExecutor
+public sealed class PasteFormatExecutor(
+    IKernelService kernelService,
+    ICustomActionTransformService customActionTransformService,
+    IPythonScriptService pythonScriptService,
+    IPythonScriptTrustService pythonScriptTrustService) : IPasteFormatExecutor
 {
     private readonly IKernelService _kernelService = kernelService;
     private readonly ICustomActionTransformService _customActionTransformService = customActionTransformService;
+    private readonly IPythonScriptService _pythonScriptService = pythonScriptService;
+    private readonly IPythonScriptTrustService _pythonScriptTrustService = pythonScriptTrustService;
 
     public async Task<DataPackage> ExecutePasteFormatAsync(PasteFormat pasteFormat, PasteActionSource source, CancellationToken cancellationToken, IProgress<double> progress)
     {
@@ -32,6 +40,15 @@ public sealed class PasteFormatExecutor(IKernelService kernelService, ICustomAct
 
         var clipboardData = Clipboard.GetContent();
 
+        // PythonScript must NOT run inside Task.Run: the trust confirmation (ContentDialog)
+        // requires the UI (XAML) thread and will throw if called from a thread-pool thread.
+        // Python script execution is fully async (process.WaitForExitAsync), so it is safe
+        // to await it directly without wrapping in Task.Run.
+        if (format == PasteFormats.PythonScript)
+        {
+            return await ExecutePythonScriptAsync(pasteFormat.Prompt, clipboardData, cancellationToken, progress);
+        }
+
         // Run on thread-pool; although we use Async routines consistently, some actions still occasionally take a long time without yielding.
         return await Task.Run(async () =>
             pasteFormat.Format switch
@@ -42,6 +59,85 @@ public sealed class PasteFormatExecutor(IKernelService kernelService, ICustomAct
             });
     }
 
+    private async Task<DataPackage> ExecutePythonScriptAsync(
+        string scriptPath,
+        DataPackageView clipboardData,
+        CancellationToken cancellationToken,
+        IProgress<double> progress)
+    {
+        // Security: ensure the script is trusted before executing.
+        if (!_pythonScriptTrustService.IsTrusted(scriptPath))
+        {
+            var hash = _pythonScriptTrustService.ComputeHash(scriptPath);
+            var approved = await _pythonScriptTrustService.RequestTrustAsync(scriptPath, hash);
+
+            if (!approved)
+            {
+                throw new OperationCanceledException("User declined to trust the Python script.");
+            }
+
+            _pythonScriptTrustService.StoreTrust(scriptPath, hash);
+        }
+
+        var metadata = _pythonScriptService.ReadMetadata(scriptPath);
+
+        // Pre-flight: check for missing packages and offer to install them.
+        var missingPackages = await _pythonScriptService.GetMissingRequirementsAsync(metadata, cancellationToken);
+        if (missingPackages.Count > 0)
+        {
+            var approved = await _pythonScriptTrustService.RequestInstallAsync(metadata.Name, missingPackages);
+            if (!approved)
+            {
+                throw new OperationCanceledException("User declined to install missing Python packages.");
+            }
+
+            await _pythonScriptService.InstallRequirementsAsync(missingPackages, metadata.Platform, cancellationToken);
+        }
+
+        var detectedFormat = await clipboardData.GetAvailableFormatsAsync();
+
+        if (string.Equals(metadata.Platform, "linux", StringComparison.OrdinalIgnoreCase))
+        {
+            return await _pythonScriptService.ExecuteWslScriptAsync(scriptPath, clipboardData, detectedFormat, cancellationToken, progress);
+        }
+        else
+        {
+            // Windows mode: script modifies the clipboard in-process; we return the updated clipboard.
+            await _pythonScriptService.ExecuteWindowsScriptAsync(scriptPath, detectedFormat, cancellationToken, progress);
+
+            // Re-read clipboard after script has run.
+            return Clipboard.GetContent() is { } updatedView
+                ? await DataPackageFromViewAsync(updatedView)
+                : new DataPackage();
+        }
+    }
+
+    private static async Task<DataPackage> DataPackageFromViewAsync(DataPackageView view)
+    {
+        var pkg = new DataPackage();
+
+        if (view.Contains(StandardDataFormats.Text))
+        {
+            pkg.SetText(await view.GetTextAsync());
+        }
+        else if (view.Contains(StandardDataFormats.Html))
+        {
+            pkg.SetHtmlFormat(await view.GetHtmlFormatAsync());
+        }
+        else if (view.Contains(StandardDataFormats.StorageItems))
+        {
+            var items = await view.GetStorageItemsAsync();
+            pkg.SetStorageItems(items);
+        }
+        else if (view.Contains(StandardDataFormats.Bitmap))
+        {
+            var bitmap = await view.GetBitmapAsync();
+            pkg.SetBitmap(bitmap);
+        }
+
+        return pkg;
+    }
+
     private static void WriteTelemetry(PasteFormats format, PasteActionSource source)
     {
         switch (source)

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/IPythonScriptService.cs

@@ -0,0 +1,62 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Collections.Generic;
+using System.Threading;
+using System.Threading.Tasks;
+
+using AdvancedPaste.Models;
+using Windows.ApplicationModel.DataTransfer;
+
+namespace AdvancedPaste.Services.PythonScripts;
+
+public interface IPythonScriptService
+{
+    /// <summary>
+    /// Windows mode: the script directly manipulates the clipboard. C# waits for the process to exit.
+    /// </summary>
+    Task ExecuteWindowsScriptAsync(string scriptPath, ClipboardFormat detectedFormat, CancellationToken cancellationToken, IProgress<double> progress);
+
+    /// <summary>
+    /// WSL mode: C# passes data via JSON stdin, receives a DataPackage from JSON stdout.
+    /// </summary>
+    Task<DataPackage> ExecuteWslScriptAsync(string scriptPath, DataPackageView clipboardData, ClipboardFormat detectedFormat, CancellationToken cancellationToken, IProgress<double> progress);
+
+    /// <summary>
+    /// Parses the @advancedpaste: header comments from a Python script file.
+    /// </summary>
+    PythonScriptMetadata ReadMetadata(string scriptPath);
+
+    /// <summary>
+    /// Discovers all .py scripts in <paramref name="folderPath"/> and returns their metadata.
+    /// </summary>
+    IReadOnlyList<PythonScriptMetadata> DiscoverScripts(string folderPath);
+
+    /// <summary>
+    /// Finds the Python executable to use. Returns null if none is found.
+    /// </summary>
+    string TryFindPythonExecutable(string overridePath = null);
+
+    /// <summary>
+    /// Returns true if wsl.exe is available on this machine.
+    /// </summary>
+    bool IsWslAvailable();
+
+    /// <summary>
+    /// Checks which of the declared requirements are not yet importable.
+    /// Returns an empty list if all packages are installed.
+    /// </summary>
+    Task<IReadOnlyList<PythonRequirement>> GetMissingRequirementsAsync(
+        PythonScriptMetadata metadata,
+        CancellationToken cancellationToken);
+
+    /// <summary>
+    /// Installs the given packages via pip / pip3.
+    /// </summary>
+    Task InstallRequirementsAsync(
+        IReadOnlyList<PythonRequirement> requirements,
+        string platform,
+        CancellationToken cancellationToken);
+}

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/IPythonScriptTrustService.cs

@@ -0,0 +1,37 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Collections.Generic;
+using System.Threading.Tasks;
+
+namespace AdvancedPaste.Services.PythonScripts;
+
+public interface IPythonScriptTrustService
+{
+    /// <summary>
+    /// Returns true if the script at <paramref name="scriptPath"/> is currently trusted (hash matches stored value).
+    /// </summary>
+    bool IsTrusted(string scriptPath);
+
+    /// <summary>
+    /// Shows a UI confirmation dialog for the script. Returns true if the user approved execution.
+    /// </summary>
+    Task<bool> RequestTrustAsync(string scriptPath, string hash);
+
+    /// <summary>
+    /// Persists the trust entry for <paramref name="scriptPath"/> with the given <paramref name="hash"/>.
+    /// </summary>
+    void StoreTrust(string scriptPath, string hash);
+
+    /// <summary>
+    /// Computes the SHA-256 hash of the script file and returns the hex string.
+    /// </summary>
+    string ComputeHash(string scriptPath);
+
+    /// <summary>
+    /// Shows a confirmation dialog listing the missing packages and asking the user
+    /// whether to install them. Returns true if the user approved installation.
+    /// </summary>
+    Task<bool> RequestInstallAsync(string scriptName, IReadOnlyList<PythonRequirement> missingPackages);
+}

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/PythonRequirement.cs

@@ -0,0 +1,13 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+namespace AdvancedPaste.Services.PythonScripts;
+
+/// <summary>
+/// Represents a single Python package requirement declared via
+/// <c># @advancedpaste:requires import_name=pip_package</c>.
+/// </summary>
+/// <param name="ImportName">The Python import name used in the script (e.g. "cv2").</param>
+/// <param name="PipPackage">The pip install name (e.g. "opencv-python-headless"). Equals <see cref="ImportName"/> when not explicitly specified.</param>
+public sealed record PythonRequirement(string ImportName, string PipPackage);

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/PythonScriptMetadata.cs

@@ -0,0 +1,19 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Collections.Generic;
+
+using AdvancedPaste.Models;
+
+namespace AdvancedPaste.Services.PythonScripts;
+
+public sealed record PythonScriptMetadata(
+    string ScriptPath,
+    string Name,
+    string Description,
+    ClipboardFormat SupportedFormats,
+    string Platform,
+    string Version,
+    bool IsEnabled,
+    IReadOnlyList<PythonRequirement> Requirements);

src/modules/AdvancedPaste/AdvancedPaste/Services/PythonScripts/PythonScriptTrustService.cs

@@ -0,0 +1,126 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Collections.Generic;
+using System.IO;
+using System.Linq;
+using System.Security.Cryptography;
+using System.Threading.Tasks;
+
+using AdvancedPaste.Helpers;
+using AdvancedPaste.Settings;
+using ManagedCommon;
+using Microsoft.UI.Xaml.Controls;
+
+namespace AdvancedPaste.Services.PythonScripts;
+
+public sealed class PythonScriptTrustService(IUserSettings userSettings) : IPythonScriptTrustService
+{
+    private readonly IUserSettings _userSettings = userSettings;
+
+    public bool IsTrusted(string scriptPath)
+    {
+        var hashes = _userSettings.TrustedScriptHashes;
+        if (hashes is null || !hashes.TryGetValue(scriptPath, out var storedHash))
+        {
+            return false;
+        }
+
+        try
+        {
+            var currentHash = ComputeHash(scriptPath);
+            return string.Equals(currentHash, storedHash, StringComparison.OrdinalIgnoreCase);
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError($"Failed to compute hash for {scriptPath}", ex);
+            return false;
+        }
+    }
+
+    public async Task<bool> RequestTrustAsync(string scriptPath, string hash)
+    {
+        try
+        {
+            var resourceLoader = ResourceLoaderInstance.ResourceLoader;
+
+            var dialog = new ContentDialog
+            {
+                Title = resourceLoader.GetString("PythonScriptTrustTitle"),
+                Content = string.Format(
+                    System.Globalization.CultureInfo.CurrentCulture,
+                    resourceLoader.GetString("PythonScriptTrustContent"),
+                    scriptPath),
+                PrimaryButtonText = resourceLoader.GetString("PythonScriptTrustConfirm"),
+                CloseButtonText = resourceLoader.GetString("PythonScriptTrustCancel"),
+            };
+
+            // XamlRoot must be set for ContentDialog to function.
+            var mainWindow = (Microsoft.UI.Xaml.Application.Current as AdvancedPaste.App)?.GetMainWindow();
+            if (mainWindow?.Content?.XamlRoot is { } xamlRoot)
+            {
+                dialog.XamlRoot = xamlRoot;
+            }
+
+            var result = await dialog.ShowAsync();
+            return result == ContentDialogResult.Primary;
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError("Failed to show trust dialog", ex);
+            return false;
+        }
+    }
+
+    public void StoreTrust(string scriptPath, string hash)
+    {
+        _userSettings.StoreTrustedScriptHash(scriptPath, hash);
+    }
+
+    public string ComputeHash(string scriptPath)
+    {
+        using var stream = File.OpenRead(scriptPath);
+        var hashBytes = SHA256.HashData(stream);
+        return Convert.ToHexStringLower(hashBytes);
+    }
+
+    public async Task<bool> RequestInstallAsync(string scriptName, IReadOnlyList<PythonRequirement> missingPackages)
+    {
+        try
+        {
+            var resourceLoader = ResourceLoaderInstance.ResourceLoader;
+            var packageList = string.Join("\n", missingPackages.Select(r =>
+                string.Equals(r.ImportName, r.PipPackage, StringComparison.Ordinal)
+                    ? $"  • {r.PipPackage}"
+                    : $"  • {r.PipPackage}  (import: {r.ImportName})"));
+
+            var dialog = new ContentDialog
+            {
+                Title = resourceLoader.GetString("PythonPackageInstallTitle"),
+                Content = string.Format(
+                    System.Globalization.CultureInfo.CurrentCulture,
+                    resourceLoader.GetString("PythonPackageInstallContent"),
+                    scriptName,
+                    packageList),
+                PrimaryButtonText = resourceLoader.GetString("PythonPackageInstallConfirm"),
+                CloseButtonText = resourceLoader.GetString("PythonPackageInstallCancel"),
+            };
+
+            var mainWindow = (Microsoft.UI.Xaml.Application.Current as AdvancedPaste.App)?.GetMainWindow();
+            if (mainWindow?.Content?.XamlRoot is { } xamlRoot)
+            {
+                dialog.XamlRoot = xamlRoot;
+            }
+
+            var result = await dialog.ShowAsync();
+            return result == ContentDialogResult.Primary;
+        }
+        catch (Exception ex)
+        {
+            Logger.LogError("Failed to show package install dialog", ex);
+            return false;
+        }
+    }
+}

src/modules/AdvancedPaste/AdvancedPaste/Strings/en-us/Resources.resw

@@ -372,4 +372,73 @@
     <value>Unable to load Foundry Local model: {0}</value>
     <comment>{0} is the model identifier. Do not translate {0}.</comment>
   </data>
+  <data name="PythonNotFound" xml:space="preserve">
+    <value>Python was not found. Please install Python or configure the path in Settings.</value>
+  </data>
+  <data name="WslNotAvailable" xml:space="preserve">
+    <value>WSL is not installed or not available. Cannot run Linux scripts.</value>
+  </data>
+  <data name="PythonScriptFailed" xml:space="preserve">
+    <value>The Python script failed to execute.</value>
+  </data>
+  <data name="PythonScriptTimeout" xml:space="preserve">
+    <value>Script execution timed out ({0} seconds).</value>
+    <comment>{0} is the configured timeout in seconds. Do not translate {0}.</comment>
+  </data>
+  <data name="PythonScriptNotFound" xml:space="preserve">
+    <value>Script file not found: {0}</value>
+    <comment>{0} is the script file path. Do not translate {0}.</comment>
+  </data>
+  <data name="PythonScriptInvalidJson" xml:space="preserve">
+    <value>The script output is not valid JSON.</value>
+  </data>
+  <data name="PythonScriptTrustTitle" xml:space="preserve">
+    <value>Run Python Script?</value>
+  </data>
+  <data name="PythonScriptTrustContent" xml:space="preserve">
+    <value>This script has not been verified. Running untrusted scripts can be a security risk. Do you want to run the following script?
+
+{0}</value>
+    <comment>{0} is the script file path. Do not translate {0}.</comment>
+  </data>
+  <data name="PythonScriptTrustConfirm" xml:space="preserve">
+    <value>Run</value>
+  </data>
+  <data name="PythonScriptTrustCancel" xml:space="preserve">
+    <value>Cancel</value>
+  </data>
+  <data name="PythonPackageInstallTitle" xml:space="preserve">
+    <value>Install Missing Packages?</value>
+  </data>
+  <data name="PythonPackageInstallContent" xml:space="preserve">
+    <value>The script "{0}" requires the following Python packages that are not installed:
+
+{1}
+
+Install them now?</value>
+    <comment>{0} = script display name, {1} = bullet list of package names. Do not translate package names.</comment>
+  </data>
+  <data name="PythonPackageInstallConfirm" xml:space="preserve">
+    <value>Install</value>
+  </data>
+  <data name="PythonPackageInstallCancel" xml:space="preserve">
+    <value>Skip</value>
+  </data>
+  <data name="PythonPackageInstallFailed" xml:space="preserve">
+    <value>Failed to install package(s) "{0}": {1}</value>
+    <comment>{0} = pip package names, {1} = error detail. Do not translate package names.</comment>
+  </data>
+  <data name="PythonPackageInstallTimeout" xml:space="preserve">
+    <value>Package installation for "{0}" timed out ({1} seconds).</value>
+    <comment>{0} = pip package names, {1} = timeout in seconds. Do not translate {0} or {1}.</comment>
+  </data>
+  <data name="ShowErrorDetailsBtn.Content" xml:space="preserve">
+    <value>Show details</value>
+  </data>
+  <data name="ErrorDetailsDialogTitle" xml:space="preserve">
+    <value>Error Details</value>
+  </data>
+  <data name="ErrorDetailsDialogClose" xml:space="preserve">
+    <value>Close</value>
+  </data>
 </root>

src/modules/AdvancedPaste/AdvancedPaste/ViewModels/OptionsViewModel.cs

@@ -16,6 +16,7 @@ using System.Threading.Tasks;
 using AdvancedPaste.Helpers;
 using AdvancedPaste.Models;
 using AdvancedPaste.Services;
+using AdvancedPaste.Services.PythonScripts;
 using AdvancedPaste.Settings;
 using Common.UI;
 using CommunityToolkit.Mvvm.ComponentModel;
@@ -41,6 +42,7 @@ namespace AdvancedPaste.ViewModels
         private readonly IUserSettings _userSettings;
         private readonly IPasteFormatExecutor _pasteFormatExecutor;
         private readonly IAICredentialsProvider _credentialsProvider;
+        private readonly IPythonScriptService _pythonScriptService;
 
         private CancellationTokenSource _pasteActionCancellationTokenSource;
 
@@ -100,6 +102,8 @@ namespace AdvancedPaste.ViewModels
 
         public ObservableCollection<PasteFormat> CustomActionPasteFormats { get; } = [];
 
+        public ObservableCollection<PasteFormat> PythonScriptPasteFormats { get; } = [];
+
         public bool IsCustomAIServiceEnabled
         {
             get
@@ -258,11 +262,12 @@ namespace AdvancedPaste.ViewModels
 
         public event EventHandler PreviewRequested;
 
-        public OptionsViewModel(IFileSystem fileSystem, IAICredentialsProvider credentialsProvider, IUserSettings userSettings, IPasteFormatExecutor pasteFormatExecutor)
+        public OptionsViewModel(IFileSystem fileSystem, IAICredentialsProvider credentialsProvider, IUserSettings userSettings, IPasteFormatExecutor pasteFormatExecutor, IPythonScriptService pythonScriptService)
         {
             _credentialsProvider = credentialsProvider;
             _userSettings = userSettings;
             _pasteFormatExecutor = pasteFormatExecutor;
+            _pythonScriptService = pythonScriptService;
 
             GeneratedResponses = [];
             GeneratedResponses.CollectionChanged += (s, e) =>
@@ -413,12 +418,51 @@ namespace AdvancedPaste.ViewModels
             }
 
             UpdateFormats(StandardPasteFormats, Enum.GetValues<PasteFormats>()
-                                                    .Where(format => PasteFormat.MetadataDict[format].IsCoreAction || _userSettings.AdditionalActions.Contains(format))
+                                                    .Where(format => format != PasteFormats.PythonScript &&
+                                                                     (PasteFormat.MetadataDict[format].IsCoreAction || _userSettings.AdditionalActions.Contains(format)))
                                                     .Select(CreateStandardPasteFormat));
 
             UpdateFormats(
                 CustomActionPasteFormats,
                 IsCustomAIServiceEnabled ? _userSettings.CustomActions.Select(customAction => CreateCustomAIPasteFormat(customAction.Name, customAction.Prompt, isSavedQuery: true)) : []);
+
+            UpdateFormats(
+                PythonScriptPasteFormats,
+                BuildPythonScriptFormats());
+        }
+
+        private IEnumerable<PasteFormat> BuildPythonScriptFormats()
+        {
+            if (!_userSettings.IsPythonScriptsEnabled)
+            {
+                yield break;
+            }
+
+            var folder = _userSettings.PythonScriptsFolder;
+            if (string.IsNullOrWhiteSpace(folder))
+            {
+                yield break;
+            }
+
+            var discoveredScripts = _pythonScriptService.DiscoverScripts(folder);
+            var scriptActions = _userSettings.PythonScriptActions;
+
+            // Use metadata from discovered scripts, but apply IsShown from saved settings.
+            var hiddenPaths = new System.Collections.Generic.HashSet<string>(
+                scriptActions.Where(a => !a.IsShown).Select(a => a.ScriptPath),
+                StringComparer.OrdinalIgnoreCase);
+
+            foreach (var meta in discoveredScripts)
+            {
+                if (hiddenPaths.Contains(meta.ScriptPath) || !meta.IsEnabled)
+                {
+                    continue;
+                }
+
+                // Filter by intersection: only pass clipboard formats the script supports.
+                var filteredFormats = AvailableClipboardFormats & meta.SupportedFormats;
+                yield return PasteFormat.CreatePythonScriptFormat(meta.Name, meta.ScriptPath, filteredFormats);
+            }
         }
 
         public void Dispose()
@@ -692,7 +736,10 @@ namespace AdvancedPaste.ViewModels
             _pasteActionCancellationTokenSource = new();
             TransformProgress = double.NaN;
             PasteActionError = PasteActionError.None;
-            Query = pasteFormat.Query;
+
+            // For Python scripts the Prompt field holds the file path, not a user-visible query.
+            // Setting Query to the path would show it in the AI prompt box, which is misleading.
+            Query = pasteFormat.Format == PasteFormats.PythonScript ? string.Empty : pasteFormat.Query;
 
             try
             {
@@ -732,7 +779,7 @@ namespace AdvancedPaste.ViewModels
 
         internal async Task ExecutePasteFormatAsync(VirtualKey key)
         {
-            var pasteFormat = StandardPasteFormats.Concat(CustomActionPasteFormats)
+            var pasteFormat = StandardPasteFormats.Concat(CustomActionPasteFormats).Concat(PythonScriptPasteFormats)
                                                   .Where(pasteFormat => pasteFormat.IsEnabled)
                                                   .ElementAtOrDefault(key - VirtualKey.Number1);
 

src/settings-ui/Settings.UI.Library/AdvancedPasteProperties.cs

@@ -107,6 +107,10 @@ namespace Microsoft.PowerToys.Settings.UI.Library
         [CmdConfigureIgnoreAttribute]
         public PasteAIConfiguration PasteAIConfiguration { get; set; }
 
+        [JsonPropertyName("python-scripts")]
+        [CmdConfigureIgnoreAttribute]
+        public AdvancedPastePythonScriptSettings PythonScripts { get; set; } = new();
+
         public override string ToString()
             => JsonSerializer.Serialize(this, SettingsSerializationContext.Default.AdvancedPasteProperties);
     }

src/settings-ui/Settings.UI.Library/AdvancedPastePythonScriptAction.cs

@@ -0,0 +1,248 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.Collections.Generic;
+using System.Linq;
+using System.Text.Json.Serialization;
+using Microsoft.PowerToys.Settings.UI.Library.Helpers;
+
+namespace Microsoft.PowerToys.Settings.UI.Library;
+
+public sealed class AdvancedPastePythonScriptAction : Observable, IAdvancedPasteAction, ICloneable
+{
+    private string _scriptPath = string.Empty;
+    private string _name = string.Empty;
+    private string _description = string.Empty;
+    private bool _isShown = true;
+    private bool _isEnabled = true;
+    private string _platform = "windows";
+    private string _formats = "any";
+    private string _requires = string.Empty;
+    private bool _requiresAutoDetect = true;
+    private HotkeySettings _shortcut = new();
+
+    [JsonPropertyName("scriptPath")]
+    public string ScriptPath
+    {
+        get => _scriptPath;
+        set => Set(ref _scriptPath, value ?? string.Empty);
+    }
+
+    [JsonPropertyName("name")]
+    public string Name
+    {
+        get => _name;
+        set => Set(ref _name, value ?? string.Empty);
+    }
+
+    [JsonPropertyName("description")]
+    public string Description
+    {
+        get => _description;
+        set => Set(ref _description, value ?? string.Empty);
+    }
+
+    [JsonPropertyName("isShown")]
+    public bool IsShown
+    {
+        get => _isShown;
+        set => Set(ref _isShown, value);
+    }
+
+    [JsonPropertyName("isEnabled")]
+    public bool IsEnabled
+    {
+        get => _isEnabled;
+        set => Set(ref _isEnabled, value);
+    }
+
+    [JsonPropertyName("platform")]
+    public string Platform
+    {
+        get => _platform;
+        set => Set(ref _platform, value ?? "windows");
+    }
+
+    [JsonPropertyName("formats")]
+    public string Formats
+    {
+        get => _formats;
+        set => Set(ref _formats, value ?? "any");
+    }
+
+    /// <summary>
+    /// Space-separated requires entries, e.g. "cv2=opencv-python-headless numpy requests".
+    /// Only written to header when RequiresAutoDetect is false (manual mode).
+    /// </summary>
+    [JsonPropertyName("requires")]
+    public string Requires
+    {
+        get => _requires;
+        set => Set(ref _requires, value ?? string.Empty);
+    }
+
+    /// <summary>
+    /// When true, dependencies are auto-detected from import statements.
+    /// When false, the manual <see cref="Requires"/> value is used.
+    /// </summary>
+    [JsonPropertyName("requiresAutoDetect")]
+    public bool RequiresAutoDetect
+    {
+        get => _requiresAutoDetect;
+        set => Set(ref _requiresAutoDetect, value);
+    }
+
+    /// <summary>
+    /// Inverted view of RequiresAutoDetect for UI binding.
+    /// Uses a separate field to avoid circular property change notifications.
+    /// </summary>
+    [JsonIgnore]
+    public bool IsRequiresManual
+    {
+        get => !_requiresAutoDetect;
+        set
+        {
+            var newAuto = !value;
+            if (_requiresAutoDetect != newAuto)
+            {
+                _requiresAutoDetect = newAuto;
+                OnPropertyChanged(nameof(RequiresAutoDetect));
+                OnPropertyChanged(nameof(IsRequiresManual));
+            }
+        }
+    }
+
+    [JsonPropertyName("shortcut")]
+    public HotkeySettings Shortcut
+    {
+        get => _shortcut;
+        set
+        {
+            if (_shortcut != value)
+            {
+                _shortcut = value ?? new();
+                OnPropertyChanged();
+            }
+        }
+    }
+
+    [JsonIgnore]
+    public IEnumerable<IAdvancedPasteAction> SubActions => [];
+
+    // Convenience properties for format checkboxes
+    [JsonIgnore]
+    public bool SupportsText
+    {
+        get => FormatContains("text");
+        set => ToggleFormat("text", value);
+    }
+
+    [JsonIgnore]
+    public bool SupportsHtml
+    {
+        get => FormatContains("html");
+        set => ToggleFormat("html", value);
+    }
+
+    [JsonIgnore]
+    public bool SupportsImage
+    {
+        get => FormatContains("image");
+        set => ToggleFormat("image", value);
+    }
+
+    [JsonIgnore]
+    public bool SupportsAudio
+    {
+        get => FormatContains("audio");
+        set => ToggleFormat("audio", value);
+    }
+
+    [JsonIgnore]
+    public bool SupportsVideo
+    {
+        get => FormatContains("video");
+        set => ToggleFormat("video", value);
+    }
+
+    [JsonIgnore]
+    public bool SupportsFiles
+    {
+        get => FormatContains("files") || FormatContains("file");
+        set => ToggleFormat("files", value);
+    }
+
+    private bool FormatContains(string format)
+    {
+        if (string.Equals(Formats, "any", StringComparison.OrdinalIgnoreCase))
+        {
+            return true;
+        }
+
+        return Formats.Split(',', StringSplitOptions.TrimEntries)
+                       .Any(f => string.Equals(f, format, StringComparison.OrdinalIgnoreCase));
+    }
+
+    private bool _isTogglingFormat;
+
+    private void ToggleFormat(string format, bool include)
+    {
+        if (_isTogglingFormat)
+        {
+            return;
+        }
+
+        _isTogglingFormat = true;
+        try
+        {
+            var currentFormats = string.Equals(Formats, "any", StringComparison.OrdinalIgnoreCase)
+                ? new HashSet<string>(["text", "html", "image", "audio", "video", "files"], StringComparer.OrdinalIgnoreCase)
+                : new HashSet<string>(Formats.Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries), StringComparer.OrdinalIgnoreCase);
+
+            // Normalize file/files
+            currentFormats.Remove("file");
+
+            if (include)
+            {
+                currentFormats.Add(format);
+            }
+            else
+            {
+                currentFormats.Remove(format);
+            }
+
+            var allFormats = new HashSet<string>(["text", "html", "image", "audio", "video", "files"], StringComparer.OrdinalIgnoreCase);
+            Formats = currentFormats.SetEquals(allFormats) ? "any" : string.Join(", ", currentFormats);
+
+            OnPropertyChanged(nameof(SupportsText));
+            OnPropertyChanged(nameof(SupportsHtml));
+            OnPropertyChanged(nameof(SupportsImage));
+            OnPropertyChanged(nameof(SupportsAudio));
+            OnPropertyChanged(nameof(SupportsVideo));
+            OnPropertyChanged(nameof(SupportsFiles));
+        }
+        finally
+        {
+            _isTogglingFormat = false;
+        }
+    }
+
+    public object Clone()
+    {
+        return new AdvancedPastePythonScriptAction
+        {
+            ScriptPath = ScriptPath,
+            Name = Name,
+            Description = Description,
+            IsShown = IsShown,
+            IsEnabled = IsEnabled,
+            Platform = Platform,
+            Formats = Formats,
+            Requires = Requires,
+            RequiresAutoDetect = RequiresAutoDetect,
+            Shortcut = Shortcut != null ? new HotkeySettings(Shortcut.Win, Shortcut.Ctrl, Shortcut.Alt, Shortcut.Shift, Shortcut.Code) : null,
+        };
+    }
+}

src/settings-ui/Settings.UI.Library/AdvancedPastePythonScriptSettings.cs

@@ -0,0 +1,29 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System.Collections.Generic;
+using System.Text.Json.Serialization;
+
+namespace Microsoft.PowerToys.Settings.UI.Library;
+
+public sealed class AdvancedPastePythonScriptSettings
+{
+    [JsonPropertyName("isEnabled")]
+    public bool IsEnabled { get; set; }
+
+    [JsonPropertyName("scriptsFolder")]
+    public string ScriptsFolder { get; set; } = string.Empty;
+
+    [JsonPropertyName("pythonExecutablePath")]
+    public string PythonExecutablePath { get; set; } = string.Empty;
+
+    [JsonPropertyName("timeoutSeconds")]
+    public int TimeoutSeconds { get; set; } = 30;
+
+    [JsonPropertyName("value")]
+    public List<AdvancedPastePythonScriptAction> Value { get; set; } = [];
+
+    [JsonPropertyName("trustedScriptHashes")]
+    public Dictionary<string, string> TrustedScriptHashes { get; set; } = [];
+}

src/settings-ui/Settings.UI.Library/SettingsSerializationContext.cs

@@ -138,6 +138,10 @@ namespace Microsoft.PowerToys.Settings.UI.Library
     [JsonSerializable(typeof(AdvancedPasteAdditionalAction))]
     [JsonSerializable(typeof(AdvancedPastePasteAsFileAction))]
     [JsonSerializable(typeof(AdvancedPasteTranscodeAction))]
+    [JsonSerializable(typeof(AdvancedPastePythonScriptAction))]
+    [JsonSerializable(typeof(AdvancedPastePythonScriptSettings))]
+    [JsonSerializable(typeof(System.Collections.Generic.List<AdvancedPastePythonScriptAction>))]
+    [JsonSerializable(typeof(System.Collections.Generic.Dictionary<string, string>))]
     [JsonSerializable(typeof(ImageResizerSizes))]
     [JsonSerializable(typeof(ImageResizerCustomSizeProperty))]
     [JsonSerializable(typeof(KeyboardKeysProperty))]

src/settings-ui/Settings.UI.UnitTests/ViewModelTests/AdvancedPaste.cs

@@ -0,0 +1,71 @@
+// Copyright (c) Microsoft Corporation
+// The Microsoft Corporation licenses this file to you under the MIT license.
+// See the LICENSE file in the project root for more information.
+
+using System;
+using System.IO;
+using System.Linq;
+using System.Reflection;
+
+using Microsoft.PowerToys.Settings.UI.Library;
+using Microsoft.PowerToys.Settings.UI.ViewModels;
+using Microsoft.VisualStudio.TestTools.UnitTesting;
+
+namespace ViewModelTests
+{
+    [TestClass]
+    public class AdvancedPaste
+    {
+        [TestMethod]
+        public void WriteScriptHeader_OverwritesExistingBlankDescriptionTag()
+        {
+            var scriptPath = Path.Combine(Path.GetTempPath(), $"AdvancedPaste-{Guid.NewGuid():N}.py");
+
+            try
+            {
+                File.WriteAllLines(
+                    scriptPath,
+                    [
+                        "# @advancedpaste:name   reverse text",
+                        "# @advancedpaste:formats   text",
+                        "# @advancedpaste:platform   windows",
+                        "# @advancedpaste:desc   ",
+                        "# @advancedpaste:enabled   true",
+                        "print('hello')",
+                    ]);
+
+                var action = new AdvancedPastePythonScriptAction
+                {
+                    ScriptPath = scriptPath,
+                    Name = "reverse text",
+                    Description = "Updated description",
+                    Platform = "windows",
+                    Formats = "text",
+                    IsEnabled = true,
+                    RequiresAutoDetect = true,
+                };
+
+                var writeScriptHeader = typeof(AdvancedPasteViewModel)
+                    .GetMethod("WriteScriptHeader", BindingFlags.NonPublic | BindingFlags.Static);
+
+                Assert.IsNotNull(writeScriptHeader);
+
+                writeScriptHeader.Invoke(null, [action]);
+
+                var descLines = File.ReadAllLines(scriptPath)
+                    .Where(line => line.Contains("@advancedpaste:desc", StringComparison.OrdinalIgnoreCase))
+                    .ToArray();
+
+                Assert.AreEqual(1, descLines.Length);
+                Assert.AreEqual("# @advancedpaste:desc   Updated description", descLines[0]);
+            }
+            finally
+            {
+                if (File.Exists(scriptPath))
+                {
+                    File.Delete(scriptPath);
+                }
+            }
+        }
+    }
+}

src/settings-ui/Settings.UI/SettingsXAML/Views/AdvancedPastePage.xaml

@@ -390,6 +390,106 @@
                             IsTabStop="{x:Bind ViewModel.IsConflictingCopyShortcut, Mode=OneWay}"
                             Severity="Warning" />
                     </controls:SettingsGroup>
+
+                    <controls:SettingsGroup x:Uid="AdvancedPaste_PythonScripts_GroupSettings" IsEnabled="{x:Bind ViewModel.IsEnabled, Mode=OneWay}">
+                        <tkcontrols:SettingsCard x:Uid="AdvancedPaste_PythonScripts_EnableCard">
+                            <tkcontrols:SettingsCard.HeaderIcon>
+                                <FontIcon Glyph="&#xE943;" />
+                            </tkcontrols:SettingsCard.HeaderIcon>
+                            <ToggleSwitch IsOn="{x:Bind ViewModel.IsPythonScriptsEnabled, Mode=TwoWay}" />
+                        </tkcontrols:SettingsCard>
+                        <tkcontrols:SettingsCard x:Uid="AdvancedPaste_ScriptsFolder_SettingsCard"
+                            IsEnabled="{x:Bind ViewModel.IsPythonScriptsEnabled, Mode=OneWay}">
+                            <tkcontrols:SettingsCard.HeaderIcon>
+                                <FontIcon Glyph="&#xE8B7;" />
+                            </tkcontrols:SettingsCard.HeaderIcon>
+                            <StackPanel Orientation="Horizontal" Spacing="8">
+                                <TextBox
+                                    x:Name="ScriptsFolderTextBox"
+                                    x:Uid="AdvancedPaste_ScriptsFolder_TextBox"
+                                    MinWidth="300"
+                                    HorizontalAlignment="Stretch"
+                                    Text="{x:Bind ViewModel.ScriptsFolder, Mode=TwoWay, UpdateSourceTrigger=LostFocus}" />
+                                <Button
+                                    VerticalAlignment="Bottom"
+                                    Click="BrowseScriptsFolder_Click"
+                                    Content="{ui:FontIcon Glyph=&#xE8DA;,
+                                                          FontSize=16}"
+                                    Style="{StaticResource SubtleButtonStyle}" />
+                                <Button
+                                    VerticalAlignment="Bottom"
+                                    Click="OpenScriptsFolder_Click"
+                                    Content="{ui:FontIcon Glyph=&#xE838;,
+                                                          FontSize=16}"
+                                    Style="{StaticResource SubtleButtonStyle}"
+                                    ToolTipService.ToolTip="Open folder" />
+                            </StackPanel>
+                        </tkcontrols:SettingsCard>
+                        <tkcontrols:SettingsCard x:Uid="AdvancedPaste_PythonExecutablePath_SettingsCard"
+                            IsEnabled="{x:Bind ViewModel.IsPythonScriptsEnabled, Mode=OneWay}">
+                            <tkcontrols:SettingsCard.HeaderIcon>
+                                <FontIcon Glyph="&#xE943;" />
+                            </tkcontrols:SettingsCard.HeaderIcon>
+                            <StackPanel Orientation="Horizontal" Spacing="8">
+                                <TextBox
+                                    x:Name="PythonExecutablePathTextBox"
+                                    x:Uid="AdvancedPaste_PythonExecutablePath_TextBox"
+                                    MinWidth="300"
+                                    HorizontalAlignment="Stretch"
+                                    Text="{x:Bind ViewModel.PythonExecutablePath, Mode=TwoWay, UpdateSourceTrigger=LostFocus}" />
+                                <Button
+                                    VerticalAlignment="Bottom"
+                                    Click="BrowsePythonExecutablePath_Click"
+                                    Content="{ui:FontIcon Glyph=&#xE8DA;,
+                                                          FontSize=16}"
+                                    Style="{StaticResource SubtleButtonStyle}" />
+                            </StackPanel>
+                        </tkcontrols:SettingsCard>
+
+                        <!-- Discovered Python Scripts -->
+                        <tkcontrols:SettingsExpander
+                            x:Name="PythonScriptListExpander"
+                            x:Uid="AdvancedPaste_PythonScriptList"
+                            HeaderIcon="{ui:FontIcon Glyph=&#xE756;}"
+                            IsEnabled="{x:Bind ViewModel.IsPythonScriptsEnabled, Mode=OneWay}"
+                            IsExpanded="True"
+                            ItemsSource="{x:Bind ViewModel.PythonScriptActions, Mode=OneWay}">
+                            <StackPanel Orientation="Horizontal" Spacing="8">
+                                <Button
+                                    x:Name="RefreshScriptsButton"
+                                    Click="RefreshPythonScripts_Click"
+                                    Style="{ThemeResource AccentButtonStyle}"
+                                    Content="Load scripts" />
+                            </StackPanel>
+                            <tkcontrols:SettingsExpander.ItemTemplate>
+                                <DataTemplate x:DataType="models:AdvancedPastePythonScriptAction">
+                                    <tkcontrols:SettingsCard
+                                        Margin="0,0,0,2"
+                                        Header="{x:Bind Name, Mode=OneWay}"
+                                        Description="{x:Bind ScriptPath, Mode=OneWay}"
+                                        IsActionIconVisible="False">
+                                        <StackPanel Orientation="Horizontal" Spacing="8">
+                                            <ToggleSwitch
+                                                IsOn="{x:Bind IsEnabled, Mode=TwoWay, UpdateSourceTrigger=PropertyChanged}"
+                                                Toggled="ScriptEnabledToggle_Toggled"
+                                                OffContent=""
+                                                OnContent="" />
+                                            <Button
+                                                Content="&#xE70F;"
+                                                FontFamily="{ThemeResource SymbolThemeFontFamily}"
+                                                Click="EditPythonScript_Click"
+                                                Style="{StaticResource SubtleButtonStyle}"
+                                                Tag="{x:Bind}">
+                                                <ToolTipService.ToolTip>
+                                                    <TextBlock Text="Edit script settings" />
+                                                </ToolTipService.ToolTip>
+                                            </Button>
+                                        </StackPanel>
+                                    </tkcontrols:SettingsCard>
+                                </DataTemplate>
+                            </tkcontrols:SettingsExpander.ItemTemplate>
+                        </tkcontrols:SettingsExpander>
+                    </controls:SettingsGroup>
                 </StackPanel>
             </controls:SettingsPageControl.ModuleContent>
             <controls:SettingsPageControl.PrimaryLinks>
@@ -428,7 +528,74 @@
             </StackPanel>
         </ContentDialog>
 
-        <!--  Paste AI provider dialog  -->
+        <!--  Python Script Edit Dialog  -->
+        <ContentDialog
+            x:Name="PythonScriptEditDialog"
+            Title="Edit script settings"
+            CloseButtonText="Cancel"
+            PrimaryButtonText="Apply changes"
+            PrimaryButtonStyle="{ThemeResource AccentButtonStyle}">
+            <ContentDialog.Resources>
+                <x:Double x:Key="ContentDialogMaxWidth">600</x:Double>
+            </ContentDialog.Resources>
+            <StackPanel Spacing="14" MinWidth="400">
+                <TextBlock
+                    x:Name="ScriptEditFilePath"
+                    Style="{StaticResource CaptionTextBlockStyle}"
+                    Foreground="{ThemeResource TextFillColorSecondaryBrush}"
+                    IsTextSelectionEnabled="True" />
+                <TextBox
+                    x:Name="ScriptEditName"
+                    Header="Name"
+                    Width="380"
+                    HorizontalAlignment="Left" />
+                <TextBox
+                    x:Name="ScriptEditDescription"
+                    Header="Description"
+                    Width="380"
+                    HorizontalAlignment="Left" />
+                <ComboBox
+                    x:Name="ScriptEditPlatform"
+                    Header="Platform"
+                    MinWidth="160">
+                    <x:String>windows</x:String>
+                    <x:String>linux</x:String>
+                    <x:String>any</x:String>
+                </ComboBox>
+                <TextBlock
+                    Text="Supported formats"
+                    Style="{StaticResource BodyTextBlockStyle}"
+                    Margin="0,4,0,0" />
+                <Grid ColumnSpacing="12" RowSpacing="4">
+                    <Grid.ColumnDefinitions>
+                        <ColumnDefinition Width="Auto" />
+                        <ColumnDefinition Width="Auto" />
+                        <ColumnDefinition Width="Auto" />
+                    </Grid.ColumnDefinitions>
+                    <Grid.RowDefinitions>
+                        <RowDefinition Height="Auto" />
+                        <RowDefinition Height="Auto" />
+                    </Grid.RowDefinitions>
+                    <CheckBox x:Name="ScriptEditText" Content="Text" Grid.Row="0" Grid.Column="0" />
+                    <CheckBox x:Name="ScriptEditHtml" Content="HTML" Grid.Row="0" Grid.Column="1" />
+                    <CheckBox x:Name="ScriptEditImage" Content="Image" Grid.Row="0" Grid.Column="2" />
+                    <CheckBox x:Name="ScriptEditAudio" Content="Audio" Grid.Row="1" Grid.Column="0" />
+                    <CheckBox x:Name="ScriptEditVideo" Content="Video" Grid.Row="1" Grid.Column="1" />
+                    <CheckBox x:Name="ScriptEditFiles" Content="Files" Grid.Row="1" Grid.Column="2" />
+                </Grid>
+                <ToggleSwitch
+                    x:Name="ScriptEditAutoDetectDeps"
+                    Header="Dependencies"
+                    OnContent="Auto-detect from imports"
+                    OffContent="Manual" />
+                <TextBox
+                    x:Name="ScriptEditRequires"
+                    Header="Required packages (space-separated)"
+                    Width="380"
+                    HorizontalAlignment="Left"
+                    PlaceholderText="e.g. numpy requests cv2=opencv-python-headless" />
+            </StackPanel>
+        </ContentDialog>
         <ContentDialog
             x:Name="PasteAIProviderConfigurationDialog"
             x:Uid="AdvancedPaste_EndpointDialog"

src/settings-ui/Settings.UI/SettingsXAML/Views/AdvancedPastePage.xaml.cs

@@ -21,6 +21,7 @@ using Microsoft.UI.Xaml;
 using Microsoft.UI.Xaml.Controls;
 using Microsoft.UI.Xaml.Media;
 using Microsoft.UI.Xaml.Media.Imaging;
+using Windows.ApplicationModel.DataTransfer;
 
 namespace Microsoft.PowerToys.Settings.UI.Views
 {
@@ -264,6 +265,247 @@ namespace Microsoft.PowerToys.Settings.UI.Views
             }
         }
 
+        private void BrowsePythonExecutablePath_Click(object sender, RoutedEventArgs e)
+        {
+            string selectedFile = PickFileDialog(
+                "Python Executable\0python.exe;python3.exe\0All Executables\0*.exe\0",
+                "Select Python Executable");
+
+            if (!string.IsNullOrEmpty(selectedFile))
+            {
+                PythonExecutablePathTextBox.Text = selectedFile;
+                if (ViewModel is not null)
+                {
+                    ViewModel.PythonExecutablePath = selectedFile;
+                }
+            }
+        }
+
+        private void BrowseScriptsFolder_Click(object sender, RoutedEventArgs e)
+        {
+            IntPtr windowHandle = WinRT.Interop.WindowNative.GetWindowHandle(App.GetSettingsWindow());
+            string selectedFolder = ShellGetFolder.GetFolderDialogWithFlags(
+                windowHandle,
+                ShellGetFolder.FolderDialogFlags._BIF_NEWDIALOGSTYLE);
+
+            if (!string.IsNullOrEmpty(selectedFolder))
+            {
+                ScriptsFolderTextBox.Text = selectedFolder;
+                if (ViewModel is not null)
+                {
+                    ViewModel.ScriptsFolder = selectedFolder;
+                }
+            }
+        }
+
+        private void OpenScriptsFolder_Click(object sender, RoutedEventArgs e)
+        {
+            var folder = ViewModel?.ScriptsFolder;
+            if (!string.IsNullOrEmpty(folder) && System.IO.Directory.Exists(folder))
+            {
+                System.Diagnostics.Process.Start(new System.Diagnostics.ProcessStartInfo
+                {
+                    FileName = folder,
+                    UseShellExecute = true,
+                });
+            }
+        }
+
+        private void RefreshPythonScripts_Click(object sender, RoutedEventArgs e)
+        {
+            ViewModel?.RefreshPythonScripts();
+            RefreshScriptsButton.Content = "Refresh scripts";
+        }
+
+        private async void EditPythonScript_Click(object sender, RoutedEventArgs e)
+        {
+            if (sender is not FrameworkElement { Tag: AdvancedPastePythonScriptAction action })
+            {
+                return;
+            }
+
+            // Snapshot initial values to detect changes
+            var initialName = action.Name;
+            var initialDesc = action.Description;
+            var initialPlatform = action.Platform;
+            var initialText = action.SupportsText;
+            var initialHtml = action.SupportsHtml;
+            var initialImage = action.SupportsImage;
+            var initialAudio = action.SupportsAudio;
+            var initialVideo = action.SupportsVideo;
+            var initialFiles = action.SupportsFiles;
+            var initialAutoDetect = action.RequiresAutoDetect;
+            var initialRequires = action.Requires;
+
+            // Populate dialog fields from the action
+            ScriptEditFilePath.Text = action.ScriptPath;
+            ScriptEditName.Text = action.Name;
+            ScriptEditDescription.Text = action.Description;
+            ScriptEditPlatform.SelectedItem = action.Platform;
+            ScriptEditText.IsChecked = action.SupportsText;
+            ScriptEditHtml.IsChecked = action.SupportsHtml;
+            ScriptEditImage.IsChecked = action.SupportsImage;
+            ScriptEditAudio.IsChecked = action.SupportsAudio;
+            ScriptEditVideo.IsChecked = action.SupportsVideo;
+            ScriptEditFiles.IsChecked = action.SupportsFiles;
+            ScriptEditAutoDetectDeps.IsOn = action.RequiresAutoDetect;
+            ScriptEditRequires.Text = action.Requires;
+            ScriptEditRequires.IsEnabled = !action.RequiresAutoDetect;
+
+            void OnDepsToggled(object s, RoutedEventArgs args) =>
+                ScriptEditRequires.IsEnabled = !ScriptEditAutoDetectDeps.IsOn;
+
+            // Change detection: disable Apply button when nothing has changed
+            PythonScriptEditDialog.IsPrimaryButtonEnabled = false;
+
+            void CheckForChanges(object s, object args)
+            {
+                bool hasChanges =
+                    ScriptEditName.Text != initialName ||
+                    ScriptEditDescription.Text != initialDesc ||
+                    (ScriptEditPlatform.SelectedItem as string ?? "windows") != initialPlatform ||
+                    (ScriptEditText.IsChecked == true) != initialText ||
+                    (ScriptEditHtml.IsChecked == true) != initialHtml ||
+                    (ScriptEditImage.IsChecked == true) != initialImage ||
+                    (ScriptEditAudio.IsChecked == true) != initialAudio ||
+                    (ScriptEditVideo.IsChecked == true) != initialVideo ||
+                    (ScriptEditFiles.IsChecked == true) != initialFiles ||
+                    ScriptEditAutoDetectDeps.IsOn != initialAutoDetect ||
+                    ScriptEditRequires.Text != initialRequires;
+                PythonScriptEditDialog.IsPrimaryButtonEnabled = hasChanges;
+            }
+
+            void OnTextChanged(object s, TextChangedEventArgs args) => CheckForChanges(s, args);
+            void OnChecked(object s, RoutedEventArgs args) => CheckForChanges(s, args);
+            void OnToggled(object s, RoutedEventArgs args)
+            {
+                OnDepsToggled(s, args);
+                CheckForChanges(s, args);
+            }
+
+            void OnSelectionChanged(object s, SelectionChangedEventArgs args) => CheckForChanges(s, args);
+
+            ScriptEditName.TextChanged += OnTextChanged;
+            ScriptEditDescription.TextChanged += OnTextChanged;
+            ScriptEditRequires.TextChanged += OnTextChanged;
+            ScriptEditPlatform.SelectionChanged += OnSelectionChanged;
+            ScriptEditText.Checked += OnChecked;
+            ScriptEditText.Unchecked += OnChecked;
+            ScriptEditHtml.Checked += OnChecked;
+            ScriptEditHtml.Unchecked += OnChecked;
+            ScriptEditImage.Checked += OnChecked;
+            ScriptEditImage.Unchecked += OnChecked;
+            ScriptEditAudio.Checked += OnChecked;
+            ScriptEditAudio.Unchecked += OnChecked;
+            ScriptEditVideo.Checked += OnChecked;
+            ScriptEditVideo.Unchecked += OnChecked;
+            ScriptEditFiles.Checked += OnChecked;
+            ScriptEditFiles.Unchecked += OnChecked;
+            ScriptEditAutoDetectDeps.Toggled += OnToggled;
+
+            try
+            {
+                PythonScriptEditDialog.XamlRoot = Content.XamlRoot;
+                var result = await PythonScriptEditDialog.ShowAsync();
+
+                if (result == ContentDialogResult.Primary)
+                {
+                    // Write dialog values back to the action
+                    action.Name = ScriptEditName.Text;
+                    action.Description = ScriptEditDescription.Text;
+                    action.Platform = ScriptEditPlatform.SelectedItem as string ?? "windows";
+                    action.SupportsText = ScriptEditText.IsChecked == true;
+                    action.SupportsHtml = ScriptEditHtml.IsChecked == true;
+                    action.SupportsImage = ScriptEditImage.IsChecked == true;
+                    action.SupportsAudio = ScriptEditAudio.IsChecked == true;
+                    action.SupportsVideo = ScriptEditVideo.IsChecked == true;
+                    action.SupportsFiles = ScriptEditFiles.IsChecked == true;
+                    action.RequiresAutoDetect = ScriptEditAutoDetectDeps.IsOn;
+                    action.Requires = ScriptEditRequires.Text;
+
+                    await ApplySingleActionAsync(action);
+                }
+            }
+            finally
+            {
+                ScriptEditName.TextChanged -= OnTextChanged;
+                ScriptEditDescription.TextChanged -= OnTextChanged;
+                ScriptEditRequires.TextChanged -= OnTextChanged;
+                ScriptEditPlatform.SelectionChanged -= OnSelectionChanged;
+                ScriptEditText.Checked -= OnChecked;
+                ScriptEditText.Unchecked -= OnChecked;
+                ScriptEditHtml.Checked -= OnChecked;
+                ScriptEditHtml.Unchecked -= OnChecked;
+                ScriptEditImage.Checked -= OnChecked;
+                ScriptEditImage.Unchecked -= OnChecked;
+                ScriptEditAudio.Checked -= OnChecked;
+                ScriptEditAudio.Unchecked -= OnChecked;
+                ScriptEditVideo.Checked -= OnChecked;
+                ScriptEditVideo.Unchecked -= OnChecked;
+                ScriptEditFiles.Checked -= OnChecked;
+                ScriptEditFiles.Unchecked -= OnChecked;
+                ScriptEditAutoDetectDeps.Toggled -= OnToggled;
+            }
+        }
+
+        private async void ScriptEnabledToggle_Toggled(object sender, RoutedEventArgs e)
+        {
+            if (sender is ToggleSwitch toggle && toggle.DataContext is AdvancedPastePythonScriptAction action)
+            {
+                action.IsEnabled = toggle.IsOn;
+                await ApplySingleActionAsync(action);
+            }
+        }
+
+        private async Task ApplySingleActionAsync(AdvancedPastePythonScriptAction action)
+        {
+            try
+            {
+                ViewModel?.ApplySingleScriptChange(action);
+            }
+            catch (System.IO.IOException)
+            {
+                var headerText = ViewModels.AdvancedPasteViewModel.GenerateHeaderText(action);
+                var errorDialog = new ContentDialog
+                {
+                    XamlRoot = Content.XamlRoot,
+                    Title = "Unable to write to file",
+                    PrimaryButtonText = "Copy header",
+                    CloseButtonText = "OK",
+                    PrimaryButtonStyle = (Style)Application.Current.Resources["AccentButtonStyle"],
+                    Content = new StackPanel
+                    {
+                        Spacing = 12,
+                        Children =
+                        {
+                            new TextBlock
+                            {
+                                Text = $"The file is locked by another process and cannot be updated:\n{action.ScriptPath}\n\nCopy the header below and paste it at the top of the file manually:",
+                                TextWrapping = Microsoft.UI.Xaml.TextWrapping.Wrap,
+                            },
+                            new TextBox
+                            {
+                                Text = headerText,
+                                IsReadOnly = true,
+                                AcceptsReturn = true,
+                                TextWrapping = Microsoft.UI.Xaml.TextWrapping.Wrap,
+                                FontFamily = new FontFamily("Consolas"),
+                                MaxHeight = 200,
+                            },
+                        },
+                    },
+                };
+
+                var dialogResult = await errorDialog.ShowAsync();
+                if (dialogResult == ContentDialogResult.Primary)
+                {
+                    var dataPackage = new DataPackage();
+                    dataPackage.SetText(headerText);
+                    Clipboard.SetContent(dataPackage);
+                }
+            }
+        }
+
         private static string PickFileDialog(string filter, string title, string initialDir = null, int initialFilter = 0)
         {
             // Use Win32 OpenFileName dialog as FileOpenPicker doesn't work with elevated permissions

src/settings-ui/Settings.UI/Strings/en-us/Resources.resw

@@ -598,6 +598,45 @@ opera.exe</value>
   <data name="AdvancedPaste_Additional_Actions_GroupSettings.Header" xml:space="preserve">
     <value>Custom actions</value>
   </data>
+  <data name="AdvancedPaste_PythonScripts_GroupSettings.Header" xml:space="preserve">
+    <value>Python scripts</value>
+  </data>
+  <data name="AdvancedPaste_PythonScripts_EnableCard.Header" xml:space="preserve">
+    <value>Enable Python scripts</value>
+  </data>
+  <data name="AdvancedPaste_PythonScripts_EnableCard.Description" xml:space="preserve">
+    <value>Run custom Python scripts from the Advanced Paste menu</value>
+  </data>
+  <data name="AdvancedPaste_ScriptsFolder_SettingsCard.Header" xml:space="preserve">
+    <value>Scripts folder</value>
+  </data>
+  <data name="AdvancedPaste_ScriptsFolder_SettingsCard.Description" xml:space="preserve">
+    <value>Folder to scan for Python scripts (.py files). Leave blank to use the default location.</value>
+  </data>
+  <data name="AdvancedPaste_ScriptsFolder_TextBox.PlaceholderText" xml:space="preserve">
+    <value>Default (%LOCALAPPDATA%\Microsoft\PowerToys\AdvancedPaste\Scripts)</value>
+  </data>
+  <data name="AdvancedPaste_PythonExecutablePath_SettingsCard.Header" xml:space="preserve">
+    <value>Python interpreter</value>
+  </data>
+  <data name="AdvancedPaste_PythonExecutablePath_SettingsCard.Description" xml:space="preserve">
+    <value>Path to the Python executable used to run scripts. Leave blank to detect automatically (supports Anaconda, Miniconda, system Python).</value>
+  </data>
+  <data name="AdvancedPaste_PythonExecutablePath_TextBox.PlaceholderText" xml:space="preserve">
+    <value>Auto-detect (e.g. C:\Users\&lt;user&gt;\anaconda3\python.exe)</value>
+  </data>
+  <data name="AdvancedPaste_PythonScriptList.Header" xml:space="preserve">
+    <value>Discovered scripts</value>
+  </data>
+  <data name="AdvancedPaste_PythonScriptList.Description" xml:space="preserve">
+    <value>Python scripts found in the scripts folder. Changes to settings are written back to the script file headers.</value>
+  </data>
+  <data name="AdvancedPaste_PythonScript_RefreshScripts.Content" xml:space="preserve">
+    <value>Refresh scripts</value>
+  </data>
+  <data name="AdvancedPaste_PythonScript_ApplyChanges.Content" xml:space="preserve">
+    <value>Apply changes</value>
+  </data>
   <data name="AdvancedPaste_FoundryLocal_LegalDescription" xml:space="preserve">
     <value>You're running local models directly on your device. Their behavior may vary or be unpredictable.</value>
   </data>

src/settings-ui/Settings.UI/ViewModels/AdvancedPasteViewModel.cs

@@ -293,6 +293,386 @@ namespace Microsoft.PowerToys.Settings.UI.ViewModels
 
         public AdvancedPasteAdditionalActions AdditionalActions => _additionalActions;
 
+        public bool IsPythonScriptsEnabled
+        {
+            get
+            {
+                var scripts = _advancedPasteSettings.Properties.PythonScripts;
+                return scripts?.IsEnabled ?? false;
+            }
+
+            set
+            {
+                var scripts = _advancedPasteSettings.Properties.PythonScripts ??= new AdvancedPastePythonScriptSettings();
+                if (scripts.IsEnabled != value)
+                {
+                    scripts.IsEnabled = value;
+                    OnPropertyChanged(nameof(IsPythonScriptsEnabled));
+                    SaveAndNotifySettings();
+                }
+            }
+        }
+
+        public bool ScriptsDiscovered => _scriptsDiscovered;
+
+        public string PythonExecutablePath
+        {
+            get => _advancedPasteSettings.Properties.PythonScripts?.PythonExecutablePath ?? string.Empty;
+            set
+            {
+                var scripts = _advancedPasteSettings.Properties.PythonScripts ??= new AdvancedPastePythonScriptSettings();
+                if (!string.Equals(scripts.PythonExecutablePath, value, StringComparison.OrdinalIgnoreCase))
+                {
+                    scripts.PythonExecutablePath = value ?? string.Empty;
+                    OnPropertyChanged(nameof(PythonExecutablePath));
+                    SaveAndNotifySettings();
+                }
+            }
+        }
+
+        public string ScriptsFolder
+        {
+            get => _advancedPasteSettings.Properties.PythonScripts?.ScriptsFolder ?? string.Empty;
+            set
+            {
+                var scripts = _advancedPasteSettings.Properties.PythonScripts ??= new AdvancedPastePythonScriptSettings();
+                if (!string.Equals(scripts.ScriptsFolder, value, StringComparison.OrdinalIgnoreCase))
+                {
+                    scripts.ScriptsFolder = value ?? string.Empty;
+                    OnPropertyChanged(nameof(ScriptsFolder));
+                    SaveAndNotifySettings();
+
+                    if (_scriptsDiscovered)
+                    {
+                        RefreshPythonScripts();
+                    }
+                }
+            }
+        }
+
+        private ObservableCollection<AdvancedPastePythonScriptAction> _pythonScriptActions = [];
+        private bool _scriptsDiscovered;
+
+        public ObservableCollection<AdvancedPastePythonScriptAction> PythonScriptActions
+        {
+            get => _pythonScriptActions;
+            set
+            {
+                _pythonScriptActions = value;
+                OnPropertyChanged(nameof(PythonScriptActions));
+            }
+        }
+
+        /// <summary>
+        /// Scans the scripts folder for .py files and populates PythonScriptActions
+        /// with metadata from their headers. Existing settings (hotkeys) are preserved.
+        /// </summary>
+        public void RefreshPythonScripts()
+        {
+            _scriptsDiscovered = true;
+            OnPropertyChanged(nameof(ScriptsDiscovered));
+
+            var folder = ScriptsFolder;
+            if (string.IsNullOrWhiteSpace(folder) || !System.IO.Directory.Exists(folder))
+            {
+                PythonScriptActions = [];
+                return;
+            }
+
+            var scripts = new ObservableCollection<AdvancedPastePythonScriptAction>();
+            var savedActions = _advancedPasteSettings.Properties.PythonScripts?.Value ?? [];
+
+            foreach (var file in System.IO.Directory.EnumerateFiles(folder, "*.py", System.IO.SearchOption.TopDirectoryOnly))
+            {
+                try
+                {
+                    var action = CreateActionFromScript(file, savedActions);
+                    scripts.Add(action);
+                }
+                catch
+                {
+                    // Skip scripts that can't be read
+                }
+            }
+
+            PythonScriptActions = scripts;
+        }
+
+        private static AdvancedPastePythonScriptAction CreateActionFromScript(
+            string filePath,
+            List<AdvancedPastePythonScriptAction> savedActions)
+        {
+            // Read header metadata from the .py file
+            var name = System.IO.Path.GetFileNameWithoutExtension(filePath);
+            var description = string.Empty;
+            var platform = "windows";
+            var formats = "any";
+            var enabled = true;
+            var requires = string.Empty;
+            var hasExplicitRequires = false;
+
+            using var reader = new System.IO.StreamReader(filePath, System.Text.Encoding.UTF8);
+            int lineCount = 0;
+            while (lineCount < 50)
+            {
+                var line = reader.ReadLine();
+                if (line is null)
+                {
+                    break;
+                }
+
+                lineCount++;
+                var trimmed = line.Trim();
+                if (!trimmed.StartsWith('#'))
+                {
+                    continue;
+                }
+
+                if (TryParseTag(trimmed, "@advancedpaste:name", out var val))
+                {
+                    name = val;
+                }
+                else if (TryParseTag(trimmed, "@advancedpaste:desc", out val))
+                {
+                    description = val;
+                }
+                else if (TryParseTag(trimmed, "@advancedpaste:platform", out val))
+                {
+                    platform = val.ToLowerInvariant();
+                }
+                else if (TryParseTag(trimmed, "@advancedpaste:formats", out val))
+                {
+                    formats = val;
+                }
+                else if (TryParseTag(trimmed, "@advancedpaste:enabled", out val))
+                {
+                    enabled = !string.Equals(val, "false", StringComparison.OrdinalIgnoreCase)
+                           && !string.Equals(val, "0", StringComparison.OrdinalIgnoreCase)
+                           && !string.Equals(val, "no", StringComparison.OrdinalIgnoreCase);
+                }
+                else if (TryParseTag(trimmed, "@advancedpaste:requires", out val))
+                {
+                    // Accumulate multiple requires tags
+                    requires = string.IsNullOrEmpty(requires) ? val : $"{requires} {val}";
+                    hasExplicitRequires = true;
+                }
+            }
+
+            // Preserve existing saved settings (hotkeys, IsShown)
+            var saved = savedActions?.FirstOrDefault(a =>
+                string.Equals(a.ScriptPath, filePath, StringComparison.OrdinalIgnoreCase));
+
+            return new AdvancedPastePythonScriptAction
+            {
+                ScriptPath = filePath,
+                Name = name,
+                Description = description,
+                Platform = platform,
+                Formats = formats,
+                IsEnabled = enabled,
+                Requires = requires,
+                RequiresAutoDetect = !hasExplicitRequires,
+                IsShown = saved?.IsShown ?? true,
+                Shortcut = saved?.Shortcut ?? new HotkeySettings(),
+            };
+        }
+
+        private static bool TryParseTag(string line, string tag, out string value)
+        {
+            var idx = line.IndexOf(tag, StringComparison.OrdinalIgnoreCase);
+            if (idx < 0)
+            {
+                value = null;
+                return false;
+            }
+
+            value = line[(idx + tag.Length)..].Trim();
+            return value.Length > 0;
+        }
+
+        private static bool ContainsTag(string line, string tag)
+        {
+            return line.IndexOf(tag, StringComparison.OrdinalIgnoreCase) >= 0;
+        }
+
+        /// <summary>
+        /// Writes changed metadata back to each script's header and saves settings.
+        /// </summary>
+        public void ApplyPythonScriptChanges()
+        {
+            foreach (var action in PythonScriptActions)
+            {
+                try
+                {
+                    WriteScriptHeader(action);
+                }
+                catch
+                {
+                    // Skip files that can't be written
+                }
+            }
+
+            // Save the actions to settings
+            var pythonSettings = _advancedPasteSettings.Properties.PythonScripts ??= new AdvancedPastePythonScriptSettings();
+            pythonSettings.Value = [.. PythonScriptActions.Select(a => (AdvancedPastePythonScriptAction)a.Clone())];
+            SaveAndNotifySettings();
+
+            RefreshPythonScripts();
+        }
+
+        /// <summary>
+        /// Applies changes for a single script action. Writes the header to file and saves settings.
+        /// Throws IOException if the file is locked.
+        /// </summary>
+        public void ApplySingleScriptChange(AdvancedPastePythonScriptAction action)
+        {
+            WriteScriptHeader(action);
+
+            var pythonSettings = _advancedPasteSettings.Properties.PythonScripts ??= new AdvancedPastePythonScriptSettings();
+            pythonSettings.Value = [.. PythonScriptActions.Select(a => (AdvancedPastePythonScriptAction)a.Clone())];
+            SaveAndNotifySettings();
+        }
+
+        /// <summary>
+        /// Generates the full header text for a script action, for manual copy/paste fallback.
+        /// </summary>
+        public static string GenerateHeaderText(AdvancedPastePythonScriptAction action)
+        {
+            var sb = new System.Text.StringBuilder();
+            sb.AppendLine(string.Concat("# @advancedpaste:name   ", action.Name));
+            sb.AppendLine(string.Concat("# @advancedpaste:desc   ", action.Description));
+            sb.AppendLine(string.Concat("# @advancedpaste:platform   ", action.Platform));
+            sb.AppendLine(string.Concat("# @advancedpaste:formats   ", action.Formats));
+            sb.AppendLine(string.Concat("# @advancedpaste:enabled   ", action.IsEnabled ? "true" : "false"));
+            if (!action.RequiresAutoDetect && !string.IsNullOrWhiteSpace(action.Requires))
+            {
+                sb.AppendLine(string.Concat("# @advancedpaste:requires   ", action.Requires));
+            }
+
+            return sb.ToString().TrimEnd();
+        }
+
+        private static void WriteScriptHeader(AdvancedPastePythonScriptAction action)
+        {
+            if (!System.IO.File.Exists(action.ScriptPath))
+            {
+                return;
+            }
+
+            var lines = System.IO.File.ReadAllLines(action.ScriptPath, System.Text.Encoding.UTF8).ToList();
+
+            var tagUpdates = new Dictionary<string, string>(StringComparer.OrdinalIgnoreCase)
+            {
+                ["@advancedpaste:name"] = action.Name,
+                ["@advancedpaste:desc"] = action.Description,
+                ["@advancedpaste:platform"] = action.Platform,
+                ["@advancedpaste:formats"] = action.Formats,
+                ["@advancedpaste:enabled"] = action.IsEnabled ? "true" : "false",
+            };
+
+            // Only write requires tag in manual mode
+            if (!action.RequiresAutoDetect && !string.IsNullOrWhiteSpace(action.Requires))
+            {
+                tagUpdates["@advancedpaste:requires"] = action.Requires;
+            }
+
+            var updatedTags = new HashSet<string>(StringComparer.OrdinalIgnoreCase);
+            int lastTagLine = -1;
+
+            // Collect indices of duplicate tag lines and requires lines to remove
+            var linesToRemove = new HashSet<int>();
+
+            for (int i = 0; i < Math.Min(lines.Count, 50); i++)
+            {
+                var trimmed = lines[i].Trim();
+                if (!trimmed.StartsWith('#'))
+                {
+                    continue;
+                }
+
+                // Handle requires tag separately (may need full removal in auto mode)
+                if (ContainsTag(trimmed, "@advancedpaste:requires"))
+                {
+                    lastTagLine = i;
+
+                    if (action.RequiresAutoDetect)
+                    {
+                        // Auto-detect mode: remove all requires lines
+                        linesToRemove.Add(i);
+                    }
+                    else if (!updatedTags.Contains("@advancedpaste:requires"))
+                    {
+                        // Manual mode: update first occurrence
+                        if (tagUpdates.ContainsKey("@advancedpaste:requires"))
+                        {
+                            lines[i] = $"# @advancedpaste:requires   {action.Requires}";
+                            updatedTags.Add("@advancedpaste:requires");
+                        }
+                    }
+                    else
+                    {
+                        // Duplicate requires line: remove
+                        linesToRemove.Add(i);
+                    }
+
+                    continue;
+                }
+
+                foreach (var (tag, newValue) in tagUpdates)
+                {
+                    if (ContainsTag(trimmed, tag))
+                    {
+                        if (!updatedTags.Contains(tag))
+                        {
+                            // First occurrence: update in place
+                            lines[i] = $"# {tag}   {newValue}";
+                            updatedTags.Add(tag);
+                            lastTagLine = i;
+                        }
+                        else
+                        {
+                            // Duplicate: mark for removal
+                            linesToRemove.Add(i);
+                        }
+
+                        break;
+                    }
+                }
+
+                if (trimmed.Contains("@advancedpaste:"))
+                {
+                    lastTagLine = i;
+                }
+            }
+
+            // Remove duplicate/unwanted lines in reverse order to preserve indices
+            foreach (var idx in linesToRemove.OrderByDescending(x => x))
+            {
+                lines.RemoveAt(idx);
+            }
+
+            // Recalculate insertion point after removals
+            var removedBeforeLastTag = linesToRemove.Count(idx => idx <= lastTagLine);
+            var insertionPoint = lastTagLine >= 0 ? lastTagLine + 1 - removedBeforeLastTag : 0;
+
+            var newLines = new List<string>();
+            foreach (var (tag, newValue) in tagUpdates)
+            {
+                if (!updatedTags.Contains(tag))
+                {
+                    newLines.Add($"# {tag}   {newValue}");
+                }
+            }
+
+            if (newLines.Count > 0)
+            {
+                insertionPoint = Math.Min(insertionPoint, lines.Count);
+                lines.InsertRange(insertionPoint, newLines);
+            }
+
+            System.IO.File.WriteAllLines(action.ScriptPath, lines, new System.Text.UTF8Encoding(false));
+        }
+
         public static IEnumerable<AIServiceTypeMetadata> AvailableProviders => AIServiceTypeRegistry.GetAvailableServiceTypes();
 
         /// <summary>

tools/build/build-common.ps1

@@ -201,6 +201,10 @@ function Ensure-VsDevEnvironment {
         if (-not $instPaths) {
             try { $p2 = & $vswhere -latest -products * -property installationPath 2>$null; if ($p2) { $instPaths += $p2 } } catch {}
         }
+        # Fallback: include incomplete installations (e.g. pending reboot after component install)
+        if (-not $instPaths) {
+            try { $p3 = & $vswhere -latest -products * -all -requires Microsoft.VisualStudio.Component.VC.Tools.x86.x64 -property installationPath 2>$null; if ($p3) { $instPaths += $p3 } } catch {}
+        }
     }
 
     # Add explicit common year-based candidates as a last resort