aiden-runtime 4.1.2 → 4.1.4

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

@@ -19,6 +19,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isWindows = exports.execAsync = void 0;
 exports.windowsOnlyError = windowsOnlyError;
 exports.runPowerShell = runPowerShell;
+exports.winRtAwaitPreamble = winRtAwaitPreamble;
 const node_child_process_1 = require("node:child_process");
 const node_util_1 = require("node:util");
 exports.execAsync = (0, node_util_1.promisify)(node_child_process_1.exec);
@@ -26,13 +27,43 @@ exports.execAsync = (0, node_util_1.promisify)(node_child_process_1.exec);
  * Standard "not supported on this platform" error payload. Surfaces a
  * link the user can file an issue against rather than pretending the
  * call quietly no-op'd.
+ *
+ * v4.1.3-essentials: now also returns a structured `capabilityCard`
+ * payload (per ToolCallResult.capabilityCard contract). The REPL
+ * renders the card as a bordered block above the bare-error fallback,
+ * giving non-Windows users a clear "here's what you can still do"
+ * surface instead of a one-line "platform unsupported" wall.
+ *
+ * The `canStill` / `cannotReliably` lists are passed by the caller so
+ * each tool can be specific (e.g. `app_input` mentions Chrome DevTools
+ * Protocol as a non-Windows alternative; `media_transport` points at
+ * `media_key` or a Spotify Web API skill instead). Falls back to a
+ * generic "use shell_exec for platform commands" hint when caller
+ * doesn't supply alternatives.
  */
