aiden-runtime 4.1.1 → 4.1.2

package/dist/tools/v4/system/appLaunch.js

@@ -0,0 +1,92 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/appLaunch.ts — `app_launch` tool.
+ *
+ * Start a Windows application by executable name or absolute path via
+ * PowerShell `Start-Process`. Resolves bare names through PATH and
+ * `App Paths` registry (so `spotify`, `notepad`, `chrome` all work
+ * without the user supplying the full path).
+ *
+ * Returns the PID of the launched process when available — useful for
+ * a subsequent `app_close` invocation or for confirming "did the
+ * launch succeed?" without a `window_list` round-trip.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appLaunchTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+function buildPs(appName, args) {
+    // Single-quote escape the app name for PowerShell.
+    const safeApp = appName.replace(/'/g, "''");
+    const argString = args && args.length > 0
+        ? `-ArgumentList @(${args.map((a) => `'${a.replace(/'/g, "''")}'`).join(',')})`
+        : '';
+    return [
+        `try {`,
+        `  $p = Start-Process '${safeApp}' ${argString} -PassThru -ErrorAction Stop;`,
+        `  Write-Output ('PID=' + $p.Id);`,
+        `} catch {`,
+        // App Paths registry resolution fallback: Start-Process sometimes
+        // fails on bare names that Windows would otherwise resolve via
+        // App Paths (Spotify, Chrome). Fall back to `start <name>` which
+        // honours App Paths.
+        `  cmd /c "start '' '${safeApp}'";`,
+        `  Write-Output 'PID=unknown (launched via cmd start fallback)';`,
+        `}`,
+    ].join(' ');
+}
+exports.appLaunchTool = {
+    schema: {
+        name: 'app_launch',
+        description: 'Launch a Windows application by exe name, friendly name (resolved via App Paths registry), or absolute path. Returns the launched PID when available. Use for "open Spotify" / "start Chrome" / etc. Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                app: {
+                    type: 'string',
+                    description: 'Application identifier. Accepts: bare name (e.g. "spotify", "notepad", "chrome"), exe basename ("notepad.exe"), or absolute path ("C:\\\\Program Files\\\\App\\\\app.exe").',
+                },
+                args: {
+                    type: 'array',
+                    description: 'Optional command-line arguments to pass to the app.',
+                    items: { type: 'string', description: 'A single CLI argument string.' },
+                },
+            },
+            required: ['app'],
+        },
+    },
+    category: 'execute',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('app_launch');
+        const app = typeof args.app === 'string' ? args.app.trim() : '';
+        if (!app) {
+            return { success: false, error: '`app` is required and must be non-empty.' };
+        }
+        const rawArgs = Array.isArray(args.args) ? args.args : undefined;
+        const cliArgs = rawArgs?.filter((a) => typeof a === 'string');
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(app, cliArgs), {
+                timeoutMs: 20000,
+            });
+            const out = stdout.trim();
+            // Extract PID when Start-Process succeeded; null for cmd-fallback path.
+            const pidMatch = out.match(/PID=(\d+)/);
+            const pid = pidMatch ? Number(pidMatch[1]) : null;
+            return { success: true, app, pid, raw: out };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

package/dist/tools/v4/system/clipboardRead.js

