aiden-runtime 4.1.1 → 4.1.3

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

@@ -0,0 +1,211 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/mediaTransport.ts — `media_transport` tool. v4.1.4-media.
+ *
+ * Verified play/pause/skip against a specific GSMTC session. Replaces
+ * the blind-keystroke `media_key` behavior for the common case where
+ * the user names an app ("pause Spotify", "resume YouTube"): instead
+ * of blasting VK_MEDIA_PLAY_PAUSE at whichever app the OS most
+ * recently routed to, we enumerate sessions, match the target by
+ * AppUserModelId substring (or fall back to title contains), and call
+ * `TryPlayAsync()` / `TryPauseAsync()` / etc. directly on that session.
+ *
+ * Layer 2 of the three-layer media-control hierarchy v4.1.4 establishes:
+ *   1. Semantic API (Spotify Web API when authed) — out of this slice
+ *   2. OS media-session API (GSMTC)               ← this tool writes
+ *   3. Global media keys (mediaKey tool)          — blind fallback
+ *
+ * Honesty story: unlike `media_key`'s blind keystroke + degraded flag,
+ * `media_transport` reports `success: true` ONLY when GSMTC returns
+ * its `Success` result. Failures (session disappeared mid-call, app
+ * doesn't support that action, no matching target) surface as
+ * `success: false` with the specific reason. No degraded flag — we
+ * either have OS-confirmed action or we have an honest failure.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.mediaTransportTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+/** GSMTC API call per action. Keys match the schema enum verbatim. */
+const ACTION_METHOD = {
+    play: 'TryPlayAsync',
+    pause: 'TryPauseAsync',
+    toggle: 'TryTogglePlayPauseAsync',
+    next: 'TrySkipNextAsync',
+    previous: 'TrySkipPreviousAsync',
+    stop: 'TryStopAsync',
+};
+/**
+ * Build the PowerShell snippet. `target` is a case-insensitive substring
+ * matched against each session's AppUserModelId first, then the track
+ * title as a softer fallback. Empty/omitted target selects the current
+ * session (matches the legacy `media_key` semantics, no surprise).
+ *
+ * Output: a single JSON line with `matched` (boolean — did we find a
+ * session) and `result` (the GSMTC enum value as a string —
+ * `Success` / `Failed` / `UnknownError` etc.).
+ */
+function buildPs(action, target) {
+    const method = ACTION_METHOD[action];
+    // Single-quote-escape target for PS string literal. Lowercase compare
+    // happens inside the script so the model can pass "Spotify" or "spotify".
+    const safeTarget = target.replace(/'/g, "''");
+    return `
+${(0, _psHelpers_1.winRtAwaitPreamble)()}
+$mgType = [Windows.Media.Control.GlobalSystemMediaTransportControlsSessionManager,Windows.Media.Control,ContentType=WindowsRuntime]
+$pType = [Windows.Media.Control.GlobalSystemMediaTransportControlsSessionMediaProperties,Windows.Media.Control,ContentType=WindowsRuntime]
+$mgr = Await ($mgType::RequestAsync()) $mgType
+$target = '${safeTarget}'
+$picked = $null
+if ($target.Length -gt 0) {
+    $lt = $target.ToLower()
+    foreach ($s in $mgr.GetSessions()) {
+        if ($s.SourceAppUserModelId -and $s.SourceAppUserModelId.ToLower().Contains($lt)) {
+            $picked = $s
+            break
+        }
+    }
+    if (-not $picked) {
+        # Soft fallback: title contains.
+        foreach ($s in $mgr.GetSessions()) {
+            $p = $null
+            try { $p = Await ($s.TryGetMediaPropertiesAsync()) $pType } catch { $p = $null }
+            if ($p -and $p.Title -and $p.Title.ToLower().Contains($lt)) {
+                $picked = $s
+                break
+            }
+        }
+    }
+} else {
+    $picked = $mgr.GetCurrentSession()
+}
+if (-not $picked) {
+    @{ matched=$false; result='NoSession'; appUserModelId=$null } | ConvertTo-Json -Compress
+    exit 0
+}
+$res = Await ($picked.${method}()) ([bool])
+# v4.1.3-essentials bugfix: PowerShell 5.1 does NOT accept a bare
+# parenthesized \`if\` expression inside a hashtable literal — it
+# parses \`(if ...)\` as a command invocation and fails with
+# "The term 'if' is not recognized as the name of a cmdlet..." (no
+# ternary operator until PS 7+). The \`$(...)\` subexpression
+# operator forces statement-context evaluation in PS 5.1, which is
+# what we need here.
+$status = if ($res) { 'Success' } else { 'Failed' }
+@{ matched=$true; result=$status; appUserModelId=$picked.SourceAppUserModelId } | ConvertTo-Json -Compress
+`.trim();
+}
+exports.mediaTransportTool = {
+    schema: {
+        name: 'media_transport',
+        description: 'PREFERRED for named-app media control. Verified play/pause/skip ' +
+            'against a specific Windows GSMTC media session — returns OS-confirmed ' +
+            'success/failure, NOT a blind keystroke like `media_key`. Use this ' +
+            'whenever the user names an app ("pause Spotify", "resume YouTube"). ' +
+            'Target matches by AppUserModelId substring ("spotify" → Spotify.exe), ' +
+            'then track title as soft fallback. Omit `target` to act on the ' +
+            'current session. Pair with `media_sessions` (read) to enumerate ' +
+            'available apps. Windows-only in v4.1.4.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['play', 'pause', 'toggle', 'next', 'previous', 'stop'],
+                    description: "Action to invoke on the matched session. 'toggle' flips " +
+                        "play/pause. 'play' / 'pause' are explicit. 'next' / 'previous' " +
+                        "skip tracks. 'stop' halts playback.",
+                },
+                target: {
+                    type: 'string',
+                    description: 'Optional app/track identifier. Case-insensitive substring ' +
+                        'match against AppUserModelId first ("spotify" matches ' +
+                        'Spotify.exe), then track title. Omit to act on the OS-routed ' +
+                        'current session.',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    category: 'execute',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)()) {
+            // v4.1.3-essentials: tailored capability card for non-Windows.
+            // Layer-1 (web API) and layer-3b (CDP) alternatives exist on
+            // every platform; only layer-2 (GSMTC verified transport) is
+            // Windows-bound.
+            return (0, _psHelpers_1.windowsOnlyError)('media_transport', {
+                canStill: [
+                    'Use Spotify Web API via a skill that wraps OAuth + /me/player',
+                    'Use Chrome DevTools Protocol (`browser_*` tools) to drive a YouTube tab',
+                    'Use `shell_exec` with `playerctl` (Linux) or `osascript` (macOS) for system-wide control',
+                ],
+                cannotReliably: [
+                    'GSMTC-verified play/pause/skip with OS-level success confirmation',
+                    'Target a specific app by AppUserModelId without OS media-session APIs',
+                ],
+                fix: 'Run Aiden on Windows for GSMTC, OR install a Spotify-OAuth skill ' +
+                    'for layer-1 control, OR use `shell_exec` with the platform\'s media-key utility.',
+            });
+        }
+        const action = args.action;
+        if (!ACTION_METHOD[action]) {
+            return {
+                success: false,
+                error: `Unknown action: ${String(args.action)}. ` +
+                    `Valid: ${Object.keys(ACTION_METHOD).join(', ')}`,
+            };
+        }
+        const target = typeof args.target === 'string' ? args.target.trim() : '';
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(action, target), {
+                timeoutMs: 8000,
+            });
+            const trimmed = stdout.trim();
+            if (trimmed.length === 0) {
+                return {
+                    success: false,
+                    error: 'media_transport returned empty output from PowerShell',
+                };
+            }
+            const parsed = JSON.parse(trimmed);
+            if (!parsed.matched) {
+                return {
+                    success: false,
+                    error: target
+                        ? `No media session matched target "${target}". Call media_sessions to see what's available.`
+                        : 'No active media session. Open a media app first (Spotify, YouTube, etc.).',
+                };
+            }
+            if (parsed.result !== 'Success') {
+                return {
+                    success: false,
+                    error: `GSMTC ${action} returned ${parsed.result} for ${parsed.appUserModelId}. ` +
+                        `The app may not support that action in its current state.`,
+                    appUserModelId: parsed.appUserModelId,
+                };
+            }
+            // OS-confirmed success. No degraded flag — unlike media_key we
+            // KNOW the action landed on a specific session and the OS
+            // accepted it.
+            return {
+                success: true,
+                action,
+                appUserModelId: parsed.appUserModelId,
+            };
+        }
+        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),
+            };
+        }
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-runtime",
-  "version": "4.1.1",
+  "version": "4.1.3",
   "publishConfig": {
     "access": "public"
   },
@@ -77,6 +77,9 @@
     "dist:linux": "node scripts/prepare-electron.js && electron-builder --linux --x64 --publish never && node -e \"const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));p.main='./dist/index.js';fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\\n');console.log('  main restored')\"",
     "test": "vitest run",
     "test:ui": "vitest --ui",
+    "eval": "ts-node evals/cli.ts",
+    "eval:honesty": "ts-node evals/cli.ts --suite honesty",
+    "eval:scenario": "ts-node evals/cli.ts --scenario",
     "stress-test": "npx ts-node tests/stressTest.ts",
     "test:all": "npx ts-node tests/e2e/masterTestSuite.ts",
     "test:unit": "npx ts-node tests/e2e/masterTestSuite.ts --part1",