aiden-runtime 4.1.0 → 4.1.2

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

@@ -0,0 +1,162 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/aidenSelfUpdate.ts — Phase v4.1.2-update.
+ *
+ * Natural-language entry point for self-update. When the user asks
+ * Aiden to update / install latest / upgrade itself, the model calls
+ * this tool. Routes to the same shared executor (`executeInstall`)
+ * that `/update install` uses — single source of truth for install
+ * behavior.
+ *
+ * Two-step confirmation contract (consent gate):
+ *   1. First call with `confirm: false` — returns status + a prompt
+ *      asking the user to confirm. NEVER spawns.
+ *   2. Model surfaces the prompt to the user; waits for explicit
+ *      agreement ("yes update", "go ahead", "do it").
+ *   3. Second call with `confirm: true` — only after explicit user
+ *      agreement; spawns the install.
+ *
+ * The contract is enforced via tool DESCRIPTION (model-facing rule).
+ * Tool-side, we don't track "did the user actually consent" — that
+ * needs a runtime approval object (request_id + fresh-confirmation
+ * verification) which is a v4.2+ design. For v4.1.2 the description
+ * carries the rule and the tool trusts the model to follow it.
+ *
+ * Acceptable risk: failure mode of a misbehaving model is "user gets
+ * an unwanted install they have to /quit to apply" — not data loss.
+ * Phase D's promotion path is the more sensitive consent surface and
+ * is user-driven UI.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.aidenSelfUpdateTool = void 0;
+const version_1 = require("../../../core/version");
+const checkUpdate_1 = require("../../../core/v4/update/checkUpdate");
+const executeInstall_1 = require("../../../core/v4/update/executeInstall");
+exports.aidenSelfUpdateTool = {
+    schema: {
+        name: 'aiden_self_update',
+        description: 'Update Aiden to the latest version via npm install -g aiden-runtime@latest. ' +
+            'TWO-STEP CONFIRMATION REQUIRED: first call with confirm:false to check status ' +
+            'and surface to the user; only call with confirm:true AFTER the user explicitly ' +
+            'agrees in their next message ("yes update", "go ahead", "do it"). NEVER call ' +
+            'with confirm:true autonomously. ' +
+            'Call this tool ONLY when the user explicitly asks Aiden to update / install ' +
+            'latest / upgrade itself. Example user phrases that warrant a call: ' +
+            '"update yourself", "can you install the latest version?", "upgrade to the latest", ' +
+            '"self-update". DO NOT call when: user asks about update status without requesting ' +
+            'action ("are there updates?") — for status queries, just answer from your context; ' +
+            'user mentions updates of OTHER software ("update VSCode"); user has not explicitly ' +
+            'asked Aiden to update itself.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                confirm: {
+                    type: 'boolean',
+                    description: 'False on first call (status check, no install). True on second call AFTER ' +
+                        'the user explicitly agreed to proceed in their last message.',
+                },
+            },
+            required: ['confirm'],
+        },
+    },
+    category: 'write',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, ctx) {
+        if (!ctx.paths) {
+            return {
+                success: false,
+                error: 'aiden_self_update needs Aiden user-data paths — not configured in this context.',
+            };
+        }
+        const confirm = args.confirm === true;
+        // Status probe — bypass the 6h boot cache for user-initiated checks.
+        const status = await (0, checkUpdate_1.checkForUpdate)({
+            paths: ctx.paths,
+            installedVersion: version_1.VERSION,
+            cacheTtlMs: 0,
+        });
+        // ── First call: confirm:false → status + prompt. NEVER spawn. ─────
+        if (!confirm) {
+            if (status.latest === null) {
+                return {
+                    success: true,
+                    stage: 'status',
+                    message: "Couldn't check for updates (registry unreachable). " +
+                        'Try again in a moment, or run `npm install -g aiden-runtime@latest` manually.',
+                    installed: status.installed,
+                    latest: null,
+                    updateAvailable: false,
+                };
+            }
+            if (!status.updateAvailable) {
+                return {
+                    success: true,
+                    stage: 'status',
+                    message: `You're on the latest version (v${status.installed}). Nothing to update.`,
+                    installed: status.installed,
+                    latest: status.latest,
+                    updateAvailable: false,
+                };
+            }
+            return {
+                success: true,
+                stage: 'status',
+                message: `Update available: v${status.installed} → v${status.latest}. ` +
+                    `Confirm by saying "yes update" or "go ahead". This runs ` +
+                    `\`npm install -g aiden-runtime@latest\` and you'll need to ` +
+                    `restart Aiden after.`,
+                installed: status.installed,
+                latest: status.latest,
+                updateAvailable: true,
+            };
+        }
+        // ── Second call: confirm:true → install. ────────────────────────
+        if (status.latest === null) {
+            return {
+                success: false,
+                stage: 'install',
+                error: "Can't install — registry unreachable. " +
+                    'Try again or run `npm install -g aiden-runtime@latest` manually.',
+                installed: status.installed,
+            };
+        }
+        if (!status.updateAvailable) {
+            return {
+                success: true,
+                stage: 'install',
+                message: `Already on v${status.installed}. Nothing to install.`,
+                installed: status.installed,
+                latest: status.latest,
+                updateAvailable: false,
+            };
+        }
+        const result = await (0, executeInstall_1.executeInstall)();
+        if (result.success) {
+            const v = result.installedVersion ?? status.latest;
+            return {
+                success: true,
+                stage: 'install',
+                message: `✓ aiden-runtime v${v} installed. Restart Aiden to apply: ` +
+                    `type /quit then re-run \`aiden\`.`,
+                installed: status.installed,
+                installedVersion: v,
+            };
+        }
+        return {
+            success: false,
+            stage: 'install',
+            error: result.error ?? 'Install failed (no error message).',
+            installed: status.installed,
+            latestSeen: status.latest,
+            // Keep stdout/stderr off the model-visible response to avoid
+            // prompt bloat; user-actionable copy-paste is already in error.
+        };
+    },
+};

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

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/appClose.ts — `app_close` tool.
+ *
+ * Close one or more Windows processes by process name. Accepts the
+ * bare name without `.exe` (matches `Stop-Process -Name` semantics).
+ * Returns the count of processes successfully terminated.
+ *
+ * The .exe stripper handles user input like "close notepad.exe" /
+ * "close notepad" identically — both resolve to the same call.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appCloseTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+function normalise(name) {
+    return name.trim().replace(/\.exe$/i, '');
+}
+function buildPs(processName, force) {
+    const safe = processName.replace(/'/g, "''");
+    const forceFlag = force ? '-Force' : '';
+    return [
+        `$procs = Get-Process -Name '${safe}' -ErrorAction SilentlyContinue;`,
+        `$count = ($procs | Measure-Object).Count;`,
+        `if ($count -gt 0) { $procs | Stop-Process ${forceFlag} -ErrorAction SilentlyContinue; }`,
+        `Write-Output ('closed:' + $count);`,
+    ].join(' ');
+}
+exports.appCloseTool = {
+    schema: {
+        name: 'app_close',
+        description: 'Close one or more Windows processes by name (with or without the .exe suffix). Matches all running instances of that name. Set `force: true` to skip the app\'s graceful-shutdown prompt. Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                app: {
+                    type: 'string',
+                    description: 'Process name (e.g. "notepad", "spotify"). The .exe suffix is stripped automatically. Matches ALL running instances of that name.',
+                },
+                force: {
+                    type: 'boolean',
+                    description: 'If true, terminate without giving the app a chance to save unsaved work. Default false (graceful close).',
+                },
+            },
+            required: ['app'],
+        },
+    },
+    category: 'execute',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('app_close');
+        const app = typeof args.app === 'string' ? normalise(args.app) : '';
+        if (!app) {
+            return { success: false, error: '`app` is required and must be non-empty.' };
+        }
+        const force = args.force === true;
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(app, force), {
+                timeoutMs: 10000,
+            });
+            const m = stdout.trim().match(/closed:(\d+)/);
+            const closed = m ? Number(m[1]) : 0;
+            return { success: true, app, closed, force };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

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