@@ -0,0 +1,54 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/clipboardRead.ts — `clipboard_read` tool.
+ *
+ * Read the current Windows clipboard contents as text via PowerShell
+ * `Get-Clipboard`. Non-text clipboard contents (image, file list, RTF)
+ * return an empty string — text-only by design; binary surfaces would
+ * need a different rendering contract.
+ *
+ * Privacy note: clipboard contents can include passwords, OTPs, and
+ * personal text. Tool description flags this so the model can warn
+ * the user before reading sensitive contexts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clipboardReadTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+exports.clipboardReadTool = {
+    schema: {
+        name: 'clipboard_read',
+        description: 'Read the current Windows clipboard contents as text. Non-text clipboard data returns an empty string. Privacy-sensitive: clipboard may contain passwords, OTPs, or personal text — only invoke when the user has clearly asked. Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    category: 'read',
+    mutates: false,
+    toolset: 'system',
+    async execute(_args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('clipboard_read');
+        try {
+            // -Raw returns the whole buffer as one string (including newlines)
+            // rather than splitting on line breaks.
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)('Get-Clipboard -Raw', { timeoutMs: 5000 });
+            // PowerShell appends a trailing CRLF — strip ONE trailing newline
+            // so the model sees what the user actually copied.
+            const text = stdout.replace(/\r?\n$/, '');
+            return { success: true, text, length: text.length };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

package/dist/tools/v4/system/clipboardWrite.js

@@ -0,0 +1,84 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/clipboardWrite.ts — `clipboard_write` tool.
+ *
+ * Write text to the Windows clipboard via PowerShell `Set-Clipboard`.
+ * Caller passes the text as a string arg; we route it through stdin to
+ * the PowerShell process to side-step shell-argument quoting issues
+ * with newlines / special chars (Aiden's existing `shellInterpolation`
+ * pattern doesn't apply to tool args, but stdin is still the safest
+ * conduit for arbitrary text).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.clipboardWriteTool = void 0;
+const node_child_process_1 = require("node:child_process");
+const _psHelpers_1 = require("./_psHelpers");
+/**
+ * Spawn `powershell.exe Set-Clipboard` with the text piped on stdin.
+ * Wrapper Promise so the tool's `execute` can `await` it.
+ */
+function setClipboardViaStdin(text, timeoutMs) {
+    return new Promise((resolve, reject) => {
+        const ps = (0, node_child_process_1.exec)(
+        // -Command - reads the script from stdin; but we want to PIPE the
+        // *value* not the script. Cleanest cross-version PowerShell path:
+        // read stdin in PowerShell and pass to Set-Clipboard.
+        'powershell.exe -NoProfile -Command "$input | Set-Clipboard"', { timeout: timeoutMs, windowsHide: true }, (err) => {
+            if (err)
+                reject(err);
+            else
+                resolve();
+        });
+        if (!ps.stdin) {
+            reject(new Error('PowerShell child has no stdin'));
+            return;
+        }
+        ps.stdin.write(text);
+        ps.stdin.end();
+    });
+}
+exports.clipboardWriteTool = {
+    schema: {
+        name: 'clipboard_write',
+        description: 'Write text to the Windows clipboard. Replaces existing clipboard contents. Handles multi-line strings and special characters safely (text routed via stdin). Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                text: {
+                    type: 'string',
+                    description: 'Text to place on the clipboard. Replaces whatever is currently there.',
+                },
+            },
+            required: ['text'],
+        },
+    },
+    category: 'execute',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('clipboard_write');
+        const text = typeof args.text === 'string' ? args.text : '';
+        // Empty string IS valid — it clears the clipboard. Distinguished
+        // from "no arg supplied" by the explicit type check.
+        if (typeof args.text !== 'string') {
+            return { success: false, error: '`text` is required and must be a string.' };
+        }
+        try {
+            await setClipboardViaStdin(text, 5000);
+            return { success: true, length: text.length };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

package/dist/tools/v4/system/mediaKey.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/mediaKey.ts — `media_key` tool.
+ *
+ * Send Windows media-control keys (play/pause, next, previous, stop)
+ * via PowerShell `System.Windows.Forms.SendKeys`. Works against any
+ * app that registers with SMTC (Spotify, YouTube in browser, Windows
+ * Media Player, Apple Music for Windows, VLC with MediaKey plugin,
+ * etc.) — the OS routes the keypress to the currently-active media
+ * session, so no per-app integration is required.
+ *
+ * Pairs with `now_playing` (read-only probe): the model reads what's
+ * playing, then issues the right media_key to control it.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mediaKeyTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+const ACTION_KEYS = {
+    play_pause: '{MEDIA_PLAY_PAUSE}',
+    next: '{MEDIA_NEXT_TRACK}',
+    previous: '{MEDIA_PREV_TRACK}',
+    stop: '{MEDIA_STOP}',
+};
+exports.mediaKeyTool = {
+    schema: {
+        name: 'media_key',
+        description: 'Send a media-control key to the active media session (Spotify, YouTube, etc.). Pair with `now_playing` to inspect current state. Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['play_pause', 'next', 'previous', 'stop'],
+                    description: "'play_pause' toggles play/pause on the active media session. " +
+                        "'next' / 'previous' skip tracks. 'stop' halts playback.",
+                },
+            },
+            required: ['action'],
+        },
+    },
+    category: 'execute',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('media_key');
+        const action = args.action;
+        if (!ACTION_KEYS[action]) {
+            return {
+                success: false,
+                error: `Unknown media action: ${String(args.action)}. ` +
+                    `Valid: ${Object.keys(ACTION_KEYS).join(', ')}`,
+            };
+        }
+        const sendkey = ACTION_KEYS[action];
+        const script = [
+            'Add-Type -AssemblyName System.Windows.Forms;',
+            `[System.Windows.Forms.SendKeys]::SendWait('${sendkey}');`,
+            `Write-Output 'sent:${action}';`,
+        ].join(' ');
+        try {
+            await (0, _psHelpers_1.runPowerShell)(script, { timeoutMs: 5000 });
+            return { success: true, action };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

package/dist/tools/v4/system/osProcessList.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/osProcessList.ts — `os_process_list` tool.
+ *
+ * Lists OS-wide running processes via `Get-Process`. Distinct from the
+ * existing `process_list` tool which only enumerates child processes
+ * Aiden itself spawned via `process_spawn` — that's the wrong shape
+ * for questions like "is claude code running?" (the answer's process
+ * was started by the user, not Aiden).
+ *
+ * Filtering is supported via a substring on the process name. Default
+ * (no filter) lists the top-CPU processes capped at 30 so the model
+ * doesn't drown in a 200-row dump.
+ *
+ * Read-only. Cross-platform fallback returns a structured error
+ * pointing at the issue tracker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.osProcessListTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+const DEFAULT_LIMIT = 30;
+const MAX_LIMIT = 200;
+function buildPs(nameFilter, limit) {
+    // Escape single quotes for the PowerShell -Name argument.
+    const filter = (nameFilter ?? '').trim();
+    // Get-Process picks `Name` (short), `Id` (pid), `CPU` (seconds), and
+    // `WorkingSet` (memory). ConvertTo-Json emits an array we parse.
+    const base = filter.length > 0
+        ? `Get-Process -Name '*${filter.replace(/'/g, "''")}*' -ErrorAction SilentlyContinue`
+        : 'Get-Process';
+    return [
+        base,
+        `| Sort-Object CPU -Descending`,
+        `| Select-Object -First ${limit} Name, Id, @{N='CPU';E={[math]::Round($_.CPU,2)}}, @{N='MemoryMB';E={[math]::Round($_.WorkingSet64/1MB,1)}}`,
+        `| ConvertTo-Json -Compress -Depth 2`,
+    ].join(' ');
+}
+exports.osProcessListTool = {
+    schema: {
+        name: 'os_process_list',
+        description: 'List OS-wide running processes (top by CPU). Use this to answer questions like "is X running?" or "what apps are using CPU?". Supports an optional name substring filter. Distinct from `process_list` which only shows processes Aiden itself spawned. Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Optional process-name substring filter, e.g. "claude" to find "claude.exe" / "claude_code.exe" / "claude-helper.exe". Omit to list top-CPU processes.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max rows to return (default 30, max 200). Use a higher value when answering "list everything running" style questions.',
+                },
+            },
+        },
+    },
+    category: 'read',
+    mutates: false,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('os_process_list');
+        const nameArg = typeof args.name === 'string' ? args.name : undefined;
+        const rawLimit = typeof args.limit === 'number' ? args.limit : DEFAULT_LIMIT;
+        const limit = Math.min(Math.max(1, Math.floor(rawLimit)), MAX_LIMIT);
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(nameArg, limit), {
+                timeoutMs: 15000,
+            });
+            const trimmed = stdout.trim();
+            // Get-Process returns nothing when the filter matches zero processes;
+            // PowerShell pipeline prints empty. Treat as "no matches" success.
+            if (trimmed.length === 0) {
+                return { success: true, processes: [], count: 0, filter: nameArg };
+            }
+            // ConvertTo-Json emits an object (single result) or array (multiple).
+            // Normalise to array.
+            const parsed = JSON.parse(trimmed);
+            const processes = Array.isArray(parsed) ? parsed : [parsed];
+            return {
+                success: true,
+                count: processes.length,
+                filter: nameArg,
+                processes,
+            };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