-function windowsOnlyError(toolName) {
+function windowsOnlyError(toolName, alternatives) {
+    const canStill = alternatives?.canStill ?? [
+        'Use `shell_exec` to run platform-native commands directly',
+        'Use `os_process_list` to inspect what\'s running',
+    ];
+    const cannotReliably = alternatives?.cannotReliably ?? [
+        `Call \`${toolName}\` until cross-platform support lands`,
+    ];
+    const fix = alternatives?.fix
+        ?? `Run Aiden on Windows for full \`${toolName}\` support, or file an ` +
+            `issue at github.com/taracodlabs/aiden if your platform is a priority.`;
     return {
         success: false,
-        error: `Tool '${toolName}' is Windows-only in v4.1.2. macOS/Linux ` +
+        error: `Tool '${toolName}' is Windows-only. macOS/Linux ` +
             `support tracked at github.com/taracodlabs/aiden — please file an ` +
             `issue if needed. (Detected platform: ${process.platform})`,
+        requires: ['Windows'],
+        capabilityCard: {
+            title: `${toolName} requires Windows`,
+            canStill,
+            cannotReliably,
+            fix,
+        },
     };
 }
 /**
@@ -53,3 +84,40 @@ async function runPowerShell(script, options = {}) {
 }
 const isWindows = () => process.platform === 'win32';
 exports.isWindows = isWindows;
+/**
+ * v4.1.4-media: PowerShell 5.1 preamble that bridges WinRT
+ * `IAsyncOperation<T>` into a .NET `Task<T>` via
+ * `System.WindowsRuntimeSystemExtensions.AsTask`.
+ *
+ * Why: every WinRT call surface we touch — `GlobalSystemMediaTransport-
+ * ControlsSessionManager.RequestAsync()`, `Session.TryGetMediaPropertiesAsync()`,
+ * `Session.TryPlayAsync()`, etc. — returns `IAsyncOperation<T>`. PS5.1
+ * (the shell we target — it ships on every stock Win10/11 install) cannot
+ * call `.GetAwaiter().GetResult()` on those because WinRT awaiters aren't
+ * recognized as TPL-compatible. The reflection dance below grabs the
+ * single-arg overload of `AsTask`, specializes it to `T`, and invokes —
+ * yielding a `Task<T>` we can `.Wait()` on.
+ *
+ * Three callers consume this string:
+ *   - `core/tools/nowPlaying.ts`         (read GSMTC properties)
+ *   - `tools/v4/system/mediaSessions.ts` (enumerate GSMTC sessions)
+ *   - `tools/v4/system/mediaTransport.ts` (play/pause/skip on a target)
+ *
+ * Returned as a literal string — caller composes it into a larger
+ * PS script. Pure (no side effects, no PowerShell exec). No leading/
+ * trailing whitespace so callers can interpolate without surprises.
+ */
+function winRtAwaitPreamble() {
+    return `Add-Type -AssemblyName System.Runtime.WindowsRuntime
+function Await($WinRtTask, $ResultType) {
+    $m = ([System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object {
+        $_.Name -eq 'AsTask' -and
+        $_.GetParameters().Count -eq 1 -and
+        $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation\`1'
+    })[0]
+    $m = $m.MakeGenericMethod($ResultType)
+    $t = $m.Invoke($null, @($WinRtTask))
+    $t.Wait(-1) | Out-Null
+    $t.Result
+}`;
+}

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

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/appInput.ts — `app_input` tool. v4.1.4-media.
+ *
+ * Focus a window by process name, then send a SendKeys keystroke
+ * sequence to it. Useful escape hatch when neither the semantic API
+ * (layer 1) nor GSMTC (layer 2) surface a control — e.g. "press space
+ * in Chrome to pause this YouTube tab" when GSMTC doesn't enumerate
+ * the page as a media session.
+ *
+ * Honest about what it doesn't do: SendKeys lands keys in whatever
+ * window has focus AT THE MOMENT of the keystroke. We try
+ * AppActivate, but Windows refuses foreground activation when the
+ * calling process didn't recently receive input — the call returns
+ * a result we surface, but receipt at the target app is not
+ * guaranteed. Hence `degraded: true` on every successful invocation
+ * (mirrors the v4.1.3 honesty-degraded convention from `media_key`).
+ *
+ * Scope (v4.1.4): focus + SendKeys only. Mouse click coordinates,
+ * window-coords resolution, UI Automation deferred.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appInputTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+/**
+ * Build the PowerShell snippet. Calls AppActivate on the process by
+ * name, then SendKeys.SendWait. Both PowerShell calls return booleans /
+ * void; we capture stdout to JSON with the activation outcome so the
+ * model can see whether focus probably landed.
+ *
+ * Note on AppActivate: it returns $true if the process exists and a
+ * window was activated, $false otherwise. It does NOT confirm the
+ * window is the foreground from the OS's perspective — Windows
+ * sometimes flashes the taskbar entry instead. We pass that flag
+ * through as `activated` for transparency.
+ */
+function buildPs(processName, keys) {
+    // Single-quote escape both inputs for the PowerShell string literals.
+    const safeProc = processName.replace(/'/g, "''");
+    const safeKeys = keys.replace(/'/g, "''");
+    return [
+        'Add-Type -AssemblyName Microsoft.VisualBasic;',
+        'Add-Type -AssemblyName System.Windows.Forms;',
+        '$shell = New-Object -ComObject WScript.Shell;',
+        `$activated = $shell.AppActivate('${safeProc}');`,
+        // Give the OS ~150ms to settle before keystrokes — without this
+        // the keys can land in the calling shell on slower hardware.
+        'Start-Sleep -Milliseconds 150;',
+        `[System.Windows.Forms.SendKeys]::SendWait('${safeKeys}');`,
+        "@{ activated=[bool]$activated } | ConvertTo-Json -Compress;",
+    ].join(' ');
+}
+exports.appInputTool = {
+    schema: {
+        name: 'app_input',
+        description: 'Focus a Windows application window by process name and send a ' +
+            'SendKeys keystroke sequence to it. Use as a layer-3 fallback when ' +
+            'neither a semantic API (layer 1, e.g. Spotify Web API) nor GSMTC ' +
+            '(layer 2, `media_transport`) can do the job. Examples: "{SPACE}" to ' +
+            'pause a YouTube tab in Chrome, "^l" for Ctrl+L address-bar focus. ' +
+            'Receipt at the target app is best-effort — Windows can refuse ' +
+            'foreground activation; the tool reports `degraded:true` even on ' +
+            'apparent success. Windows-only in v4.1.4.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                app: {
+                    type: 'string',
+                    description: 'Process name (with or without .exe) or window-title substring ' +
+                        'AppActivate accepts: "chrome", "Spotify", "Notepad", etc.',
+                },
+                keys: {
+                    type: 'string',
+                    description: 'SendKeys-format keystroke sequence. Examples: "{SPACE}" = ' +
+                        'space, "^c" = Ctrl+C, "%{TAB}" = Alt+Tab, "Hello{ENTER}" = ' +
+                        'literal text + Enter. See Microsoft\'s SendKeys docs for the ' +
+                        'full grammar.',
+                },
+            },
+            required: ['app', 'keys'],
+        },
+    },
+    category: 'execute',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)()) {
+            return (0, _psHelpers_1.windowsOnlyError)('app_input', {
+                canStill: [
+                    '`browser_*` tools for any browser-hosted UI (Playwright cross-platform)',
+                    '`shell_exec` with `xdotool` (Linux X11) for arbitrary window input',
+                    '`shell_exec` with `osascript` (macOS) for AppleScript-driven keystrokes',
+                ],
+                cannotReliably: [
+                    'AppActivate + SendKeys against a specific Windows process',
+                    'VBA-style window focus by process-name substring',
+                ],
+                fix: 'Run Aiden on Windows for native AppActivate, or use Playwright ' +
+                    '(`browser_*`) / xdotool / osascript via `shell_exec` for your platform.',
+            });
+        }
+        const app = typeof args.app === 'string' ? args.app.trim() : '';
+        const keys = typeof args.keys === 'string' ? args.keys : '';
+        if (!app) {
+            return { success: false, error: '`app` is required and must be non-empty.' };
+        }
+        if (!keys) {
+            return { success: false, error: '`keys` is required and must be non-empty.' };
+        }
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(app, keys), {
+                timeoutMs: 5000,
+            });
+            const trimmed = stdout.trim();
+            let activated = false;
+            if (trimmed.length > 0) {
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    activated = parsed.activated === true;
+                }
+                catch {
+                    // Non-JSON output — degraded but not failed; the SendKeys
+                    // call likely still ran. Surface in degradedReason.
+                    activated = false;
+                }
+            }
+            return {
+                success: true,
+                app,
+                activated,
+                // v4.1.3-repl-polish honesty pattern: SendKeys cannot confirm
+                // receipt at the target window. AppActivate returning $true
+                // narrows the gap but doesn't close it — Windows can reject
+                // foreground activation silently. Always degraded.
+                degraded: true,
+                degradedReason: activated
+                    ? `keys sent to ${app}; activation reported success but cannot verify receipt`
+                    : `keys sent; ${app} window activation reported failure — receipt unlikely`,
+            };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

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

