aiden-runtime 4.1.2 → 4.1.3

package/dist/core/v4/sessionDistiller.js

@@ -192,7 +192,19 @@ function recoverBullets(raw) {
     }
     return [];
 }
-const DEFAULT_TIMEOUT_MS = 4000;
+/**
+ * v4.1.3-essentials distillation-fix: default raised from 4000ms to
+ * 12000ms after visual smoke showed chatgpt-plus Codex regularly
+ * exceeded the original budget for 800-token summaries on
+ * cold-start. Symptom: every `/quit` distillation returned
+ * `partial:true` with empty bullets/decisions/open_items, killing
+ * both the MEMORY.md update path AND the promotion prompt.
+ *
+ * 12s gives comfortable headroom while still aborting genuinely
+ * stuck calls. Power users can override via `AIDEN_SUMMARY_TIMEOUT_MS`
+ * env var (consumed by `resolveSummaryTimeoutMs()` in chatSession).
+ */
+const DEFAULT_TIMEOUT_MS = 12000;
 /**
  * Phase v4.1.2-bug-Y: max chars of tool-result content surfaced to the
  * auxiliary LLM. Covers typical error messages + JSON-payload heads
@@ -372,11 +384,46 @@ async function distillSession(opts) {
             setTimeout(() => resolve({ ok: false, error: new Error(`auxiliary call timed out after ${timeoutMs}ms`), timedOut: true }), timeoutMs);
         }),
     ]);
+    // v4.1.3-essentials distillation-fix: emit a diagnostic line for
+    // each of the three failure classes so the caller can surface the
+    // root cause. Previously all three paths produced an identical
+    // `partial:true + empty` result with no signal about WHICH failure
+    // fired. Safe to call onDiagnostic synchronously — caller wraps in
+    // try/catch so a throwing sink doesn't break distillation.
+    const diag = (msg) => {
+        if (!opts.onDiagnostic)
+            return;
+        try {
+            opts.onDiagnostic(msg);
+        }
+        catch { /* never break distillation */ }
+    };
     let semantic;
     if (llmRaw.ok) {
         semantic = parseLLMDistillation(llmRaw.content);
+        if (semantic.partial) {
+            // Parser fell back to bullets-only or fully-empty — the LLM
+            // returned content but it wasn't valid JSON. First-200-chars
+            // hint lets the user / debugger see what shape the model
+            // actually emitted (often a chatty preamble that confused
+            // the JSON extractor).
+            const head = llmRaw.content.trim().slice(0, 200).replace(/\n/g, ' ');
+            diag(`auxiliary returned unparseable JSON (first 200 chars: ${head})`);
+        }
     }
     else {
+        // Race resolved with the failure branch — either the timeout
+        // fired or auxiliaryClient.call threw. Hoist `error` into a
+        // local so the narrowed type stays stable inside the branch
+        // (TS can't infer `error` exists on `llmRaw` because the union
+        // overlaps with the success branch in its type literal).
+        const failure = llmRaw;
+        if (failure.timedOut === true) {
+            diag(`auxiliary call timed out after ${timeoutMs}ms`);
+        }
+        else {
+            diag(`auxiliary call failed: ${failure.error.message}`);
+        }
         semantic = {
             bullets: [],
             decisions: [],

package/dist/core/v4/toolRegistry.js

@@ -154,7 +154,22 @@ class ToolRegistry {
             }
             try {
                 const result = await handler.execute(args, context);
-                return { id: call.id, name: call.name, result };
+                // v4.1.3-repl-polish: lift `degraded` + `degradedReason` from the
+                // handler's inner result to the outer ToolCallResult so the CLI
+                // trail row can render the partial-yellow state. Tools opt in by
+                // setting these on the object they return; without this lift the
+                // flags would sit on `out.result.degraded` where callbacks.ts
+                // can't see them. Strict typeof checks avoid promoting truthy-
+                // but-wrong-shape junk (numbers, strings, nested objects).
+                const inner = result;
+                const out = { id: call.id, name: call.name, result };
+                if (typeof inner?.degraded === 'boolean' && inner.degraded) {
+                    out.degraded = true;
+                    if (typeof inner.degradedReason === 'string') {
+                        out.degradedReason = inner.degradedReason;
+                    }
+                }
+                return out;
             }
             catch (err) {
                 const message = err instanceof Error ? err.message : String(err);

package/dist/core/version.js

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // AUTO-GENERATED by scripts/inject-version.js — do not edit by hand
-exports.VERSION = '4.1.2';
+exports.VERSION = '4.1.3';

package/dist/moat/plannerGuard.js

@@ -91,6 +91,25 @@ const RULES = [
         keywords: /\b(process|background|long.?running|server|spawn|kill|daemon)\b/i,
         toolsets: ['process'],
     },
+    // Media playback control (v4.1.4-media)
+    //
+    // Without this, intents like "list media sessions" matched the
+    // `sessions` rule via the bare word "session" → narrowed surface to
+    // toolset `sessions` only → `media_sessions` (toolset `system`) was
+    // filtered out and the model honestly reported it as unavailable.
+    // UNION semantics mean both rules contribute on phrases that hit
+    // both ("media sessions" → sessions + system), giving the model the
+    // full picture without needing a dedicated `media` toolset.
+    //
+    // Toolset is `system` (broad but minimal blast radius): the bundle
+    // covers media_sessions, media_transport, media_key, app_input,
+    // now_playing, plus the plausibly-relevant app_launch / volume_set /
+    // os_process_list. Carving out a dedicated `media` toolset is a
+    // separate slice if the surface noise becomes a real problem.
+    {
+        keywords: /\b(play|pause|skip|spotify|music|song|video|youtube|track|playback|media)\b/i,
+        toolsets: ['system'],
+    },
 ];
 /** Always-on tools regardless of mode. The agent needs schema lookup
  *  + skill discovery + session search to be useful even on cold turns. */

package/dist/providers/v4/errors.js

@@ -17,6 +17,8 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.ProviderRateLimitError = exports.ProviderTimeoutError = exports.ProviderError = void 0;
 exports.formatRawForMessage = formatRawForMessage;
+exports.classifyProviderError = classifyProviderError;
+exports.suggestForErrorClass = suggestForErrorClass;
 /**
  * Format a raw response body for inclusion in the user-facing error
  * message. Recognises three JSON envelope shapes and falls back to the
@@ -109,3 +111,93 @@ class ProviderRateLimitError extends ProviderError {
     }
 }
 exports.ProviderRateLimitError = ProviderRateLimitError;
+function classifyProviderError(err) {
+    if (err == null)
+        return 'other';
+    // 1. Type-based class detection (fastest, most structured).
+    if (err instanceof ProviderRateLimitError)
+        return 'rate_limit';
+    if (err instanceof ProviderTimeoutError)
+        return 'transport';
+    if (err instanceof ProviderError) {
+        if (err.statusCode === 413)
+            return 'context_overflow';
+        if (err.statusCode === 429)
+            return 'rate_limit';
+        if (err.statusCode === 401 || err.statusCode === 403)
+            return 'auth';
+    }
+    // 2. Fall back to message scanning. Adapters that pass through the
+    //    upstream JSON `error.message` verbatim land here.
+    const msg = err instanceof Error ? err.message : String(err);
+    const lc = msg.toLowerCase();
+    // Context overflow / 413 family. Groq's free-tier TPM cap triggers
+    // these on the first turn once the prompt + tool schemas inflate.
+    if (lc.includes('413') ||
+        lc.includes('context_length_exceeded') ||
+        lc.includes('context length') ||
+        lc.includes('too large') ||
+        lc.includes('maximum context length') ||
+        lc.includes('payload too large')) {
+        return 'context_overflow';
+    }
+    // Rate-limit family — 429 / TPM / quota / "too many requests".
+    if (lc.includes('429') ||
+        lc.includes('rate_limit') ||
+        lc.includes('rate limit') ||
+        lc.includes('too many requests') ||
+        lc.includes('quota') ||
+        lc.includes('tpm')) {
+        return 'rate_limit';
+    }
+    // Auth family — 401 / 403 / invalid keys / unauthenticated.
+    if (lc.includes('401') ||
+        lc.includes('403') ||
+        lc.includes('invalid_api_key') ||
+        lc.includes('invalid api key') ||
+        lc.includes('unauthenticated') ||
+        lc.includes('unauthorized') ||
+        lc.includes('forbidden')) {
+        return 'auth';
+    }
+    // Transport — network, DNS, timeouts that escaped the typed path.
+    if (lc.includes('econnrefused') ||
+        lc.includes('enotfound') ||
+        lc.includes('etimedout') ||
+        lc.includes('socket hang up') ||
+        lc.includes('network')) {
+        return 'transport';
+    }
+    return 'other';
+}
+/**
+ * v4.1.3-prebump: produce a single-sentence actionable hint for the
+ * given error class. Returns null for `'other'` so the caller can keep
+ * its existing default suggestion. Provider name is surfaced where it
+ * sharpens the advice ("groq rate-limited" reads clearer than
+ * "rate limit").
+ *
+ * Pure helper. The REPL displays the result; tests assert it. No
+ * registry / state access — feed it the class + provider name.
+ */
+function suggestForErrorClass(cls, providerName) {
+    const p = providerName ?? 'this provider';
+    switch (cls) {
+        case 'context_overflow':
+            return (`${p} returned 413 (context too large). The combined system prompt ` +
+                `+ tool schemas exceed ${p}'s context window. Try \`/model\` to ` +
+                `switch to a provider with more headroom (chatgpt-plus, anthropic, ` +
+                `deepseek).`);
+        case 'rate_limit':
+            return (`${p} is rate-limited. Wait a minute, or run \`/model\` to switch ` +
+                `to another authed provider while ${p} cools off.`);
+        case 'auth':
+            return (`${p} rejected the credentials. Run \`/auth status\` (or check the ` +
+                `relevant API key env var) and \`/auth login\` if needed.`);
+        case 'transport':
+            return (`Network or transport error reaching ${p}. Check connectivity, then ` +
+                `retry — or \`/model\` to a local provider (ollama) for offline work.`);
+        case 'other':
+            return null;
+    }
+}

package/dist/tools/v4/index.js

@@ -21,7 +21,8 @@
  * Status: PHASE 8.
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.sessionSummaryTool = exports.memoryRemoveTool = exports.memoryReplaceTool = exports.memoryAddTool = exports.processWaitTool = exports.processKillTool = exports.processLogReadTool = exports.processListTool = exports.processSpawnTool = exports.executeCodeTool = exports.shellExecTool = exports.clipboardWriteTool = exports.clipboardReadTool = exports.appCloseTool = exports.appLaunchTool = exports.volumeSetTool = exports.mediaKeyTool = exports.osProcessListTool = exports.screenshotTool = exports.naturalEventsTool = exports.nowPlayingTool = exports.systemInfoTool = exports.makeLookupToolSchema = exports.skillManageTool = exports.skillViewTool = exports.skillsListTool = exports.sessionListTool = exports.sessionSearchTool = exports.browserCloseTool = exports.browserScrollTool = exports.browserFillTool = exports.browserTypeTool = exports.browserClickTool = exports.browserNavigateTool = exports.browserGetUrlTool = exports.browserExtractTool = exports.browserScreenshotTool = exports.fileCopyTool = exports.fileMoveTool = exports.fileDeleteTool = exports.filePatchTool = exports.fileWriteTool = exports.fileListTool = exports.fileReadTool = exports.deepResearchTool = exports.webPageTool = exports.webFetchTool = exports.webSearchTool = exports.makeSubagentFanoutTool = void 0;
+exports.memoryReplaceTool = exports.memoryAddTool = exports.processWaitTool = exports.processKillTool = exports.processLogReadTool = exports.processListTool = exports.processSpawnTool = exports.executeCodeTool = exports.shellExecTool = exports.appInputTool = exports.mediaTransportTool = exports.mediaSessionsTool = exports.clipboardWriteTool = exports.clipboardReadTool = exports.appCloseTool = exports.appLaunchTool = exports.volumeSetTool = exports.mediaKeyTool = exports.osProcessListTool = exports.screenshotTool = exports.naturalEventsTool = exports.nowPlayingTool = exports.systemInfoTool = exports.makeLookupToolSchema = exports.skillManageTool = exports.skillViewTool = exports.skillsListTool = exports.sessionListTool = exports.sessionSearchTool = exports.browserCloseTool = exports.browserScrollTool = exports.browserFillTool = exports.browserTypeTool = exports.browserClickTool = exports.browserNavigateTool = exports.browserGetUrlTool = exports.browserExtractTool = exports.browserScreenshotTool = exports.fileCopyTool = exports.fileMoveTool = exports.fileDeleteTool = exports.filePatchTool = exports.fileWriteTool = exports.fileListTool = exports.fileReadTool = exports.deepResearchTool = exports.webPageTool = exports.webFetchTool = exports.webSearchTool = exports.makeSubagentFanoutTool = void 0;
+exports.sessionSummaryTool = exports.memoryRemoveTool = void 0;
 exports.registerReadOnlyTools = registerReadOnlyTools;
 exports.registerWriteTools = registerWriteTools;
 exports.registerAllTools = registerAllTools;
@@ -66,6 +67,13 @@ const appLaunch_1 = require("./system/appLaunch");
 const appClose_1 = require("./system/appClose");
 const clipboardRead_1 = require("./system/clipboardRead");
 const clipboardWrite_1 = require("./system/clipboardWrite");
+// v4.1.4-media — three-layer media-control bundle.
+// Layer 2 (OS media session): mediaSessions (read) + mediaTransport (write).
+// Layer 3 fallback (mediaKey, blind keystroke) remains unchanged.
+// Layer 1 (semantic API) is per-app and out of this slice.
+const mediaSessions_1 = require("./system/mediaSessions");
+const mediaTransport_1 = require("./system/mediaTransport");
+const appInput_1 = require("./system/appInput");
 // Phase v4.1.2-update — natural-language self-update entry point.
 // Routes through the same shared executeInstall executor as `/update install`.
 const aidenSelfUpdate_1 = require("./system/aidenSelfUpdate");
@@ -123,6 +131,9 @@ function registerReadOnlyTools(registry) {
     registry.register(screenshot_1.screenshotTool);
     registry.register(osProcessList_1.osProcessListTool);
     registry.register(clipboardRead_1.clipboardReadTool);
+    // v4.1.4-media — GSMTC session enumeration (read). Pair with
+    // mediaTransport (write) in the write-tools registration below.
+    registry.register(mediaSessions_1.mediaSessionsTool);
     registry.register((0, lookupToolSchema_1.makeLookupToolSchema)(registry));
     // Phase v4.1-subagent — register a stub for subagent_fanout so its
     // schema is visible to the agent loop, the MCP server, and the
@@ -198,6 +209,11 @@ function registerWriteTools(registry) {
     registry.register(appLaunch_1.appLaunchTool);
     registry.register(appClose_1.appCloseTool);
     registry.register(clipboardWrite_1.clipboardWriteTool);
+    // v4.1.4-media — verified GSMTC transport (replaces mediaKey for
+    // the "name an app, play/pause it" case) + focused-window SendKeys
+    // (escape hatch when GSMTC doesn't enumerate the surface).
+    registry.register(mediaTransport_1.mediaTransportTool);
+    registry.register(appInput_1.appInputTool);
 }
 /** Register every v4 tool. Most callers want this. */
 function registerAllTools(registry) {
@@ -281,6 +297,13 @@ var clipboardRead_2 = require("./system/clipboardRead");
 Object.defineProperty(exports, "clipboardReadTool", { enumerable: true, get: function () { return clipboardRead_2.clipboardReadTool; } });
 var clipboardWrite_2 = require("./system/clipboardWrite");
 Object.defineProperty(exports, "clipboardWriteTool", { enumerable: true, get: function () { return clipboardWrite_2.clipboardWriteTool; } });
+// v4.1.4-media exports — three-layer media-control bundle.
+var mediaSessions_2 = require("./system/mediaSessions");
+Object.defineProperty(exports, "mediaSessionsTool", { enumerable: true, get: function () { return mediaSessions_2.mediaSessionsTool; } });
+var mediaTransport_2 = require("./system/mediaTransport");
+Object.defineProperty(exports, "mediaTransportTool", { enumerable: true, get: function () { return mediaTransport_2.mediaTransportTool; } });
+var appInput_2 = require("./system/appInput");
+Object.defineProperty(exports, "appInputTool", { enumerable: true, get: function () { return appInput_2.appInputTool; } });
 var shellExec_2 = require("./terminal/shellExec");
 Object.defineProperty(exports, "shellExecTool", { enumerable: true, get: function () { return shellExec_2.shellExecTool; } });
 var executeCode_2 = require("./executeCode");

package/dist/tools/v4/sessions/recallSession.js

@@ -132,6 +132,14 @@ exports.recallSessionTool = {
             include_full: args.include_full === true,
         };
         const ranked = (0, distillationIndex_1.rankDistillations)(dists, recallQuery);
+        // v4.1.3-repl-polish: mark degraded when any matched session was
+        // distilled with the Phase A+B `partial: true` flag (LLM-timeout
+        // path — deterministic fields present, semantic bullets/decisions
+        // may be empty). The model still gets the full match list; the
+        // trail row renders yellow so the user knows recall completed
+        // against partial data.
+        const partialCount = ranked.matches.filter((m) => m.partial === true).length;
+        const degraded = partialCount > 0;
         return {
             success: true,
             query: recallQuery.query,
@@ -142,6 +150,12 @@ exports.recallSessionTool = {
             // delta is malformed files; the agent can suggest running aiden
             // doctor to inspect.
             scanned: ids.length,
+            ...(degraded && {
+                degraded: true,
+                degradedReason: partialCount === 1
+                    ? '1 matched session has partial distillation data'
+                    : `${partialCount} matched sessions have partial distillation data`,
+            }),
         };
         // Note re: subsystem health — wire-up happens at the runtime
         // construction layer (cli/v4/aidenCLI.ts) where the registry is

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

@@ -19,6 +19,7 @@ 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);
@@ -26,13 +27,43 @@ 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) {
+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 in v4.1.2. macOS/Linux ` +
+        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,
+        },
     };
 }
 /**
@@ -53,3 +84,40 @@ async function runPowerShell(script, options = {}) {
 }
 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/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),
+            };
+        }
+    },
+};