package/dist/tools/v4/system/screenshot.js

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/screenshot.ts — `screenshot` tool.
+ *
+ * Captures the full desktop and writes it as a PNG to
+ * `<aidenHome>/screenshots/<timestamp>.png`. Returns the absolute path
+ * in `path` so a Telegram / Discord channel adapter can attach the
+ * file directly without a separate file_read round-trip.
+ *
+ * Privacy note (Phase v4.1.2-followup-3): this tool reads what is
+ * currently visible on the screen — anything in front of the user.
+ * The tool description says so explicitly so users know what they're
+ * approving when the model invokes it.
+ *
+ * Implementation: PowerShell-only, no native dependency. Uses
+ * `System.Windows.Forms.Screen` + `System.Drawing.Bitmap` /
+ * `Graphics.CopyFromScreen()` — both ship with .NET on every modern
+ * Windows install. Cross-platform fallback returns a structured error.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenshotTool = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const _psHelpers_1 = require("./_psHelpers");
+/**
+ * Build the PowerShell capture script. The bitmap dimensions come from
+ * `Screen::PrimaryScreen.Bounds` so we get the actual primary-monitor
+ * resolution, not a hardcoded value. SaveAs PNG to keep losslessness
+ * — file size on a 4K screen is ~4-8 MB which is fine for chat.
+ */
+function buildScreenshotPs(outPath) {
+    const psQuoted = outPath.replace(/'/g, "''"); // PowerShell single-quote escape
+    return [
+        'Add-Type -AssemblyName System.Windows.Forms;',
+        'Add-Type -AssemblyName System.Drawing;',
+        '$bounds = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds;',
+        '$bitmap = New-Object System.Drawing.Bitmap $bounds.Width, $bounds.Height;',
+        '$gfx = [System.Drawing.Graphics]::FromImage($bitmap);',
+        '$gfx.CopyFromScreen($bounds.Location, [System.Drawing.Point]::Empty, $bounds.Size);',
+        `$bitmap.Save('${psQuoted}', [System.Drawing.Imaging.ImageFormat]::Png);`,
+        '$gfx.Dispose(); $bitmap.Dispose();',
+        `Write-Output '${psQuoted}';`,
+    ].join(' ');
+}
+exports.screenshotTool = {
+    schema: {
+        name: 'screenshot',
+        description: 'Capture the current primary-monitor desktop as a PNG. Returns the absolute path of the saved file. Reads whatever is currently visible on screen — privacy-sensitive; only invoke when the user explicitly asks for a screenshot or screen share. Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    category: 'read',
+    mutates: false,
+    toolset: 'system',
+    async execute(_args, ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('screenshot');
+        if (!ctx.paths) {
+            return { success: false, error: 'aiden paths not wired (test mode?)' };
+        }
+        try {
+            const dir = node_path_1.default.join(ctx.paths.root, 'screenshots');
+            await node_fs_1.promises.mkdir(dir, { recursive: true });
+            const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const outPath = node_path_1.default.join(dir, `${stamp}.png`);
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildScreenshotPs(outPath), {
+                timeoutMs: 30000,
+            });
+            // Verify the file actually landed on disk — PowerShell can exit 0
+            // and have written nothing on an exotic display configuration.
+            try {
+                const stat = await node_fs_1.promises.stat(outPath);
+                return {
+                    success: true,
+                    path: outPath,
+                    size: stat.size,
+                    // For Telegram / Discord adapters — they can attach via path.
+                    attachAs: 'image/png',
+                };
+            }
+            catch {
+                return {
+                    success: false,
+                    error: `screenshot script ran but file not found at ${outPath} (stdout=${stdout.trim().slice(0, 120)})`,
+                };
+            }
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

package/dist/tools/v4/system/volumeSet.js

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/volumeSet.ts — `volume_set` tool.
+ *
+ * Set the Windows master-volume level to a percentage (0-100), or
+ * toggle mute. Uses the Shell.Application COM object's appCommand
+ * SendKeys for up/down nudges; for absolute level setting, talks to
+ * `IAudioEndpointVolume` via PowerShell inline C# (Add-Type) — no
+ * external binary (no nircmd, no soundvolumeview).
+ *
+ * The inline-C# approach is well-trodden Windows lore: the
+ * IAudioEndpointVolume COM interface is part of the Core Audio APIs
+ * available since Vista. We declare the interop types in PowerShell,
+ * invoke `SetMasterVolumeLevelScalar`, and clean up. Adds ~1-2s
+ * cold-start (PowerShell Add-Type compilation) — fine for an
+ * occasionally-invoked control.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.volumeSetTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+const ADD_TYPE_AUDIO = `
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+[Guid("5CDF2C82-841E-4546-9722-0CF74078229A"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+interface IAudioEndpointVolume {
+  int RegisterControlChangeNotify(IntPtr cb);
+  int UnregisterControlChangeNotify(IntPtr cb);
+  int GetChannelCount(out uint count);
+  int SetMasterVolumeLevel(float level, Guid ctx);
+  int SetMasterVolumeLevelScalar(float level, Guid ctx);
+  int GetMasterVolumeLevel(out float level);
+  int GetMasterVolumeLevelScalar(out float level);
+  int SetChannelVolumeLevel(uint ch, float level, Guid ctx);
+  int SetChannelVolumeLevelScalar(uint ch, float level, Guid ctx);
+  int GetChannelVolumeLevel(uint ch, out float level);
+  int GetChannelVolumeLevelScalar(uint ch, out float level);
+  int SetMute(bool mute, Guid ctx);
+  int GetMute(out bool mute);
+  int GetVolumeStepInfo(out uint step, out uint count);
+  int VolumeStepUp(Guid ctx);
+  int VolumeStepDown(Guid ctx);
+  int QueryHardwareSupport(out uint mask);
+  int GetVolumeRange(out float min, out float max, out float inc);
+}
+[Guid("A95664D2-9614-4F35-A746-DE8DB63617E6"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+interface IMMDeviceEnumerator {
+  int NotImpl0();
+  int GetDefaultAudioEndpoint(int dataFlow, int role, out IMMDevice ep);
+}
+[Guid("D666063F-1587-4E43-81F1-B948E807363F"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+interface IMMDevice {
+  int Activate(ref Guid id, int clsCtx, IntPtr pa, [MarshalAs(UnmanagedType.IUnknown)] out object o);
+}
+[ComImport, Guid("BCDE0395-E52F-467C-8E3D-C4579291692E")]
+class MMDeviceEnumeratorComObject { }
+public static class Audio {
+  static IAudioEndpointVolume Vol() {
+    var enumerator = new MMDeviceEnumeratorComObject() as IMMDeviceEnumerator;
+    IMMDevice dev = null;
+    Marshal.ThrowExceptionForHR(enumerator.GetDefaultAudioEndpoint(0, 1, out dev));
+    Guid epvid = typeof(IAudioEndpointVolume).GUID;
+    object o;
+    Marshal.ThrowExceptionForHR(dev.Activate(ref epvid, 7, IntPtr.Zero, out o));
+    return o as IAudioEndpointVolume;
+  }
+  public static float GetLevel() { float l; Marshal.ThrowExceptionForHR(Vol().GetMasterVolumeLevelScalar(out l)); return l; }
+  public static void SetLevel(float level) { Marshal.ThrowExceptionForHR(Vol().SetMasterVolumeLevelScalar(level, Guid.Empty)); }
+  public static bool GetMute() { bool m; Marshal.ThrowExceptionForHR(Vol().GetMute(out m)); return m; }
+  public static void SetMute(bool mute) { Marshal.ThrowExceptionForHR(Vol().SetMute(mute, Guid.Empty)); }
+}
+'@;
+`;
+function buildPs(action, percent) {
+    if (action === 'set' && typeof percent === 'number') {
+        const scalar = (Math.max(0, Math.min(100, percent)) / 100).toFixed(4);
+        return [
+            ADD_TYPE_AUDIO,
+            `[Audio]::SetLevel([float]${scalar});`,
+            `$level = [Audio]::GetLevel();`,
+            `Write-Output ([math]::Round($level * 100, 0));`,
+        ].join('\n');
+    }
+    if (action === 'mute') {
+        return [ADD_TYPE_AUDIO, `[Audio]::SetMute($true); Write-Output 'muted';`].join('\n');
+    }
+    if (action === 'unmute') {
+        return [ADD_TYPE_AUDIO, `[Audio]::SetMute($false); Write-Output 'unmuted';`].join('\n');
+    }
+    // toggle_mute
+    return [
+        ADD_TYPE_AUDIO,
+        `$cur = [Audio]::GetMute(); [Audio]::SetMute(-not $cur);`,
+        `Write-Output (if (-not $cur) {'muted'} else {'unmuted'});`,
+    ].join('\n');
+}
+exports.volumeSetTool = {
+    schema: {
+        name: 'volume_set',
+        description: 'Set Windows master volume to a percentage (0-100), or mute / unmute / toggle mute. Operates on the default audio endpoint. Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['set', 'mute', 'unmute', 'toggle_mute'],
+                    description: "'set' requires `percent`. 'mute' / 'unmute' force the state. 'toggle_mute' flips it.",
+                },
+                percent: {
+                    type: 'number',
+                    description: 'Target volume 0-100 (only used when action="set"). Values outside the range are clamped.',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    category: 'execute',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('volume_set');
+        const action = args.action;
+        if (!['set', 'mute', 'unmute', 'toggle_mute'].includes(action)) {
+            return {
+                success: false,
+                error: `Unknown volume action: ${String(args.action)}. ` +
+                    `Valid: set, mute, unmute, toggle_mute`,
+            };
+        }
+        const percent = typeof args.percent === 'number' ? args.percent : undefined;
+        if (action === 'set' && percent === undefined) {
+            return {
+                success: false,
+                error: "action='set' requires a numeric `percent` (0-100).",
+            };
+        }
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(action, percent), {
+                timeoutMs: 10000,
+            });
+            return { success: true, action, result: stdout.trim() };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};