@@ -19,24 +19,84 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.appLaunchTool = void 0;
+exports.processNameFromApp = processNameFromApp;
 const _psHelpers_1 = require("./_psHelpers");
+/**
+ * Derive the bare process-name we expect `Get-Process` to find after
+ * launch. Strips path components, lowercases, drops the `.exe` extension.
+ * Used by the v4.1.3-essentials launch-verification poll.
+ *
+ *   "C:\\Program Files\\Spotify\\Spotify.exe"  → "spotify"
+ *   "Spotify.exe"                              → "spotify"
+ *   "spotify"                                  → "spotify"
+ *   "notepad++.exe"                            → "notepad++"
+ *
+ * Pure helper, exported for unit testing.
+ */
+function processNameFromApp(app) {
+    // Strip path components (Windows uses \; tolerate / too).
+    let bare = app.replace(/\\/g, '/').split('/').pop() ?? app;
+    // Drop a single trailing .exe (case-insensitive).
+    bare = bare.replace(/\.exe$/i, '');
+    return bare.toLowerCase();
+}
 function buildPs(appName, args) {
     // Single-quote escape the app name for PowerShell.
     const safeApp = appName.replace(/'/g, "''");
+    // The Get-Process verification probe uses the bare process name
+    // (no path, no .exe). Compute it once on the TS side so the PS
+    // script doesn't have to do string surgery.
+    const procName = processNameFromApp(appName).replace(/'/g, "''");
     const argString = args && args.length > 0
         ? `-ArgumentList @(${args.map((a) => `'${a.replace(/'/g, "''")}'`).join(',')})`
         : '';
+    // v4.1.3-essentials launch reliability fix:
+    //
+    // Primary path: `Start-Process -PassThru` — captures PID for any
+    // traditional Win32 exe. Fails for UWP / Microsoft Store apps
+    // (Spotify is UWP on most systems) because UWP launches route
+    // through ShellExecute which doesn't yield a child-process handle
+    // for `-PassThru`.
+    //
+    // Fallback path: `[System.Diagnostics.Process]::Start($app)` — the
+    // direct .NET ShellExecute call. Same App Paths / shell-association
+    // resolution as cmd's `start` builtin, but with proper error
+    // propagation (Windows popup → .NET exception → PS throw → tool
+    // returns success:false) and no quoting hell.
+    //
+    // Verification: after either path lands "PID=unknown", sleep 300ms
+    // and probe `Get-Process` for the bare process name. If the process
+    // exists, capture its PID — the launch verifiably succeeded. If not,
+    // signal "launched but no matching process appeared" so the tool can
+    // surface `success:false` honestly instead of pretending it worked.
     return [
+        `$ErrorActionPreference = 'Stop';`,
+        `$pid_out = $null;`,
         `try {`,
-        `  $p = Start-Process '${safeApp}' ${argString} -PassThru -ErrorAction Stop;`,
-        `  Write-Output ('PID=' + $p.Id);`,
+        `  $p = Start-Process '${safeApp}' ${argString} -PassThru;`,
+        `  if ($p -and $p.Id) { $pid_out = $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)';`,
+        `  try {`,
+        `    $p = [System.Diagnostics.Process]::Start('${safeApp}');`,
+        `    if ($p -and $p.Id) { $pid_out = $p.Id }`,
+        `  } catch {`,
+        `    Write-Output ('LAUNCH_FAILED=' + $_.Exception.Message);`,
+        `    return;`,
+        `  }`,
+        `}`,
+        // If we got a PID from either Start-Process or .NET Process.Start,
+        // we're done — emit it and exit.
+        `if ($pid_out) { Write-Output ('PID=' + $pid_out); return };`,
+        // Otherwise (UWP path, both layers returned null) verify via
+        // Get-Process. 300ms grace; enough for Windows shell to either
+        // launch the app or surface the "cannot find" popup.
+        `Start-Sleep -Milliseconds 300;`,
+        `$found = Get-Process -Name '${procName}' -ErrorAction SilentlyContinue ` +
+            `| Select-Object -First 1;`,
+        `if ($found) {`,
+        `  Write-Output ('PID=' + $found.Id + ' (verified via Get-Process)');`,
+        `} else {`,
+        `  Write-Output ('LAUNCH_UNVERIFIED=' + '${procName}');`,
         `}`,
     ].join(' ');
 }
