aiden-runtime 4.1.1 → 4.1.3

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

@@ -0,0 +1,218 @@
+"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;
+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;`,
+        `  if ($p -and $p.Id) { $pid_out = $p.Id }`,
+        `} catch {`,
+        `  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(' ');
+}
+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();
+            // 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;
+            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 {
+                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,109 @@
+"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: '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: {
+                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', {
+                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 {
+                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 });
+            // 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 {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

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;