aiden-runtime 4.1.2 → 4.1.4

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.4",
   "publishConfig": {
     "access": "public"
   },
@@ -277,6 +277,7 @@
     "twilio": "^5.13.1",
     "uuid": "^9.0.0",
     "whatsapp-web.js": "^1.26.0",
+    "wrap-ansi": "^9.0.2",
     "ws": "^8.20.0"
   },
   "optionalDependencies": {

package/skills/system_control.md

@@ -54,10 +54,34 @@ Replace the clipboard with new text. Handles multi-line strings safely
 { "tool": "clipboard_write", "input": { "text": "Hello, world!" } }
 ```
 
+### media_sessions
+Enumerate every Windows media session registered with the OS (Spotify,
+YouTube in browser, VLC, etc.). One entry per app, with which one is
+the OS-routed target for global media keys. Use this BEFORE
+`media_transport` when controlling a specific app.
+```json
+{ "tool": "media_sessions", "input": {} }
+```
+
+### media_transport
+Verified play / pause / skip against a specific GSMTC media session.
+Targets by `AppUserModelId` substring (case-insensitive — "spotify"
+matches `Spotify.exe`), then by track title as a softer fallback. Omit
+`target` to act on the OS-routed current session. Returns OS-level
+success/failure — NOT a blind keystroke like `media_key`.
+```json
+{ "tool": "media_transport", "input": { "action": "pause", "target": "spotify" } }
+{ "tool": "media_transport", "input": { "action": "play",  "target": "spotify" } }
+{ "tool": "media_transport", "input": { "action": "next",  "target": "youtube" } }
+{ "tool": "media_transport", "input": { "action": "toggle" } }
+```
+
 ### media_key
-Send a media-control key to the active media session (Spotify, YouTube
-in browser, Windows Media Player, etc.). Pair with `now_playing` to
-inspect state first.
+Blind global media keypress (`VK_MEDIA_PLAY_PAUSE` and friends). Layer-3
+fallback for the rare case where neither a semantic API nor GSMTC can
+act. Prefer `media_transport` whenever the user names an app — this
+tool returns `degraded:true` because Windows doesn't surface the SMTC
+routing outcome to user-mode, so we can't verify any app received it.
 ```json
 { "tool": "media_key", "input": { "action": "play_pause" } }
 { "tool": "media_key", "input": { "action": "next" } }
@@ -65,6 +89,17 @@ inspect state first.
 { "tool": "media_key", "input": { "action": "stop" } }
 ```
 
+### app_input
+Focus a Windows application by process name and send a SendKeys
+sequence to it. Escape hatch when GSMTC doesn't enumerate the surface
+("press space in Chrome to pause this YouTube tab"). Always returns
+`degraded:true` — SendKeys cannot verify receipt at the target window.
+```json
+{ "tool": "app_input", "input": { "app": "chrome", "keys": "{SPACE}" } }
+{ "tool": "app_input", "input": { "app": "notepad", "keys": "Hello{ENTER}" } }
+{ "tool": "app_input", "input": { "app": "Spotify", "keys": "^{RIGHT}" } }
+```
+
 ### volume_set
 Set Windows master volume to a percentage, or mute / unmute / toggle.
 ```json
@@ -126,9 +161,24 @@ turn into common requests.
 1. `os_process_list` with `name: "<substring>"` → returns matching processes
 2. If `count === 0` → tell the user honestly, suggest `app_launch`
 
-**Media control workflow:**
-1. `now_playing` → see what's currently playing
-2. `media_key` → control it (play_pause / next / previous / stop)
+## Media control — strict order
+
+1. If the user names an app ("Spotify", "YouTube", "VLC") — ALWAYS try
+   `media_transport({action, target})` first. Verified, OS-confirmed.
+2. If `media_transport` returns `NoSession` OR the user didn't name an app
+   — fall back to `media_key({action})`. Blind global keystroke, returns
+   `degraded:true` because Windows can't tell us if anything received it.
+3. If GSMTC doesn't enumerate the surface at all (e.g. a YouTube tab the
+   browser hasn't registered with SMTC) — last resort: `app_input({app,
+   keys})` to focus the window and send a keystroke directly.
+
+Never call `media_key` and `media_transport` in the same turn — redundant.
+First call gives you the answer; second is noise the user has to read.
+
+Honesty contract:
+- `media_transport` success is OS-confirmed → trail row is silent (success).
+- `media_key` and `app_input` always report `degraded:true` → yellow trail
+  row, because neither can verify receipt at the target app.
 
 **Volume change with feedback:**
 1. `volume_set` → returns the resulting volume percent in `result`