aiden-runtime 4.1.1 → 4.1.3

package/skills/system_control.md

@@ -1,69 +1,185 @@
----
-name: system_control
-description: Windows desktop control — clipboard, windows, running applications
-version: 1.0.0
----
-
-# Skill: System Control
-
-Use these tools to interact with the Windows desktop environment — clipboard, open windows, and running applications.
-
-## Tools
-
-### clipboard_read
-Read the current contents of the Windows clipboard.
-```json
-{ "tool": "clipboard_read", "input": {} }
-```
-
-### clipboard_write
-Write text to the Windows clipboard.
-```json
-{ "tool": "clipboard_write", "input": { "text": "Hello, world!" } }
-```
-
-### window_list
-List all visible windows currently open on the desktop, with their process IDs, process names, and window titles.
-```json
-{ "tool": "window_list", "input": {} }
-```
-
-### window_focus
-Bring a specific window to the foreground by its title (or partial title).
-```json
-{ "tool": "window_focus", "input": { "title": "Notepad" } }
-```
-
-### app_launch
-Launch an application by executable name or full path.
-```json
-{ "tool": "app_launch", "input": { "app": "notepad.exe" } }
-{ "tool": "app_launch", "input": { "app": "C:\\Program Files\\App\\app.exe" } }
-```
-
-### app_close
-Close a running process by its process name (without .exe extension is also accepted).
-```json
-{ "tool": "app_close", "input": { "app": "notepad" } }
-```
-
-## Usage Patterns
-
-**Copy result to clipboard after creating a file:**
-1. `file_write` → write the content
-2. `clipboard_write` → copy the file path or content to clipboard
-
-**Open an app and confirm it's running:**
-1. `app_launch` → launch the app
-2. `window_list` → verify window appears
-
-**Switch focus during automation:**
-1. `window_list` → find the correct window title
-2. `window_focus` → bring it forward
-3. `keyboard_type` → type into it
-
-## Notes
-- `app_close` uses `Stop-Process -Force`; the process terminates immediately without a save prompt.
-- `window_focus` uses `Microsoft.VisualBasic.Interaction.AppActivate`; partial title matches work.
-- All tools are Windows-only (PowerShell-backed).
-- `app_launch` is gated by CommandGate — dangerous executables are blocked automatically.
+---
+name: system_control
+description: Windows desktop control — clipboard, screenshots, media, volume, apps
+version: 2.0.0
+---
+
+# Skill: System Control
+
+Interact with the Windows desktop: clipboard, screenshots, media playback,
+volume, app launch/close, OS-wide process listing. All eight verbs below
+are real registered tools — call them directly. The two verbs in the
+"Not a tool yet" section route through `shell_exec` with the PowerShell
+snippet shown.
+
+Windows-only in v4.1.2. macOS/Linux callers get a structured error
+pointing at the issue tracker; route to the user's clarifying-question
+path if they need cross-platform coverage.
+
+## Read-only verbs
+
+### clipboard_read
+Read the current clipboard contents as text. Empty string for non-text
+clipboard data (image, RTF, file list). Privacy-sensitive — the
+clipboard often holds passwords, OTPs, or personal text. Only call when
+the user has clearly asked.
+```json
+{ "tool": "clipboard_read", "input": {} }
+```
+
+### screenshot
+Capture the primary monitor as a PNG. Saves to
+`<aidenHome>/screenshots/<timestamp>.png` and returns the absolute path.
+Telegram / Discord channel adapters can attach the file directly via
+the returned path. Privacy-sensitive — captures everything visible.
+```json
+{ "tool": "screenshot", "input": {} }
+```
+
+### os_process_list
+List OS-wide running processes (top by CPU). Use this to answer
+"is X running?" or "what's hogging my CPU?". Distinct from `process_list`
+which only shows processes Aiden itself spawned via `process_spawn`.
+```json
+{ "tool": "os_process_list", "input": { "name": "claude" } }
+{ "tool": "os_process_list", "input": { "limit": 50 } }
+```
+
+## Mutating verbs (approval-gated)
+
+### clipboard_write
+Replace the clipboard with new text. Handles multi-line strings safely
+(text routed via stdin to PowerShell, no shell-quoting issues).
+```json
+{ "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
+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" } }
+{ "tool": "media_key", "input": { "action": "previous" } }
+{ "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
+{ "tool": "volume_set", "input": { "action": "set", "percent": 30 } }
+{ "tool": "volume_set", "input": { "action": "mute" } }
+{ "tool": "volume_set", "input": { "action": "toggle_mute" } }
+```
+
+### app_launch
+Launch a Windows application by exe name, friendly name (resolved via
+App Paths registry), or absolute path. Returns the PID when available.
+```json
+{ "tool": "app_launch", "input": { "app": "spotify" } }
+{ "tool": "app_launch", "input": { "app": "notepad", "args": ["C:\\temp\\note.txt"] } }
+{ "tool": "app_launch", "input": { "app": "C:\\Program Files\\App\\app.exe" } }
+```
+
+### app_close
+Close one or more processes by name (with or without the `.exe`
+suffix). Matches all running instances. Set `force: true` to skip the
+app's graceful-shutdown prompt.
+```json
+{ "tool": "app_close", "input": { "app": "notepad" } }
+{ "tool": "app_close", "input": { "app": "chrome.exe", "force": true } }
+```
+
+## Not a tool yet — route via `shell_exec`
+
+### Focus a window by title
+v4.1.2 does not ship a `window_focus` tool — Win32 P/Invoke complexity
+isn't worth a dedicated tool when shell_exec covers the same ground.
+```powershell
+(New-Object -ComObject WScript.Shell).AppActivate('Notepad')
+```
+
+### List visible windows
+Same reasoning. The MainWindowTitle filter excludes background services.
+```powershell
+Get-Process | Where-Object { $_.MainWindowTitle } |
+  Select-Object Id, ProcessName, MainWindowTitle |
+  ConvertTo-Json -Compress
+```
+
+Wrap either snippet in `shell_exec` when the user explicitly asks for
+window manipulation. Track v4.1.3+ for native tool wrappers if these
+turn into common requests.
+
+## Usage Patterns
+
+**Copy file content to clipboard after writing it:**
+1. `file_write` → write the content
+2. `clipboard_write` → copy the file path or content
+
+**Confirm an app launched:**
+1. `app_launch` → returns PID
+2. `os_process_list` with the app's name → verify it's still running
+
+**"Is X running?" workflow:**
+1. `os_process_list` with `name: "<substring>"` → returns matching processes
+2. If `count === 0` → tell the user honestly, suggest `app_launch`
+
+## 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`
+2. Surface it to the user so they know the change landed.