@@ -77,10 +137,76 @@ exports.appLaunchTool = {
                 timeoutMs: 20000,
             });
             const out = stdout.trim();
-            // Extract PID when Start-Process succeeded; null for cmd-fallback path.
+            // v4.1.3-essentials: the PS script emits exactly ONE of three
+            // outcomes. Parse in order of confidence:
+            //   1. `LAUNCH_FAILED=<message>`     → .NET Process.Start threw;
+            //                                      the popup-error class is here.
+            //   2. `LAUNCH_UNVERIFIED=<name>`    → ShellExecute returned but
+            //                                      no matching process appeared
+            //                                      within 300ms — silently broken.
+            //   3. `PID=<n>` (optional `(verified via Get-Process)` suffix) →
+            //                                      verified launch with PID.
+            //
+            // Outcomes 1 and 2 return `success:false` so the model + user see
+            // the honest failure instead of a "launched" lie. Outcome 3 still
+            // sets `degraded:true` for the case where Start-Process succeeded
+            // but the app might still crash post-init (Spotify "boots" for 21s
+            // before stable state) — caller verifies via `os_process_list`.
+            const launchFailedMatch = out.match(/LAUNCH_FAILED=(.+)$/m);
+            if (launchFailedMatch) {
+                return {
+                    success: false,
+                    app,
+                    raw: out,
+                    error: `Could not launch '${app}': ${launchFailedMatch[1].trim()}. ` +
+                        `Verify the app is installed and resolvable via App Paths or PATH.`,
+                };
+            }
+            const launchUnverifiedMatch = out.match(/LAUNCH_UNVERIFIED=(.+)$/m);
+            if (launchUnverifiedMatch) {
+                return {
+                    success: false,
+                    app,
+                    raw: out,
+                    error: `Launch attempted but no process named '${launchUnverifiedMatch[1].trim()}' ` +
+                        `appeared within 300ms. Windows may have shown an error dialog, ` +
+                        `or the app failed to start. Try \`os_process_list\` with a ` +
+                        `name filter to confirm, or pass an absolute path.`,
+                };
+            }
+            // Extract PID — both bare `PID=12345` and the verified
+            // `PID=12345 (verified via Get-Process)` shapes parse the same.
             const pidMatch = out.match(/PID=(\d+)/);
             const pid = pidMatch ? Number(pidMatch[1]) : null;
