aiden-runtime 4.1.1 → 4.1.3

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

@@ -0,0 +1,123 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/_psHelpers.ts — Phase v4.1.2-followup-3.
+ *
+ * Shared utilities for the computer-control tool family. Each tool
+ * (screenshot / os_process_list / media_key / volume_set / app_launch /
+ * app_close / clipboard_read / clipboard_write) gates on `win32` and
+ * shells out to PowerShell. The gate + exec boilerplate is identical
+ * across all eight tools — extracted here so the per-tool files stay
+ * focused on the one PowerShell snippet that matters.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isWindows = exports.execAsync = void 0;
+exports.windowsOnlyError = windowsOnlyError;
+exports.runPowerShell = runPowerShell;
+exports.winRtAwaitPreamble = winRtAwaitPreamble;
+const node_child_process_1 = require("node:child_process");
+const node_util_1 = require("node:util");
+exports.execAsync = (0, node_util_1.promisify)(node_child_process_1.exec);
+/**
+ * Standard "not supported on this platform" error payload. Surfaces a
+ * link the user can file an issue against rather than pretending the
+ * call quietly no-op'd.
+ *
+ * v4.1.3-essentials: now also returns a structured `capabilityCard`
+ * payload (per ToolCallResult.capabilityCard contract). The REPL
+ * renders the card as a bordered block above the bare-error fallback,
+ * giving non-Windows users a clear "here's what you can still do"
+ * surface instead of a one-line "platform unsupported" wall.
+ *
+ * The `canStill` / `cannotReliably` lists are passed by the caller so
+ * each tool can be specific (e.g. `app_input` mentions Chrome DevTools
+ * Protocol as a non-Windows alternative; `media_transport` points at
+ * `media_key` or a Spotify Web API skill instead). Falls back to a
+ * generic "use shell_exec for platform commands" hint when caller
+ * doesn't supply alternatives.
+ */
+function windowsOnlyError(toolName, alternatives) {
+    const canStill = alternatives?.canStill ?? [
+        'Use `shell_exec` to run platform-native commands directly',
+        'Use `os_process_list` to inspect what\'s running',
+    ];
+    const cannotReliably = alternatives?.cannotReliably ?? [
+        `Call \`${toolName}\` until cross-platform support lands`,
+    ];
+    const fix = alternatives?.fix
+        ?? `Run Aiden on Windows for full \`${toolName}\` support, or file an ` +
+            `issue at github.com/taracodlabs/aiden if your platform is a priority.`;
+    return {
+        success: false,
+        error: `Tool '${toolName}' is Windows-only. macOS/Linux ` +
+            `support tracked at github.com/taracodlabs/aiden — please file an ` +
+            `issue if needed. (Detected platform: ${process.platform})`,
+        requires: ['Windows'],
+        capabilityCard: {
+            title: `${toolName} requires Windows`,
+            canStill,
+            cannotReliably,
+            fix,
+        },
+    };
+}
+/**
+ * Run a PowerShell snippet and return stdout. Defaults to a 15-second
+ * timeout — caller passes a different one when a slower operation
+ * (screenshot, app launch) is expected.
+ *
+ * Single source of truth for the `shell: 'powershell.exe'` invocation
+ * shape so future powershell-CLI / `pwsh` migration is one-line.
+ */
+async function runPowerShell(script, options = {}) {
+    const opts = {
+        shell: 'powershell.exe',
+        timeout: options.timeoutMs ?? 15000,
+        maxBuffer: (options.maxBufferMb ?? 4) * 1024 * 1024,
+    };
+    return await (0, exports.execAsync)(script, opts);
+}
+const isWindows = () => process.platform === 'win32';
+exports.isWindows = isWindows;
+/**
+ * v4.1.4-media: PowerShell 5.1 preamble that bridges WinRT
+ * `IAsyncOperation<T>` into a .NET `Task<T>` via
+ * `System.WindowsRuntimeSystemExtensions.AsTask`.
+ *
+ * Why: every WinRT call surface we touch — `GlobalSystemMediaTransport-
+ * ControlsSessionManager.RequestAsync()`, `Session.TryGetMediaPropertiesAsync()`,
+ * `Session.TryPlayAsync()`, etc. — returns `IAsyncOperation<T>`. PS5.1
+ * (the shell we target — it ships on every stock Win10/11 install) cannot
+ * call `.GetAwaiter().GetResult()` on those because WinRT awaiters aren't
+ * recognized as TPL-compatible. The reflection dance below grabs the
+ * single-arg overload of `AsTask`, specializes it to `T`, and invokes —
+ * yielding a `Task<T>` we can `.Wait()` on.
+ *
+ * Three callers consume this string:
+ *   - `core/tools/nowPlaying.ts`         (read GSMTC properties)
+ *   - `tools/v4/system/mediaSessions.ts` (enumerate GSMTC sessions)
+ *   - `tools/v4/system/mediaTransport.ts` (play/pause/skip on a target)
+ *
+ * Returned as a literal string — caller composes it into a larger
+ * PS script. Pure (no side effects, no PowerShell exec). No leading/
+ * trailing whitespace so callers can interpolate without surprises.
+ */
+function winRtAwaitPreamble() {
+    return `Add-Type -AssemblyName System.Runtime.WindowsRuntime
+function Await($WinRtTask, $ResultType) {
+    $m = ([System.WindowsRuntimeSystemExtensions].GetMethods() | Where-Object {
+        $_.Name -eq 'AsTask' -and
+        $_.GetParameters().Count -eq 1 -and
+        $_.GetParameters()[0].ParameterType.Name -eq 'IAsyncOperation\`1'
+    })[0]
+    $m = $m.MakeGenericMethod($ResultType)
+    $t = $m.Invoke($null, @($WinRtTask))
+    $t.Wait(-1) | Out-Null
+    $t.Result
+}`;
+}

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/appInput.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * Copyright (c) 2026 Shiva Deore (Taracod).
+ * Licensed under AGPL-3.0. See LICENSE for details.
+ *
+ * Aiden — local-first agent.
+ */
+/**
+ * tools/v4/system/appInput.ts — `app_input` tool. v4.1.4-media.
+ *
+ * Focus a window by process name, then send a SendKeys keystroke
+ * sequence to it. Useful escape hatch when neither the semantic API
+ * (layer 1) nor GSMTC (layer 2) surface a control — e.g. "press space
+ * in Chrome to pause this YouTube tab" when GSMTC doesn't enumerate
+ * the page as a media session.
+ *
+ * Honest about what it doesn't do: SendKeys lands keys in whatever
+ * window has focus AT THE MOMENT of the keystroke. We try
+ * AppActivate, but Windows refuses foreground activation when the
+ * calling process didn't recently receive input — the call returns
+ * a result we surface, but receipt at the target app is not
+ * guaranteed. Hence `degraded: true` on every successful invocation
+ * (mirrors the v4.1.3 honesty-degraded convention from `media_key`).
+ *
+ * Scope (v4.1.4): focus + SendKeys only. Mouse click coordinates,
+ * window-coords resolution, UI Automation deferred.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appInputTool = void 0;
+const _psHelpers_1 = require("./_psHelpers");
+/**
+ * Build the PowerShell snippet. Calls AppActivate on the process by
+ * name, then SendKeys.SendWait. Both PowerShell calls return booleans /
+ * void; we capture stdout to JSON with the activation outcome so the
+ * model can see whether focus probably landed.
+ *
+ * Note on AppActivate: it returns $true if the process exists and a
+ * window was activated, $false otherwise. It does NOT confirm the
+ * window is the foreground from the OS's perspective — Windows
+ * sometimes flashes the taskbar entry instead. We pass that flag
+ * through as `activated` for transparency.
+ */
+function buildPs(processName, keys) {
+    // Single-quote escape both inputs for the PowerShell string literals.
+    const safeProc = processName.replace(/'/g, "''");
+    const safeKeys = keys.replace(/'/g, "''");
+    return [
+        'Add-Type -AssemblyName Microsoft.VisualBasic;',
+        'Add-Type -AssemblyName System.Windows.Forms;',
+        '$shell = New-Object -ComObject WScript.Shell;',
+        `$activated = $shell.AppActivate('${safeProc}');`,
+        // Give the OS ~150ms to settle before keystrokes — without this
+        // the keys can land in the calling shell on slower hardware.
+        'Start-Sleep -Milliseconds 150;',
+        `[System.Windows.Forms.SendKeys]::SendWait('${safeKeys}');`,
+        "@{ activated=[bool]$activated } | ConvertTo-Json -Compress;",
+    ].join(' ');
+}
+exports.appInputTool = {
+    schema: {
+        name: 'app_input',
+        description: 'Focus a Windows application window by process name and send a ' +
+            'SendKeys keystroke sequence to it. Use as a layer-3 fallback when ' +
+            'neither a semantic API (layer 1, e.g. Spotify Web API) nor GSMTC ' +
+            '(layer 2, `media_transport`) can do the job. Examples: "{SPACE}" to ' +
+            'pause a YouTube tab in Chrome, "^l" for Ctrl+L address-bar focus. ' +
+            'Receipt at the target app is best-effort — Windows can refuse ' +
+            'foreground activation; the tool reports `degraded:true` even on ' +
+            'apparent success. Windows-only in v4.1.4.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                app: {
+                    type: 'string',
+                    description: 'Process name (with or without .exe) or window-title substring ' +
+                        'AppActivate accepts: "chrome", "Spotify", "Notepad", etc.',
+                },
+                keys: {
+                    type: 'string',
+                    description: 'SendKeys-format keystroke sequence. Examples: "{SPACE}" = ' +
+                        'space, "^c" = Ctrl+C, "%{TAB}" = Alt+Tab, "Hello{ENTER}" = ' +
+                        'literal text + Enter. See Microsoft\'s SendKeys docs for the ' +
+                        'full grammar.',
+                },
+            },
+            required: ['app', 'keys'],
+        },
+    },
+    category: 'execute',
+    mutates: true,
+    toolset: 'system',
+    async execute(args, _ctx) {
+        if (!(0, _psHelpers_1.isWindows)()) {
+            return (0, _psHelpers_1.windowsOnlyError)('app_input', {
+                canStill: [
+                    '`browser_*` tools for any browser-hosted UI (Playwright cross-platform)',
+                    '`shell_exec` with `xdotool` (Linux X11) for arbitrary window input',
+                    '`shell_exec` with `osascript` (macOS) for AppleScript-driven keystrokes',
+                ],
+                cannotReliably: [
+                    'AppActivate + SendKeys against a specific Windows process',
+                    'VBA-style window focus by process-name substring',
+                ],
+                fix: 'Run Aiden on Windows for native AppActivate, or use Playwright ' +
+                    '(`browser_*`) / xdotool / osascript via `shell_exec` for your platform.',
+            });
+        }
+        const app = typeof args.app === 'string' ? args.app.trim() : '';
+        const keys = typeof args.keys === 'string' ? args.keys : '';
+        if (!app) {
+            return { success: false, error: '`app` is required and must be non-empty.' };
+        }
+        if (!keys) {
+            return { success: false, error: '`keys` is required and must be non-empty.' };
+        }
+        try {
+            const { stdout } = await (0, _psHelpers_1.runPowerShell)(buildPs(app, keys), {
+                timeoutMs: 5000,
+            });
+            const trimmed = stdout.trim();
+            let activated = false;
+            if (trimmed.length > 0) {
+                try {
+                    const parsed = JSON.parse(trimmed);
+                    activated = parsed.activated === true;
+                }
+                catch {
+                    // Non-JSON output — degraded but not failed; the SendKeys
+                    // call likely still ran. Surface in degradedReason.
+                    activated = false;
+                }
+            }
+            return {
+                success: true,
+                app,
+                activated,
+                // v4.1.3-repl-polish honesty pattern: SendKeys cannot confirm
+                // receipt at the target window. AppActivate returning $true
+                // narrows the gap but doesn't close it — Windows can reject
+                // foreground activation silently. Always degraded.
+                degraded: true,
+                degradedReason: activated
+                    ? `keys sent to ${app}; activation reported success but cannot verify receipt`
+                    : `keys sent; ${app} window activation reported failure — receipt unlikely`,
+            };
+        }
+        catch (e) {
+            return {
+                success: false,
+                error: e instanceof Error ? e.message : String(e),
+            };
+        }
+    },
+};