@@ -0,0 +1,92 @@
+"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;
+const _psHelpers_1 = require("./_psHelpers");
+function buildPs(appName, args) {
+    // Single-quote escape the app name for PowerShell.
+    const safeApp = appName.replace(/'/g, "''");
+    const argString = args && args.length > 0
+        ? `-ArgumentList @(${args.map((a) => `'${a.replace(/'/g, "''")}'`).join(',')})`
+        : '';
+    return [
+        `try {`,
+        `  $p = Start-Process '${safeApp}' ${argString} -PassThru -ErrorAction Stop;`,
+        `  Write-Output ('PID=' + $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)';`,
+        `}`,
+    ].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();
+            // Extract PID when Start-Process succeeded; null for cmd-fallback path.
+            const pidMatch = out.match(/PID=(\d+)/);
+            const pid = pidMatch ? Number(pidMatch[1]) : null;
+            return { success: true, app, pid, raw: out };
+        }
+        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,78 @@
+"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: '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.',
+        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');
+        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 });
+            return { success: true, action };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};

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

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/osProcessList.ts — `os_process_list` tool.
+ *
+ * Lists OS-wide running processes via `Get-Process`. Distinct from the
+ * existing `process_list` tool which only enumerates child processes
+ * Aiden itself spawned via `process_spawn` — that's the wrong shape
+ * for questions like "is claude code running?" (the answer's process
+ * was started by the user, not Aiden).
+ *
+ * Filtering is supported via a substring on the process name. Default
+ * (no filter) lists the top-CPU processes capped at 30 so the model
+ * doesn't drown in a 200-row dump.
+ *
+ * Read-only. Cross-platform fallback returns a structured error
+ * pointing at the issue tracker.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.osProcessListTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+const DEFAULT_LIMIT = 30;
+const MAX_LIMIT = 200;
+function buildPs(nameFilter, limit) {
+    // Escape single quotes for the PowerShell -Name argument.
+    const filter = (nameFilter ?? '').trim();
+    // Get-Process picks `Name` (short), `Id` (pid), `CPU` (seconds), and
+    // `WorkingSet` (memory). ConvertTo-Json emits an array we parse.
+    const base = filter.length > 0
+        ? `Get-Process -Name '*${filter.replace(/'/g, "''")}*' -ErrorAction SilentlyContinue`
+        : 'Get-Process';
+    return [
+        base,
+        `| Sort-Object CPU -Descending`,
+        `| Select-Object -First ${limit} Name, Id, @{N='CPU';E={[math]::Round($_.CPU,2)}}, @{N='MemoryMB';E={[math]::Round($_.WorkingSet64/1MB,1)}}`,
+        `| ConvertTo-Json -Compress -Depth 2`,
+    ].join(' ');
+}
+exports.osProcessListTool = {
+    schema: {
+        name: 'os_process_list',
+        description: 'List OS-wide running processes (top by CPU). Use this to answer questions like "is X running?" or "what apps are using CPU?". Supports an optional name substring filter. Distinct from `process_list` which only shows processes Aiden itself spawned. Windows-only in v4.1.2.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                name: {
+                    type: 'string',
+                    description: 'Optional process-name substring filter, e.g. "claude" to find "claude.exe" / "claude_code.exe" / "claude-helper.exe". Omit to list top-CPU processes.',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Max rows to return (default 30, max 200). Use a higher value when answering "list everything running" style questions.',
+                },
+            },
+        },
+    },
+    category: 'read',
+    mutates: false,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)())
+            return (0, _psHelpers_1.windowsOnlyError)('os_process_list');
+        const nameArg = typeof args.name === 'string' ? args.name : undefined;
+        const rawLimit = typeof args.limit === 'number' ? args.limit : DEFAULT_LIMIT;
+        const limit = Math.min(Math.max(1, Math.floor(rawLimit)), MAX_LIMIT);
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(nameArg, limit), {
+                timeoutMs: 15000,
+            });
+            const trimmed = stdout.trim();
+            // Get-Process returns nothing when the filter matches zero processes;
+            // PowerShell pipeline prints empty. Treat as "no matches" success.
+            if (trimmed.length === 0) {
+                return { success: true, processes: [], count: 0, filter: nameArg };
+            }
+            // ConvertTo-Json emits an object (single result) or array (multiple).
+            // Normalise to array.
+            const parsed = JSON.parse(trimmed);
+            const processes = Array.isArray(parsed) ? parsed : [parsed];
+            return {
+                success: true,
+                count: processes.length,
+                filter: nameArg,
+                processes,
+            };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};