aiden-runtime 4.1.0 → 4.1.2

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

@@ -0,0 +1,106 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/screenshot.ts — `screenshot` tool.
+ *
+ * Captures the full desktop and writes it as a PNG to
+ * `<aidenHome>/screenshots/<timestamp>.png`. Returns the absolute path
+ * in `path` so a Telegram / Discord channel adapter can attach the
+ * file directly without a separate file_read round-trip.
+ *
+ * Privacy note (Phase v4.1.2-followup-3): this tool reads what is
+ * currently visible on the screen — anything in front of the user.
+ * The tool description says so explicitly so users know what they're
+ * approving when the model invokes it.
+ *
+ * Implementation: PowerShell-only, no native dependency. Uses
+ * `System.Windows.Forms.Screen` + `System.Drawing.Bitmap` /
+ * `Graphics.CopyFromScreen()` — both ship with .NET on every modern
+ * Windows install. Cross-platform fallback returns a structured error.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenshotTool = void 0;
+const node_fs_1 = require("node:fs");
+const node_path_1 = __importDefault(require("node:path"));
+const _psHelpers_1 = require("./_psHelpers");
+/**
+ * Build the PowerShell capture script. The bitmap dimensions come from
+ * `Screen::PrimaryScreen.Bounds` so we get the actual primary-monitor
+ * resolution, not a hardcoded value. SaveAs PNG to keep losslessness
+ * — file size on a 4K screen is ~4-8 MB which is fine for chat.
+ */
+function buildScreenshotPs(outPath) {
+    const psQuoted = outPath.replace(/'/g, "''"); // PowerShell single-quote escape
+    return [
+        'Add-Type -AssemblyName System.Windows.Forms;',
+        'Add-Type -AssemblyName System.Drawing;',
+        '$bounds = [System.Windows.Forms.Screen]::PrimaryScreen.Bounds;',
+        '$bitmap = New-Object System.Drawing.Bitmap $bounds.Width, $bounds.Height;',
+        '$gfx = [System.Drawing.Graphics]::FromImage($bitmap);',
+        '$gfx.CopyFromScreen($bounds.Location, [System.Drawing.Point]::Empty, $bounds.Size);',
+        `$bitmap.Save('${psQuoted}', [System.Drawing.Imaging.ImageFormat]::Png);`,
+        '$gfx.Dispose(); $bitmap.Dispose();',
+        `Write-Output '${psQuoted}';`,
+    ].join(' ');
+}
+exports.screenshotTool = {
+    schema: {
+        name: 'screenshot',
+        description: 'Capture the current primary-monitor desktop as a PNG. Returns the absolute path of the saved file. Reads whatever is currently visible on screen — privacy-sensitive; only invoke when the user explicitly asks for a screenshot or screen share. 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)('screenshot');
+        if (!ctx.paths) {
+            return { success: false, error: 'aiden paths not wired (test mode?)' };
+        }
+        try {
+            const dir = node_path_1.default.join(ctx.paths.root, 'screenshots');
+            await node_fs_1.promises.mkdir(dir, { recursive: true });
+            const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+            const outPath = node_path_1.default.join(dir, `${stamp}.png`);
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildScreenshotPs(outPath), {
+                timeoutMs: 30000,
+            });
+            // Verify the file actually landed on disk — PowerShell can exit 0
+            // and have written nothing on an exotic display configuration.
+            try {
+                const stat = await node_fs_1.promises.stat(outPath);
+                return {
+                    success: true,
+                    path: outPath,
+                    size: stat.size,
+                    // For Telegram / Discord adapters — they can attach via path.
+                    attachAs: 'image/png',
+                };
+            }
+            catch {
+                return {
+                    success: false,
+                    error: `screenshot script ran but file not found at ${outPath} (stdout=${stdout.trim().slice(0, 120)})`,
+                };
+            }
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

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

@@ -0,0 +1,157 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/volumeSet.ts — `volume_set` tool.
+ *
+ * Set the Windows master-volume level to a percentage (0-100), or
+ * toggle mute. Uses the Shell.Application COM object's appCommand
+ * SendKeys for up/down nudges; for absolute level setting, talks to
+ * `IAudioEndpointVolume` via PowerShell inline C# (Add-Type) — no
+ * external binary (no nircmd, no soundvolumeview).
+ *
+ * The inline-C# approach is well-trodden Windows lore: the
+ * IAudioEndpointVolume COM interface is part of the Core Audio APIs
+ * available since Vista. We declare the interop types in PowerShell,
+ * invoke `SetMasterVolumeLevelScalar`, and clean up. Adds ~1-2s
+ * cold-start (PowerShell Add-Type compilation) — fine for an
+ * occasionally-invoked control.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.volumeSetTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+const ADD_TYPE_AUDIO = `
+Add-Type -TypeDefinition @'
+using System;
+using System.Runtime.InteropServices;
+[Guid("5CDF2C82-841E-4546-9722-0CF74078229A"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+interface IAudioEndpointVolume {
+  int RegisterControlChangeNotify(IntPtr cb);
+  int UnregisterControlChangeNotify(IntPtr cb);
+  int GetChannelCount(out uint count);
+  int SetMasterVolumeLevel(float level, Guid ctx);
+  int SetMasterVolumeLevelScalar(float level, Guid ctx);
+  int GetMasterVolumeLevel(out float level);
+  int GetMasterVolumeLevelScalar(out float level);
+  int SetChannelVolumeLevel(uint ch, float level, Guid ctx);
+  int SetChannelVolumeLevelScalar(uint ch, float level, Guid ctx);
+  int GetChannelVolumeLevel(uint ch, out float level);
+  int GetChannelVolumeLevelScalar(uint ch, out float level);
+  int SetMute(bool mute, Guid ctx);
+  int GetMute(out bool mute);
+  int GetVolumeStepInfo(out uint step, out uint count);
+  int VolumeStepUp(Guid ctx);
+  int VolumeStepDown(Guid ctx);
+  int QueryHardwareSupport(out uint mask);
+  int GetVolumeRange(out float min, out float max, out float inc);
+}
+[Guid("A95664D2-9614-4F35-A746-DE8DB63617E6"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+interface IMMDeviceEnumerator {
+  int NotImpl0();
+  int GetDefaultAudioEndpoint(int dataFlow, int role, out IMMDevice ep);
+}
+[Guid("D666063F-1587-4E43-81F1-B948E807363F"), InterfaceType(ComInterfaceType.InterfaceIsIUnknown)]
+interface IMMDevice {
+  int Activate(ref Guid id, int clsCtx, IntPtr pa, [MarshalAs(UnmanagedType.IUnknown)] out object o);
+}
+[ComImport, Guid("BCDE0395-E52F-467C-8E3D-C4579291692E")]
+class MMDeviceEnumeratorComObject { }
+public static class Audio {
+  static IAudioEndpointVolume Vol() {
+    var enumerator = new MMDeviceEnumeratorComObject() as IMMDeviceEnumerator;
+    IMMDevice dev = null;
+    Marshal.ThrowExceptionForHR(enumerator.GetDefaultAudioEndpoint(0, 1, out dev));
+    Guid epvid = typeof(IAudioEndpointVolume).GUID;
+    object o;
+    Marshal.ThrowExceptionForHR(dev.Activate(ref epvid, 7, IntPtr.Zero, out o));
+    return o as IAudioEndpointVolume;
+  }
+  public static float GetLevel() { float l; Marshal.ThrowExceptionForHR(Vol().GetMasterVolumeLevelScalar(out l)); return l; }
+  public static void SetLevel(float level) { Marshal.ThrowExceptionForHR(Vol().SetMasterVolumeLevelScalar(level, Guid.Empty)); }
+  public static bool GetMute() { bool m; Marshal.ThrowExceptionForHR(Vol().GetMute(out m)); return m; }
+  public static void SetMute(bool mute) { Marshal.ThrowExceptionForHR(Vol().SetMute(mute, Guid.Empty)); }
+}
+'@;
+`;
+function buildPs(action, percent) {
+    if (action === 'set' && typeof percent === 'number') {
+        const scalar = (Math.max(0, Math.min(100, percent)) / 100).toFixed(4);
+        return [
+            ADD_TYPE_AUDIO,
+            `[Audio]::SetLevel([float]${scalar});`,
+            `$level = [Audio]::GetLevel();`,
+            `Write-Output ([math]::Round($level * 100, 0));`,
+        ].join('\n');
+    }
+    if (action === 'mute') {
+        return [ADD_TYPE_AUDIO, `[Audio]::SetMute($true); Write-Output 'muted';`].join('\n');
+    }
+    if (action === 'unmute') {
+        return [ADD_TYPE_AUDIO, `[Audio]::SetMute($false); Write-Output 'unmuted';`].join('\n');
+    }
+    // toggle_mute
+    return [
+        ADD_TYPE_AUDIO,
+        `$cur = [Audio]::GetMute(); [Audio]::SetMute(-not $cur);`,
+        `Write-Output (if (-not $cur) {'muted'} else {'unmuted'});`,
+    ].join('\n');
+}
+exports.volumeSetTool = {
+    schema: {
+        name: 'volume_set',
+        description: 'Set Windows master volume to a percentage (0-100), or mute / unmute / toggle mute. Operates on the default audio endpoint. Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                action: {
+                    type: 'string',
+                    enum: ['set', 'mute', 'unmute', 'toggle_mute'],
+                    description: "'set' requires `percent`. 'mute' / 'unmute' force the state. 'toggle_mute' flips it.",
+                },
+                percent: {
+                    type: 'number',
+                    description: 'Target volume 0-100 (only used when action="set"). Values outside the range are clamped.',
+                },
+            },
+            required: ['action'],
+        },
+    },
+    category: 'execute',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('volume_set');
+        const action = args.action;
+        if (!['set', 'mute', 'unmute', 'toggle_mute'].includes(action)) {
+            return {
+                success: false,
+                error: `Unknown volume action: ${String(args.action)}. ` +
+                    `Valid: set, mute, unmute, toggle_mute`,
+            };
+        }
+        const percent = typeof args.percent === 'number' ? args.percent : undefined;
+        if (action === 'set' && percent === undefined) {
+            return {
+                success: false,
+                error: "action='set' requires a numeric `percent` (0-100).",
+            };
+        }
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(action, percent), {
+                timeoutMs: 10000,
+            });
+            return { success: true, action, result: stdout.trim() };
+        }
+        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.0",
+  "version": "4.1.2",
   "publishConfig": {
     "access": "public"
   },
@@ -77,6 +77,9 @@
     "dist:linux": "node scripts/prepare-electron.js && electron-builder --linux --x64 --publish never && node -e \"const fs=require('fs');const p=JSON.parse(fs.readFileSync('package.json','utf8'));p.main='./dist/index.js';fs.writeFileSync('package.json',JSON.stringify(p,null,2)+'\\n');console.log('  main restored')\"",
     "test": "vitest run",
     "test:ui": "vitest --ui",
+    "eval": "ts-node evals/cli.ts",
+    "eval:honesty": "ts-node evals/cli.ts --suite honesty",
+    "eval:scenario": "ts-node evals/cli.ts --scenario",
     "stress-test": "npx ts-node tests/stressTest.ts",
     "test:all": "npx ts-node tests/e2e/masterTestSuite.ts",
     "test:unit": "npx ts-node tests/e2e/masterTestSuite.ts --part1",

package/skills/system_control.md

@@ -1,69 +1,135 @@
----
-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_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.
+```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" } }
+```
+
+### 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 workflow:**
+1. `now_playing` → see what's currently playing
+2. `media_key` → control it (play_pause / next / previous / stop)
+
+**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.