-            return { success: true, app, pid, raw: out };
+            const verified = /verified via Get-Process/.test(out);
+            if (pid === null) {
+                // Shouldn't happen — the PS script always emits one of the
+                // three outcome lines. Surface honestly so the model sees the
+                // unexpected stdout instead of pretending success.
+                return {
+                    success: false,
+                    app,
+                    raw: out,
+                    error: `Launch returned unexpected stdout (no PID / failure sentinel). ` +
+                        `Output: ${out.slice(0, 200)}`,
+                };
+            }
+            // Verified launch — still degraded because the app may crash
+            // post-init or split into a different process tree (Chrome's
+            // multi-process model, Spotify's spawn-and-detach). The honest
+            // signal is "we have a PID we can hand off; verify via
+            // os_process_list before relying on it".
+            return {
+                success: true,
+                app,
+                pid,
+                verified,
+                raw: out,
+                degraded: true,
+                degradedReason: verified
+                    ? `launched (PID ${pid}, verified via Get-Process); call os_process_list to confirm it's still alive`
+                    : `launched (PID ${pid}); call os_process_list to confirm it's still alive`,
+            };
         }
         catch (e) {
             return {

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

@@ -30,7 +30,13 @@ const ACTION_KEYS = {
 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.',
+        description: 'FALLBACK ONLY — prefer `media_transport(action, target)` for verified ' +
+            'control of named apps (Spotify, YouTube, etc.). Use `media_key` only ' +
+            'when (1) the target app is unknown / not registered with the OS media ' +
+            'bus, or (2) `media_transport` returned `NoSession`. Blind global ' +
+            'keystroke (VK_MEDIA_PLAY_PAUSE and friends) — Windows doesn\'t surface ' +
+            'routing outcome, so this tool always reports `degraded:true`. Pair ' +
+            'with `now_playing` to inspect state first. Windows-only.',
         inputSchema: {
             type: 'object',
             properties: {
@@ -48,8 +54,20 @@ exports.mediaKeyTool = {
     mutates: true,
     toolset: 'system',
     async execute(args, _ctx) {
-        if (!(0, _psHelpers_1.isWindows)())
-            return (0, _psHelpers_1.windowsOnlyError)('media_key');
+        if (!(0, _psHelpers_1.isWindows)()) {
+            return (0, _psHelpers_1.windowsOnlyError)('media_key', {
+                canStill: [
+                    '`shell_exec` with `xdotool key XF86AudioPlay` on Linux X11',
+                    '`shell_exec` with `osascript -e \'tell application "Spotify" to playpause\'` on macOS',
+                    'Use `media_transport` if a layer-1 skill (Spotify Web API) is installed',
+                ],
+                cannotReliably: [
+                    'Blind global VK_MEDIA_PLAY_PAUSE keystroke via SendKeys',
+                ],
+                fix: 'Run Aiden on Windows for direct media-key emission, or use the ' +
+                    'platform-native helpers above via `shell_exec`.',
+            });
+        }
         const action = args.action;
         if (!ACTION_KEYS[action]) {
             return {
@@ -66,7 +84,20 @@ exports.mediaKeyTool = {
         ].join(' ');
         try {
             await (0, _psHelpers_1.runPowerShell)(script, { timeoutMs: 5000 });
-            return { success: true, action };
+            // v4.1.3-repl-polish: SendKeys returns 0 whether or not any
+            // media-aware app received the keystroke — Windows doesn't
+            // surface the SMTC routing outcome to user-mode. We could
+            // scan `osProcessListImpl` for known media apps, but that's
+            // a cross-tool dep that distorts mediaKey's surface area. The
+            // honest answer is "we don't know if it landed"; the trail
+            // row renders yellow to signal that to the user without
+            // affecting the model's read of the result.
+            return {
+                success: true,
+                action,
+                degraded: true,
+                degradedReason: 'media key sent; cannot verify any app received it',
+            };
         }
         catch (e) {
             return {

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

@@ -0,0 +1,163 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/mediaSessions.ts — `media_sessions` tool. v4.1.4-media.
+ *
+ * Enumerate every Windows GSMTC (GlobalSystemMediaTransportControls) media
+ * session — one entry per app that has registered with the OS media bus
+ * (Spotify, YouTube in browser, Windows Media Player, Apple Music for
+ * Windows, VLC with the SMTC plugin, etc.).
+ *
+ * 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 reads, mediaTransport writes
+ *   3. Global media keys (mediaKey tool)      — blind fallback
+ *
+ * Pairs with `media_transport` (write tool) — the model calls
+ * `media_sessions` to see what's available, then `media_transport`
+ * with a target string ("spotify", "chrome", etc.) to act. Distinct
+ * from `now_playing` which only returns the SINGLE active session.
+ *
+ * Read-only. Windows-only in v4.1.4 (consistent with the rest of the
+ * computer-control family).
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.__friendlyAppName = exports.mediaSessionsTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+/** Map a Windows AppUserModelId to a friendly display name. Mirror of
+ *  the normalization in core/tools/nowPlaying.ts; kept in sync so the
+ *  two tools talk about the same app the same way. */
+function friendlyAppName(aumid) {
+    if (!aumid)
+        return 'unknown';
+    const id = aumid.toLowerCase();
+    if (id.includes('spotify'))
+        return 'Spotify';
+    if (id.includes('msedge'))
+        return 'Microsoft Edge';
+    if (id.includes('chrome'))
+        return 'Google Chrome';
+    if (id.includes('firefox'))
+        return 'Firefox';
+    if (id.includes('vlc'))
+        return 'VLC';
+    if (id.includes('groove'))
+        return 'Groove Music';
+    if (id.includes('mediaplay'))
+        return 'Windows Media Player';
+    if (id.includes('apple'))
+        return 'Apple Music';
+    return aumid;
+}
+/**
+ * Build the PowerShell snippet. Enumerates every session via
+ * `GetSessions()`, marks the current one (the OS-routed-keypress
+ * target), and returns a JSON array. Each session's media properties
+ * are awaited individually — TryGetMediaPropertiesAsync can return
+ * null on transient state (track-skip mid-call) which we surface as
+ * empty fields rather than failing the whole enumeration.
+ */
+function buildPs() {
+    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
+$current = $mgr.GetCurrentSession()
+$currentId = if ($current) { $current.SourceAppUserModelId } else { '' }
+$sessions = $mgr.GetSessions()
+$out = @()
+foreach ($s in $sessions) {
+    $p = $null
+    try { $p = Await ($s.TryGetMediaPropertiesAsync()) $pType } catch { $p = $null }
+    $pb = $s.GetPlaybackInfo()
+    $row = @{
+        appUserModelId = $s.SourceAppUserModelId
+        isCurrent      = ($s.SourceAppUserModelId -eq $currentId)
+        playbackStatus = $pb.PlaybackStatus.ToString()
+        title          = if ($p) { $p.Title }      else { $null }
+        artist         = if ($p) { $p.Artist }     else { $null }
+        album          = if ($p) { $p.AlbumTitle } else { $null }
+    }
+    $out += $row
+}
+if ($out.Count -eq 0) {
+    '[]'
+} else {
+    $out | ConvertTo-Json -Compress -Depth 3
+}
+`.trim();
+}
+exports.mediaSessionsTool = {
+    schema: {
+        name: 'media_sessions',
+        description: 'List active Windows MEDIA PLAYBACK sessions (audio/video apps — ' +
+            'Spotify, YouTube in browser, VLC, etc.). NOT for past conversation ' +
+            'history — call `session_search` for chat-message search or ' +
+            '`recall_session` for past-session topic recall. One entry per app, ' +
+            'including which one is the OS-routed target for global media keys. ' +
+            'Use this BEFORE `media_transport` when you need to pick a specific ' +
+            'app rather than blindly toggling the current session. Distinct from ' +
+            '`now_playing` which returns only the single current session. ' +
+            'Windows-only in v4.1.4.',
+        inputSchema: {
+            type: 'object',
+            properties: {},
+        },
+    },
+    category: 'read',
+    mutates: false,
+    toolset: 'system',
+    async execute(_args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)()) {
+            return (0, _psHelpers_1.windowsOnlyError)('media_sessions', {
+                canStill: [
+                    'Call `now_playing` if a Spotify Web API skill exposes that surface',
+                    'Use `os_process_list` with a media-app filter (spotify, vlc, chrome) for coarse presence detection',
+                    '`shell_exec` with `playerctl --list-all` on Linux to enumerate MPRIS clients',
+                ],
+                cannotReliably: [
+                    'OS-level enumeration of every media-bus-registered app',
+                    'Distinguishing the OS-routed "current" session from inactive ones',
+                ],
+                fix: 'Run Aiden on Windows for GSMTC enumeration, or wrap your platform\'s ' +
+                    'native media-control bus (MPRIS / NowPlaying) in a skill.',
+            });
+        }
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(), { timeoutMs: 8000 });
+            const trimmed = stdout.trim();
+            if (trimmed.length === 0 || trimmed === '[]') {
+                return { success: true, sessions: [], count: 0 };
+            }
+            const parsed = JSON.parse(trimmed);
+            // ConvertTo-Json emits an object (single result) or array (multiple).
+            // Normalise to array, then attach friendlyApp.
+            const rows = Array.isArray(parsed) ? parsed : [parsed];
+            const sessions = rows.map((row) => ({
+                appUserModelId: String(row.appUserModelId ?? ''),
+                friendlyApp: friendlyAppName(row.appUserModelId),
+                isCurrent: row.isCurrent === true,
+                playbackStatus: String(row.playbackStatus ?? 'Unknown'),
+                title: typeof row.title === 'string' ? row.title : undefined,
+                artist: typeof row.artist === 'string' ? row.artist : undefined,
+                album: typeof row.album === 'string' ? row.album : undefined,
+            }));
+            return { success: true, sessions, count: sessions.length };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};
+// Re-export the friendly-app mapper so mediaTransport can use the same
+// normalization for target-string matching.
+exports.__friendlyAppName = friendlyAppName;