aiden-runtime 4.1.2 → 4.1.3

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;

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aiden-runtime",
-  "version": "4.1.2",
+  "version": "4.1.3",
   "publishConfig": {
     "access": "public"
   },