@phuetz/code-buddy 1.0.0 → 1.2.0

package/dist/daemon/cron-agent-bridge.js

@@ -28,14 +28,14 @@ export class CronAgentBridge extends EventEmitter {
      * Create a task executor function for the CronScheduler
      */
     createTaskExecutor() {
-        return async (job) => {
-            return this.executeJob(job);
+        return async (job, inputData) => {
+            return this.executeJob(job, inputData);
         };
     }
     /**
      * Execute a cron job by creating an agent instance
      */
-    async executeJob(job) {
+    async executeJob(job, inputData) {
         const startTime = Date.now();
         const abortController = new AbortController();
         this.activeJobs.set(job.id, abortController);
@@ -80,9 +80,10 @@ export class CronAgentBridge extends EventEmitter {
             }
             let output;
             let watchdogOk;
+            let scriptStdout;
             switch (job.task.type) {
                 case 'message': {
-                    output = await this.executeMessageTask(job);
+                    output = await this.executeMessageTask(job, inputData);
                     break;
                 }
                 case 'tool': {
@@ -100,7 +101,9 @@ export class CronAgentBridge extends EventEmitter {
                     break;
                 }
                 case 'script': {
-                    output = await this.executeScriptTask(job);
+                    const scriptResult = await this.executeScriptTaskFull(job);
+                    output = scriptResult.output;
+                    scriptStdout = scriptResult.stdout;
                     break;
                 }
                 case 'skill': {
@@ -132,6 +135,10 @@ export class CronAgentBridge extends EventEmitter {
                 deliveryChannel,
                 ...(watchdogOk !== undefined ? { watchdogOk } : {}),
             });
+            // For script jobs, outputData is the captured stdout only (structured
+            // data channel, capped at 64KB in the script runner). For all other
+            // task types, the full output serves as outputData.
+            const outputData = job.task.type === 'script' ? scriptStdout : output;
             const result = {
                 jobId: job.id,
                 runId: recordedRunId ?? `run-${Date.now()}`,
@@ -140,6 +147,7 @@ export class CronAgentBridge extends EventEmitter {
                 duration,
                 delivered,
                 deliveryChannel,
+                outputData,
                 ...(watchdogOk !== undefined ? { watchdogOk } : {}),
             };
             this.emit('job:complete', result);
@@ -223,7 +231,7 @@ export class CronAgentBridge extends EventEmitter {
     /**
      * Execute a message-type task
      */
-    async executeMessageTask(job) {
+    async executeMessageTask(job, inputData) {
         if (!job.task.message) {
             throw new Error('Message task requires a message');
         }
@@ -245,7 +253,12 @@ export class CronAgentBridge extends EventEmitter {
                 logger.debug(`Cron job ${job.id}: could not load session ${job.resolvedSessionId}, starting fresh`);
             }
         }
-        const entries = await agent.processUserMessage(job.task.message);
+        // Prepend inputData from parent chained job if available
+        let message = job.task.message;
+        if (inputData) {
+            message = `[Chained job context — output from parent job]:\n${inputData}\n\n[Task]:\n${message}`;
+        }
+        const entries = await agent.processUserMessage(message);
         const assistantEntries = entries.filter(e => e.type === 'assistant');
         return assistantEntries.map(e => e.content).join('\n') || 'No response';
     }
@@ -292,8 +305,11 @@ export class CronAgentBridge extends EventEmitter {
      * WITHOUT instantiating a CodeBuddyAgent or calling any model provider.
      * A non-zero exit (or timeout) throws so the run is recorded as failed and
      * any chained `then` job does not fire.
+     *
+     * Returns both the combined output (for logging/delivery) and the separate
+     * stdout (for cross-job data passing, capped at 64KB by the script runner).
      */
-    async executeScriptTask(job) {
+    async executeScriptTaskFull(job) {
         const command = job.task.command;
         if (!command || typeof command.executable !== 'string' || command.executable.length === 0) {
             throw new Error('Script task requires a command with an executable');
@@ -312,7 +328,7 @@ export class CronAgentBridge extends EventEmitter {
         if (result.exitCode !== 0) {
             throw new Error(`script failed: ${command.executable} (exit ${result.exitCode})\n${result.output}`.trim());
         }
-        return result.output;
+        return { output: result.output, stdout: result.stdout };
     }
     /**
      * Execute a skill-type task — resolves a named skill from the SkillRegistry

package/dist/desktop/codebuddy-engine-adapter.d.ts

@@ -40,6 +40,12 @@ export declare class CodeBuddyEngineAdapter implements EngineAdapter {
      * effect on the next turn (Phase 8).
      */
     private agentIdentities;
+    /**
+     * Configured reasoning/thinking level (`off | minimal | … | xhigh`), set via
+     * {@link setThinkingLevel}. Re-applied to each freshly-created agent so a
+     * model swap / new session keeps the user's chosen level.
+     */
+    private thinkingLevel?;
     /**
      * Hard cap on cached agents — matches the pi-runner's
      * `MAX_CACHED_SESSIONS` (50) so memory pressure is comparable
@@ -50,6 +56,7 @@ export declare class CodeBuddyEngineAdapter implements EngineAdapter {
     constructor(config: EngineSessionConfig);
     runSession(sessionId: string, messages: EngineMessage[], onEvent: EngineStreamCallback, options?: Partial<EngineSessionConfig>): Promise<EngineSessionResult>;
     cancel(sessionId: string): void;
+    steer(sessionId: string, prompt: string): boolean;
     clearSession(sessionId: string): void;
     /**
      * Drop oldest cached agents until `agents.size <= maxRetained`.
@@ -70,6 +77,21 @@ export declare class CodeBuddyEngineAdapter implements EngineAdapter {
      * returns whatever survived the previous load.
      */
     reloadSkills(): Promise<void>;
+    /**
+     * Hot-swap the reasoning/thinking level for live sessions. Updates the global
+     * extended-thinking budget (read per-turn by the OpenAI-compat / Grok / Ollama
+     * providers → effective next turn, no rebuild) and the Gemini-native default on
+     * every cached agent. The level is remembered so future agents inherit it.
+     */
+    setThinkingLevel(level: string): Promise<void>;
+    /**
+     * Map a UI level to the Gemini-native default thinking level on a single
+     * agent's client. `GeminiThinkingLevel` is `minimal|low|medium|high`, so
+     * `xhigh` clamps to `high` and `off`/unknown leaves the Gemini default
+     * untouched (the global extended-thinking switch already disables it for the
+     * OpenAI-compat path). Best-effort; never throws.
+     */
+    private applyGeminiThinkingLevel;
     /**
      * Synchronise the core MCPManager singleton with the host's view of
      * the MCP servers. Called by Cowork at boot and after any
@@ -97,3 +119,13 @@ export declare class CodeBuddyEngineAdapter implements EngineAdapter {
      */
     updateConfig(config: Partial<EngineSessionConfig>): void;
 }
+/** Cap a single failure detail so the footer stays compact for the judge. */
+export declare function truncateFailureDetail(detail: string, max?: number): string;
+/**
+ * Build a prominent, NON-bracketed footer listing failed tool actions. The goal
+ * judge prompt (goal-state.ts) treats `[tool:…]` bracketed lines as ignorable
+ * metadata, so failures must be surfaced as a plain instruction line or the
+ * judge discounts them. Returns '' when there are no failures.
+ */
+export declare function buildToolFailureFooter(failures: string[]): string;
+export declare function buildGoalJudgeResponse(content: string, toolEvidence: string[], toolFailures?: string[]): string;

package/dist/desktop/codebuddy-engine-adapter.js

@@ -9,6 +9,10 @@
  */
 import { logger } from '../utils/logger.js';
 import { createHash } from 'node:crypto';
+import { maybeContinueGoalAfterTurn } from '../goals/goal-loop.js';
+import { getGoalManager } from '../goals/goal-manager.js';
+const COWORK_GOAL_SESSION_PREFIX = 'cowork:';
+const GOAL_LOOP_HARD_BACKSTOP = 100;
 /**
  * Concrete implementation of EngineAdapter that wraps CodeBuddyAgent.
  *
@@ -40,6 +44,12 @@ export class CodeBuddyEngineAdapter {
      * effect on the next turn (Phase 8).
      */
     agentIdentities = new Map();
+    /**
+     * Configured reasoning/thinking level (`off | minimal | … | xhigh`), set via
+     * {@link setThinkingLevel}. Re-applied to each freshly-created agent so a
+     * model swap / new session keeps the user's chosen level.
+     */
+    thinkingLevel;
     /**
      * Hard cap on cached agents — matches the pi-runner's
      * `MAX_CACHED_SESSIONS` (50) so memory pressure is comparable
@@ -102,6 +112,13 @@ export class CodeBuddyEngineAdapter {
                 if (typeof agent.setVisionGroundingModel === 'function') {
                     agent.setVisionGroundingModel(this.config.visionGroundingModel);
                 }
+                // Re-apply the configured thinking level so a freshly-created agent
+                // (new session or post model-swap) keeps the user's chosen level on the
+                // Gemini-native path. The OpenAI-compat / Grok / Ollama path reads the
+                // global extended-thinking budget per turn, so it needs no per-agent step.
+                if (this.thinkingLevel) {
+                    this.applyGeminiThinkingLevel(agent, this.thinkingLevel);
+                }
                 // Phase 9 — enforce LRU before insertion so we never exceed
                 // the cap. Evict the least-recently-used (head of the
                 // insertion-ordered Map) until there's room.
@@ -165,92 +182,166 @@ export class CodeBuddyEngineAdapter {
                     toolCallCount,
                 };
             }
-            // Stream the response
-            const stream = agent.processUserMessageStream(lastMessage.content);
-            for await (const chunk of stream) {
-                // Check for abort
-                if (abortController.signal.aborted) {
-                    break;
-                }
-                switch (chunk.type) {
-                    case 'content':
-                        if (chunk.content) {
-                            fullContent += chunk.content;
-                            onEvent({ type: 'content', content: chunk.content });
-                        }
-                        break;
-                    case 'reasoning':
-                        if (chunk.reasoning) {
-                            onEvent({ type: 'thinking', thinking: chunk.reasoning });
-                        }
-                        break;
-                    case 'tool_calls':
-                        if (chunk.toolCalls) {
-                            for (const tc of chunk.toolCalls) {
-                                toolCallCount++;
+            const streamingAgent = agent;
+            const goalSessionKey = buildCoworkGoalSessionKey(sessionId);
+            const runPromptTurn = async (prompt) => {
+                let turnContent = '';
+                const toolEvidence = [];
+                // Tracks FAILED tool actions this turn so the goal judge can't be fooled
+                // into a premature "done" by an assistant that narrates success after a
+                // write/patch/command actually failed (Hermes-style mutation verifier).
+                const toolFailures = [];
+                const stream = streamingAgent.processUserMessageStream(prompt);
+                for await (const chunk of stream) {
+                    // Check for abort
+                    if (abortController.signal.aborted) {
+                        return { interrupted: true, judgeResponse: buildGoalJudgeResponse(turnContent, toolEvidence, toolFailures) };
+                    }
+                    switch (chunk.type) {
+                        case 'content':
+                            if (chunk.content) {
+                                turnContent += chunk.content;
+                                fullContent += chunk.content;
+                                onEvent({ type: 'content', content: chunk.content });
+                            }
+                            break;
+                        case 'reasoning':
+                            if (chunk.reasoning) {
+                                onEvent({ type: 'thinking', thinking: chunk.reasoning });
+                            }
+                            break;
+                        case 'tool_calls':
+                            if (chunk.toolCalls) {
+                                for (const tc of chunk.toolCalls) {
+                                    toolCallCount++;
+                                    onEvent({
+                                        type: 'tool_start',
+                                        tool: {
+                                            id: tc.id,
+                                            name: tc.function.name,
+                                            input: tc.function.arguments,
+                                        },
+                                    });
+                                }
+                            }
+                            break;
+                        case 'tool_result':
+                            if (chunk.toolCall && chunk.toolResult) {
+                                const finalOutput = chunk.toolResult.output || chunk.toolResult.error;
+                                const toolStatus = chunk.toolResult.success ? 'success' : 'error';
+                                if (finalOutput) {
+                                    toolEvidence.push(`[tool:${chunk.toolCall.function.name} ${toolStatus}]\n${String(finalOutput)}`);
+                                }
+                                // Record failures INDEPENDENTLY of finalOutput — a tool that
+                                // fails with no output/error would otherwise be invisible to the
+                                // judge (the silent-failure hole).
+                                if (!chunk.toolResult.success) {
+                                    const detail = finalOutput ? `: ${truncateFailureDetail(String(finalOutput))}` : '';
+                                    toolFailures.push(`${chunk.toolCall.function.name}${detail}`);
+                                }
                                 onEvent({
-                                    type: 'tool_start',
+                                    type: 'tool_end',
                                     tool: {
-                                        id: tc.id,
-                                        name: tc.function.name,
-                                        input: tc.function.arguments,
+                                        id: chunk.toolCall.id,
+                                        name: chunk.toolCall.function.name,
+                                        input: chunk.toolCall.function.arguments,
+                                        output: finalOutput,
+                                        isError: !chunk.toolResult.success,
+                                        data: chunk.toolResult.data,
                                     },
                                 });
                             }
-                        }
-                        break;
-                    case 'tool_result':
-                        if (chunk.toolCall && chunk.toolResult) {
-                            const finalOutput = chunk.toolResult.output || chunk.toolResult.error;
-                            onEvent({
-                                type: 'tool_end',
-                                tool: {
-                                    id: chunk.toolCall.id,
-                                    name: chunk.toolCall.function.name,
-                                    output: finalOutput,
-                                    isError: !chunk.toolResult.success,
-                                    data: chunk.toolResult.data,
-                                },
-                            });
-                        }
-                        break;
-                    case 'tool_stream':
-                        if (chunk.toolStreamData) {
-                            onEvent({
-                                type: 'tool_stream',
-                                tool: {
-                                    id: chunk.toolStreamData.toolCallId,
-                                    name: chunk.toolStreamData.toolName,
-                                    delta: chunk.toolStreamData.delta,
-                                },
-                            });
-                        }
-                        break;
-                    case 'token_count':
-                        if (chunk.tokenCount !== undefined) {
-                            totalTokens = chunk.tokenCount;
-                            onEvent({ type: 'token_count', tokenCount: chunk.tokenCount });
-                        }
-                        break;
-                    case 'ask_user':
-                        if (chunk.askUser) {
-                            onEvent({ type: 'ask_user', askUser: chunk.askUser });
-                        }
-                        break;
-                    case 'plan_progress':
-                        if (chunk.planProgress) {
-                            onEvent({ type: 'plan_progress', planProgress: chunk.planProgress });
-                        }
-                        break;
-                    case 'diff_preview':
-                        if (chunk.diffPreview) {
-                            onEvent({ type: 'diff_preview', diffPreview: chunk.diffPreview });
-                        }
-                        break;
-                    case 'done':
-                        onEvent({ type: 'done' });
-                        break;
+                            break;
+                        case 'tool_stream':
+                            if (chunk.toolStreamData) {
+                                onEvent({
+                                    type: 'tool_stream',
+                                    tool: {
+                                        id: chunk.toolStreamData.toolCallId,
+                                        name: chunk.toolStreamData.toolName,
+                                        delta: chunk.toolStreamData.delta,
+                                    },
+                                });
+                            }
+                            break;
+                        case 'token_count':
+                            if (chunk.tokenCount !== undefined) {
+                                totalTokens = chunk.tokenCount;
+                                onEvent({ type: 'token_count', tokenCount: chunk.tokenCount });
+                            }
+                            break;
+                        case 'ask_user':
+                            if (chunk.askUser) {
+                                onEvent({ type: 'ask_user', askUser: chunk.askUser });
+                            }
+                            break;
+                        case 'plan_progress':
+                            if (chunk.planProgress) {
+                                onEvent({ type: 'plan_progress', planProgress: chunk.planProgress });
+                            }
+                            break;
+                        case 'steer':
+                            if (chunk.steer) {
+                                onEvent({ type: 'steer', steer: chunk.steer });
+                            }
+                            break;
+                        case 'diff_preview':
+                            if (chunk.diffPreview) {
+                                onEvent({ type: 'diff_preview', diffPreview: chunk.diffPreview });
+                            }
+                            break;
+                        case 'done':
+                            onEvent({ type: 'done' });
+                            break;
+                    }
+                }
+                return { interrupted: false, judgeResponse: buildGoalJudgeResponse(turnContent, toolEvidence, toolFailures) };
+            };
+            const emitGoalStatus = (message) => {
+                const content = `${fullContent ? '\n\n' : ''}${message}\n\n`;
+                fullContent += content;
+                onEvent({ type: 'content', content });
+            };
+            // Structured goal-status event for host UIs (Cowork goal banner). Emits the
+            // current GoalState snapshot so the renderer can show turn progress without
+            // re-reading goal storage. Safe no-op when no goal is set.
+            const emitGoalSnapshot = () => {
+                const s = getGoalManager(goalSessionKey).state;
+                if (!s || s.status === 'cleared')
+                    return;
+                onEvent({
+                    type: 'goal_status',
+                    goalStatus: {
+                        goal: s.goal,
+                        status: s.status,
+                        turnsUsed: s.turnsUsed,
+                        maxTurns: s.maxTurns,
+                        ...(s.lastVerdict ? { lastVerdict: s.lastVerdict } : {}),
+                        ...(s.lastReason ? { lastReason: s.lastReason } : {}),
+                    },
+                });
+            };
+            // Emit once up-front so the banner appears the instant a goal turn starts
+            // (before the first judge verdict), then again after each judged turn.
+            emitGoalSnapshot();
+            let turn = await runPromptTurn(lastMessage.content);
+            for (let i = 0; i < GOAL_LOOP_HARD_BACKSTOP; i++) {
+                const outcome = await maybeContinueGoalAfterTurn({
+                    client: streamingAgent.getClient?.() ?? null,
+                    lastResponse: turn.judgeResponse,
+                    interrupted: turn.interrupted,
+                    sessionKey: goalSessionKey,
+                });
+                if (outcome?.message) {
+                    emitGoalStatus(outcome.message);
                 }
+                if (outcome) {
+                    emitGoalSnapshot();
+                }
+                if (turn.interrupted || !outcome?.continuationPrompt) {
+                    break;
+                }
+                turn = await runPromptTurn(outcome.continuationPrompt);
             }
             return {
                 content: fullContent,
@@ -278,6 +369,18 @@ export class CodeBuddyEngineAdapter {
             logger.info('[CodeBuddyEngineAdapter] cancelled session', { sessionId });
         }
     }
+    steer(sessionId, prompt) {
+        const controller = this.abortControllers.get(sessionId);
+        const agent = this.agents.get(sessionId);
+        const queue = agent?.getMessageQueue?.();
+        if (!controller || controller.signal.aborted || !queue) {
+            return false;
+        }
+        queue.setMode('steer');
+        queue.enqueue({ content: prompt, source: 'cowork', timestamp: new Date() });
+        logger.info('[CodeBuddyEngineAdapter] steer delivered', { sessionId });
+        return true;
+    }
     clearSession(sessionId) {
         const agent = this.agents.get(sessionId);
         if (agent && typeof agent.dispose === 'function') {
@@ -352,6 +455,51 @@ export class CodeBuddyEngineAdapter {
             logger.warn('[CodeBuddyEngineAdapter] reloadSkills failed', { err });
         }
     }
+    /**
+     * Hot-swap the reasoning/thinking level for live sessions. Updates the global
+     * extended-thinking budget (read per-turn by the OpenAI-compat / Grok / Ollama
+     * providers → effective next turn, no rebuild) and the Gemini-native default on
+     * every cached agent. The level is remembered so future agents inherit it.
+     */
+    async setThinkingLevel(level) {
+        this.thinkingLevel = level;
+        try {
+            const { getExtendedThinking } = await import('../agent/extended-thinking.js');
+            getExtendedThinking().applyThinkingLevel(level);
+        }
+        catch (err) {
+            logger.warn('[CodeBuddyEngineAdapter] applyThinkingLevel failed', { err });
+        }
+        for (const agent of this.agents.values()) {
+            this.applyGeminiThinkingLevel(agent, level);
+        }
+        logger.info('[CodeBuddyEngineAdapter] thinkingLevel set', { level });
+    }
+    /**
+     * Map a UI level to the Gemini-native default thinking level on a single
+     * agent's client. `GeminiThinkingLevel` is `minimal|low|medium|high`, so
+     * `xhigh` clamps to `high` and `off`/unknown leaves the Gemini default
+     * untouched (the global extended-thinking switch already disables it for the
+     * OpenAI-compat path). Best-effort; never throws.
+     */
+    applyGeminiThinkingLevel(agent, level) {
+        const geminiLevel = level === 'minimal' || level === 'low' || level === 'medium'
+            ? level
+            : level === 'high' || level === 'xhigh'
+                ? 'high'
+                : null;
+        if (!geminiLevel)
+            return;
+        try {
+            const getClient = agent.getClient;
+            if (typeof getClient === 'function') {
+                getClient.call(agent)?.setDefaultThinkingLevel(geminiLevel);
+            }
+        }
+        catch {
+            /* best effort — Gemini path only */
+        }
+    }
     /**
      * Synchronise the core MCPManager singleton with the host's view of
      * the MCP servers. Called by Cowork at boot and after any
@@ -481,4 +629,33 @@ export class CodeBuddyEngineAdapter {
         });
     }
 }
+function buildCoworkGoalSessionKey(sessionId) {
+    return `${COWORK_GOAL_SESSION_PREFIX}${sessionId}`;
+}
+/** Cap a single failure detail so the footer stays compact for the judge. */
+export function truncateFailureDetail(detail, max = 160) {
+    const flat = detail.replace(/\s+/g, ' ').trim();
+    return flat.length > max ? `${flat.slice(0, max - 1)}…` : flat;
+}
+/**
+ * Build a prominent, NON-bracketed footer listing failed tool actions. The goal
+ * judge prompt (goal-state.ts) treats `[tool:…]` bracketed lines as ignorable
+ * metadata, so failures must be surfaced as a plain instruction line or the
+ * judge discounts them. Returns '' when there are no failures.
+ */
+export function buildToolFailureFooter(failures) {
+    if (!failures.length)
+        return '';
+    return (`⚠️ ${failures.length} tool action(s) failed this turn: ${failures.join('; ')}. ` +
+        `Do NOT treat the goal as done if these failures block it — fix or work around them first.`);
+}
+export function buildGoalJudgeResponse(content, toolEvidence, toolFailures = []) {
+    const footer = buildToolFailureFooter(toolFailures);
+    const parts = [
+        content.trim(),
+        ...toolEvidence.map((part) => part.trim()),
+        footer, // last → most prominent for the LLM judge
+    ].filter(Boolean);
+    return parts.join('\n\n');
+}
 //# sourceMappingURL=codebuddy-engine-adapter.js.map

package/dist/desktop/engine-adapter.d.ts

@@ -40,6 +40,11 @@ export interface EngineAdapter {
      * Cancel a running session.
      */
     cancel(sessionId: string): void;
+    /**
+     * Deliver user guidance into an active run when the underlying agent
+     * supports steer mode. Returns false when there is no active run/agent.
+     */
+    steer?(sessionId: string, prompt: string): boolean | Promise<boolean>;
     /**
      * Clear internal state for a session (free memory, close resources).
      */
@@ -80,6 +85,15 @@ export interface EngineAdapter {
      * Optional — adapters without a skills system can omit this.
      */
     reloadSkills?(): Promise<void>;
+    /**
+     * Hot-swap the reasoning/thinking level for live sessions —
+     * `off | minimal | low | medium | high | xhigh`. Updates the global
+     * extended-thinking budget (read per-turn by the OpenAI-compat / Grok /
+     * Ollama providers) and the Gemini-native default on cached agents, so the
+     * Cowork ReasoningLevelPicker takes effect on the next turn without a session
+     * restart. Optional — adapters without a thinking system can omit this.
+     */
+    setThinkingLevel?(level: string): Promise<void>;
     /**
      * Set the default visual grounding fallback configuration.
      */

package/dist/desktop-automation/automation-manager.js

@@ -320,6 +320,13 @@ export class DesktopAutomationManager extends EventEmitter {
             const nativeProvider = await this.createNativeProvider();
             if (nativeProvider) {
                 this.registerProvider(nativeProvider);
+                // The created provider registers under its own name (e.g. 'nutjs' on
+                // Linux when xdotool/xclip are unavailable). Also expose it under the
+                // requested 'native' key so the preferred-provider lookup resolves it
+                // instead of silently falling through to the mock provider.
+                if (!this.providers.has('native')) {
+                    this.providers.set('native', nativeProvider);
+                }
             }
         }
         // Try preferred provider first
@@ -689,6 +696,15 @@ export class DesktopAutomationManager extends EventEmitter {
                     return new WindowsNativeProvider({ wsl: false });
                 }
                 case 'linux': {
+                    // Prefer nut-js (libnut): it provides mouse/keyboard/screen control
+                    // without xdotool/xclip/wmctrl, which are frequently absent on minimal
+                    // or remote Linux desktops. Fall back to the xdotool-based provider
+                    // (which also does window management) only when libnut is unavailable.
+                    const { NutJsProvider } = await import('./nutjs-provider.js');
+                    const nut = new NutJsProvider();
+                    if (await nut.isAvailable()) {
+                        return nut;
+                    }
                     const { LinuxNativeProvider } = await import('./linux-native-provider.js');
                     return new LinuxNativeProvider();
                 }