@phuetz/code-buddy 0.1.25 → 0.2.0

package/dist/security/write-policy.d.ts

@@ -0,0 +1,57 @@
+/**
+ * WritePolicy — enforces diff-first writes at the tool-handler level.
+ *
+ * Modes:
+ *   strict  — blocks any direct file write; the caller must use applyPatch()
+ *   confirm — allows writes but records a decision event in RunStore (existing confirmation UX)
+ *   off     — no restriction (current default behaviour)
+ *
+ * The singleton is injectable for tests via WritePolicy.setInstance().
+ */
+export type WritePolicyMode = 'strict' | 'confirm' | 'off';
+export interface WriteOperation {
+    /** Tool name triggering the write */
+    toolName: string;
+    /** File path(s) being written */
+    paths: string[];
+    /** Patch content if already prepared */
+    patch?: string;
+    /** Short description for decision log */
+    description?: string;
+}
+export interface GateResult {
+    allowed: boolean;
+    /** True if the caller must route through applyPatch() */
+    requiresPatch: boolean;
+    reason?: string;
+}
+export declare const WRITE_TOOL_NAMES: Set<string>;
+export declare class WritePolicy {
+    private static _instance;
+    private mode;
+    private listeners;
+    static getInstance(): WritePolicy;
+    /** Replace the singleton (for testing). */
+    static setInstance(instance: WritePolicy): void;
+    static resetInstance(): void;
+    setMode(mode: WritePolicyMode): void;
+    getMode(): WritePolicyMode;
+    /**
+     * Check whether the operation is allowed under the current policy.
+     *
+     * Called by tool-handler before executing str_replace_editor / create_file / multi_edit.
+     *
+     * @param operation - The write operation being attempted
+     * @param runId - Active run ID for decision logging (optional)
+     */
+    gate(operation: WriteOperation, _runId?: string): Promise<GateResult>;
+    /**
+     * Returns true if the tool name is subject to write-policy gating.
+     */
+    isWriteTool(toolName: string): boolean;
+    /**
+     * Subscribe to gate decisions (for RunStore integration).
+     */
+    onGate(listener: (op: WriteOperation, result: GateResult) => void): void;
+    private notifyListeners;
+}

package/dist/security/write-policy.js

@@ -0,0 +1,117 @@
+/**
+ * WritePolicy — enforces diff-first writes at the tool-handler level.
+ *
+ * Modes:
+ *   strict  — blocks any direct file write; the caller must use applyPatch()
+ *   confirm — allows writes but records a decision event in RunStore (existing confirmation UX)
+ *   off     — no restriction (current default behaviour)
+ *
+ * The singleton is injectable for tests via WritePolicy.setInstance().
+ */
+import { logger } from '../utils/logger.js';
+// ──────────────────────────────────────────────────────────────────
+// Tool names that trigger write-policy gating
+// ──────────────────────────────────────────────────────────────────
+export const WRITE_TOOL_NAMES = new Set([
+    'str_replace_editor',
+    'create_file',
+    'multi_edit',
+    'apply_patch',
+    'edit_file', // Morph Fast Apply
+    'write_file',
+]);
+// ──────────────────────────────────────────────────────────────────
+// WritePolicy
+// ──────────────────────────────────────────────────────────────────
+export class WritePolicy {
+    static _instance = null;
+    mode = 'confirm';
+    listeners = [];
+    // ── Singleton ────────────────────────────────────────────────
+    static getInstance() {
+        if (!WritePolicy._instance) {
+            WritePolicy._instance = new WritePolicy();
+        }
+        return WritePolicy._instance;
+    }
+    /** Replace the singleton (for testing). */
+    static setInstance(instance) {
+        WritePolicy._instance = instance;
+    }
+    static resetInstance() {
+        WritePolicy._instance = null;
+    }
+    // ── Configuration ─────────────────────────────────────────────
+    setMode(mode) {
+        this.mode = mode;
+        logger.debug(`WritePolicy: mode set to ${mode}`);
+    }
+    getMode() {
+        return this.mode;
+    }
+    // ── Gating ────────────────────────────────────────────────────
+    /**
+     * Check whether the operation is allowed under the current policy.
+     *
+     * Called by tool-handler before executing str_replace_editor / create_file / multi_edit.
+     *
+     * @param operation - The write operation being attempted
+     * @param runId - Active run ID for decision logging (optional)
+     */
+    async gate(operation, _runId) {
+        const { toolName } = operation;
+        // apply_patch is always allowed — it IS the diff-first path
+        if (toolName === 'apply_patch') {
+            return { allowed: true, requiresPatch: false };
+        }
+        switch (this.mode) {
+            case 'off':
+                return { allowed: true, requiresPatch: false };
+            case 'confirm': {
+                // In confirm mode, direct writes are allowed but we log the decision
+                const result = { allowed: true, requiresPatch: false };
+                this.notifyListeners(operation, result);
+                return result;
+            }
+            case 'strict': {
+                // In strict mode, block direct writes if no patch is provided
+                if (operation.patch) {
+                    // Caller has already produced a patch — allow it
+                    return { allowed: true, requiresPatch: false };
+                }
+                const result = {
+                    allowed: false,
+                    requiresPatch: true,
+                    reason: `WritePolicy (strict): tool "${toolName}" attempted a direct file write. Use apply_patch with a unified diff instead.`,
+                };
+                this.notifyListeners(operation, result);
+                logger.info(`WritePolicy blocked: ${toolName}`, { paths: operation.paths });
+                return result;
+            }
+        }
+    }
+    /**
+     * Returns true if the tool name is subject to write-policy gating.
+     */
+    isWriteTool(toolName) {
+        return WRITE_TOOL_NAMES.has(toolName);
+    }
+    // ── Observability ─────────────────────────────────────────────
+    /**
+     * Subscribe to gate decisions (for RunStore integration).
+     */
+    onGate(listener) {
+        this.listeners.push(listener);
+    }
+    notifyListeners(op, result) {
+        for (const l of this.listeners) {
+            try {
+                l(op, result);
+            }
+            catch {
+                // Ignore listener errors
+            }
+        }
+    }
+}
+//# sourceMappingURL=write-policy.js.map

package/dist/security/write-policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"write-policy.js","sourceRoot":"","sources":["../../src/security/write-policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AA0B5C,qEAAqE;AACrE,8CAA8C;AAC9C,qEAAqE;AAErE,MAAM,CAAC,MAAM,gBAAgB,GAAG,IAAI,GAAG,CAAC;IACtC,oBAAoB;IACpB,aAAa;IACb,YAAY;IACZ,aAAa;IACb,WAAW,EAAM,mBAAmB;IACpC,YAAY;CACb,CAAC,CAAC;AAEH,qEAAqE;AACrE,cAAc;AACd,qEAAqE;AAErE,MAAM,OAAO,WAAW;IACd,MAAM,CAAC,SAAS,GAAuB,IAAI,CAAC;IAE5C,IAAI,GAAoB,SAAS,CAAC;IAClC,SAAS,GAA4D,EAAE,CAAC;IAEhF,gEAAgE;IAEhE,MAAM,CAAC,WAAW;QAChB,IAAI,CAAC,WAAW,CAAC,SAAS,EAAE,CAAC;YAC3B,WAAW,CAAC,SAAS,GAAG,IAAI,WAAW,EAAE,CAAC;QAC5C,CAAC;QACD,OAAO,WAAW,CAAC,SAAS,CAAC;IAC/B,CAAC;IAED,2CAA2C;IAC3C,MAAM,CAAC,WAAW,CAAC,QAAqB;QACtC,WAAW,CAAC,SAAS,GAAG,QAAQ,CAAC;IACnC,CAAC;IAED,MAAM,CAAC,aAAa;QAClB,WAAW,CAAC,SAAS,GAAG,IAAI,CAAC;IAC/B,CAAC;IAED,iEAAiE;IAEjE,OAAO,CAAC,IAAqB;QAC3B,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC;QACjB,MAAM,CAAC,KAAK,CAAC,4BAA4B,IAAI,EAAE,CAAC,CAAC;IACnD,CAAC;IAED,OAAO;QACL,OAAO,IAAI,CAAC,IAAI,CAAC;IACnB,CAAC;IAED,iEAAiE;IAEjE;;;;;;;OAOG;IACH,KAAK,CAAC,IAAI,CAAC,SAAyB,EAAE,MAAe;QACnD,MAAM,EAAE,QAAQ,EAAE,GAAG,SAAS,CAAC;QAE/B,4DAA4D;QAC5D,IAAI,QAAQ,KAAK,aAAa,EAAE,CAAC;YAC/B,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;QACjD,CAAC;QAED,QAAQ,IAAI,CAAC,IAAI,EAAE,CAAC;YAClB,KAAK,KAAK;gBACR,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;YAEjD,KAAK,SAAS,CAAC,CAAC,CAAC;gBACf,qEAAqE;gBACrE,MAAM,MAAM,GAAe,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;gBACnE,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;gBACxC,OAAO,MAAM,CAAC;YAChB,CAAC;YAED,KAAK,QAAQ,CAAC,CAAC,CAAC;gBACd,8DAA8D;gBAC9D,IAAI,SAAS,CAAC,KAAK,EAAE,CAAC;oBACpB,iDAAiD;oBACjD,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,KAAK,EAAE,CAAC;gBACjD,CAAC;gBAED,MAAM,MAAM,GAAe;oBACzB,OAAO,EAAE,KAAK;oBACd,aAAa,EAAE,IAAI;oBACnB,MAAM,EAAE,+BAA+B,QAAQ,+EAA+E;iBAC/H,CAAC;gBACF,IAAI,CAAC,eAAe,CAAC,SAAS,EAAE,MAAM,CAAC,CAAC;gBACxC,MAAM,CAAC,IAAI,CAAC,wBAAwB,QAAQ,EAAE,EAAE,EAAE,KAAK,EAAE,SAAS,CAAC,KAAK,EAAE,CAAC,CAAC;gBAC5E,OAAO,MAAM,CAAC;YAChB,CAAC;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACH,WAAW,CAAC,QAAgB;QAC1B,OAAO,gBAAgB,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC;IACxC,CAAC;IAED,iEAAiE;IAEjE;;OAEG;IACH,MAAM,CAAC,QAA0D;QAC/D,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC;IAChC,CAAC;IAEO,eAAe,CAAC,EAAkB,EAAE,MAAkB;QAC5D,KAAK,MAAM,CAAC,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;YAC/B,IAAI,CAAC;gBACH,CAAC,CAAC,EAAE,EAAE,MAAM,CAAC,CAAC;YAChB,CAAC;YAAC,MAAM,CAAC;gBACP,yBAAyB;YAC3B,CAAC;QACH,CAAC;IACH,CAAC"}

package/dist/services/prompt-builder.js

@@ -118,8 +118,45 @@ export class PromptBuilder {
             catch (err) {
                 logger.warn("Failed to load bootstrap context", { error: getErrorMessage(err) });
             }
+            // Inject workflow orchestration rules (concrete plan triggers, verification contract, etc.)
+            try {
+                const { getWorkflowRulesBlock } = await import('../prompts/workflow-rules.js');
+                systemPrompt += '\n\n' + getWorkflowRulesBlock();
+                logger.debug('Injected workflow orchestration rules into system prompt');
+            }
+            catch (err) {
+                logger.warn('Failed to inject workflow rules', { error: getErrorMessage(err) });
+            }
+            // Manus AI structured variation — shuffle reminder blocks to prevent
+            // the model from falling into brittle repetition patterns.
+            // Only the footer guideline section is varied; the preamble/tools are left
+            // untouched so prompt caching remains effective on the stable prefix.
+            try {
+                const { varySystemPrompt } = await import('../prompts/variation-injector.js');
+                // Use a daily seed so the variation is stable within a single day
+                // (same day → same order → consistent cache), but rotates across days.
+                const daySeed = Math.floor(Date.now() / 86_400_000);
+                systemPrompt = varySystemPrompt(systemPrompt, {
+                    seed: daySeed,
+                    shuffleOrder: true,
+                    alternativePhrasing: true,
+                    variationRate: 0.3,
+                });
+            }
+            catch {
+                // non-critical — proceed with original prompt
+            }
             // Cache system prompt for optimization
             this.promptCacheManager.cacheSystemPrompt(systemPrompt);
+            // Store stable/dynamic split for cache-breakpoint injection (Manus AI #11/#20)
+            try {
+                const { buildStableDynamicSplit } = await import('../optimization/cache-breakpoints.js');
+                const split = buildStableDynamicSplit(systemPrompt);
+                // The split is used by the client to inject cache_control breakpoints.
+                // Attach it to the PromptCacheManager for inspection if needed.
+                this.promptCacheManager._stableDynamicSplit = split;
+            }
+            catch { /* non-critical */ }
             return systemPrompt;
         }
         catch (error) {

package/dist/services/prompt-builder.js.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-builder.js","sourceRoot":"","sources":["../../src/services/prompt-builder.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"prompt-builder.js","sourceRoot":"","sources":["../../src/services/prompt-builder.ts"],"names":[],"mappings":"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"}

package/dist/themes/theme-schema.d.ts

@@ -12,14 +12,14 @@ export declare const avatarConfigSchema: z.ZodObject<{
     tool: z.ZodString;
     system: z.ZodString;
 }, "strip", z.ZodTypeAny, {
+    system: string;
     user: string;
     assistant: string;
-    system: string;
     tool: string;
 }, {
+    system: string;
     user: string;
     assistant: string;
-    system: string;
     tool: string;
 }>;
 /**
@@ -178,14 +178,14 @@ export declare const themeSchema: z.ZodObject<{
         tool: z.ZodString;
         system: z.ZodString;
     }, "strip", z.ZodTypeAny, {
+        system: string;
         user: string;
         assistant: string;
-        system: string;
         tool: string;
     }, {
+        system: string;
         user: string;
         assistant: string;
-        system: string;
         tool: string;
     }>;
     isBuiltin: z.ZodBoolean;
@@ -220,9 +220,9 @@ export declare const themeSchema: z.ZodObject<{
         codeBackground?: string | undefined;
     };
     avatars: {
+        system: string;
         user: string;
         assistant: string;
-        system: string;
         tool: string;
     };
     isBuiltin: boolean;
@@ -257,9 +257,9 @@ export declare const themeSchema: z.ZodObject<{
         codeBackground?: string | undefined;
     };
     avatars: {
+        system: string;
         user: string;
         assistant: string;
-        system: string;
         tool: string;
     };
     isBuiltin: boolean;
@@ -277,14 +277,14 @@ export declare const themePreferencesSchema: z.ZodObject<{
         tool: z.ZodOptional<z.ZodString>;
         system: z.ZodOptional<z.ZodString>;
     }, "strip", z.ZodTypeAny, {
+        system?: string | undefined;
         user?: string | undefined;
         assistant?: string | undefined;
-        system?: string | undefined;
         tool?: string | undefined;
     }, {
+        system?: string | undefined;
         user?: string | undefined;
         assistant?: string | undefined;
-        system?: string | undefined;
         tool?: string | undefined;
     }>>;
     customColors: z.ZodOptional<z.ZodObject<{
@@ -360,9 +360,9 @@ export declare const themePreferencesSchema: z.ZodObject<{
 }, "strip", z.ZodTypeAny, {
     activeTheme: string;
     customAvatars?: {
+        system?: string | undefined;
         user?: string | undefined;
         assistant?: string | undefined;
-        system?: string | undefined;
         tool?: string | undefined;
     } | undefined;
     customColors?: {
@@ -392,9 +392,9 @@ export declare const themePreferencesSchema: z.ZodObject<{
 }, {
     activeTheme: string;
     customAvatars?: {
+        system?: string | undefined;
         user?: string | undefined;
         assistant?: string | undefined;
-        system?: string | undefined;
         tool?: string | undefined;
     } | undefined;
     customColors?: {

package/dist/tools/ask-human-tool.d.ts

@@ -0,0 +1,62 @@
+/**
+ * AskHuman Tool (OpenManus-inspired)
+ *
+ * Allows the agent to pause mid-task and ask the user a clarifying
+ * question. In CLI mode this blocks on readline. In non-interactive
+ * environments it returns a timeout message so the agent can proceed
+ * with a best-effort answer.
+ *
+ * The LLM should call this tool when:
+ *  - It needs information that cannot be inferred from context
+ *  - Multiple valid interpretations exist and the wrong one would waste effort
+ *  - A destructive or irreversible action requires explicit human sign-off
+ */
+import type { ToolResult } from '../types/index.js';
+export interface AskHumanInput {
+    /** The question to ask the user */
+    question: string;
+    /** Optional suggested options (presented as a numbered list) */
+    options?: string[];
+    /** Timeout in seconds before the tool returns a default answer (default: 120) */
+    timeout?: number;
+    /** Default answer returned on timeout (default: "no answer provided, use best judgement") */
+    default?: string;
+}
+export declare class AskHumanTool {
+    /**
+     * Pause agent execution and ask the human a question.
+     * Returns the user's typed response as the tool output.
+     */
+    execute(input: AskHumanInput): Promise<ToolResult>;
+    getSchema(): {
+        name: string;
+        description: string;
+        parameters: {
+            type: "object";
+            properties: {
+                question: {
+                    type: string;
+                    description: string;
+                };
+                options: {
+                    type: string;
+                    items: {
+                        type: string;
+                    };
+                    description: string;
+                };
+                timeout: {
+                    type: string;
+                    description: string;
+                };
+                default: {
+                    type: string;
+                    description: string;
+                };
+            };
+            required: string[];
+        };
+    };
+}
+export declare function getAskHumanTool(): AskHumanTool;
+export declare function resetAskHumanTool(): void;

package/dist/tools/ask-human-tool.js

@@ -0,0 +1,112 @@
+/**
+ * AskHuman Tool (OpenManus-inspired)
+ *
+ * Allows the agent to pause mid-task and ask the user a clarifying
+ * question. In CLI mode this blocks on readline. In non-interactive
+ * environments it returns a timeout message so the agent can proceed
+ * with a best-effort answer.
+ *
+ * The LLM should call this tool when:
+ *  - It needs information that cannot be inferred from context
+ *  - Multiple valid interpretations exist and the wrong one would waste effort
+ *  - A destructive or irreversible action requires explicit human sign-off
+ */
+import * as readline from 'readline';
+export class AskHumanTool {
+    /**
+     * Pause agent execution and ask the human a question.
+     * Returns the user's typed response as the tool output.
+     */
+    async execute(input) {
+        const { question, options, timeout = 120, default: defaultAnswer = 'No answer provided – use your best judgement and continue.', } = input;
+        // Detect non-interactive environments
+        if (!process.stdin.isTTY) {
+            return {
+                success: true,
+                output: defaultAnswer,
+            };
+        }
+        return new Promise((resolve) => {
+            const rl = readline.createInterface({
+                input: process.stdin,
+                output: process.stdout,
+                terminal: true,
+            });
+            let prompt = `\n🤔 Agent needs your input:\n${question}\n`;
+            if (options && options.length > 0) {
+                prompt += '\nOptions:\n';
+                options.forEach((opt, i) => {
+                    prompt += `  ${i + 1}. ${opt}\n`;
+                });
+                prompt += '\nEnter your choice (number or free text): ';
+            }
+            else {
+                prompt += '\nYour answer: ';
+            }
+            // Auto-timeout
+            const timer = setTimeout(() => {
+                rl.close();
+                resolve({
+                    success: true,
+                    output: defaultAnswer,
+                });
+            }, timeout * 1000);
+            rl.question(prompt, (answer) => {
+                clearTimeout(timer);
+                rl.close();
+                // If user picked a number from the options list, expand it
+                if (options && options.length > 0) {
+                    const n = parseInt(answer.trim(), 10);
+                    if (!isNaN(n) && n >= 1 && n <= options.length) {
+                        resolve({ success: true, output: options[n - 1] });
+                        return;
+                    }
+                }
+                resolve({
+                    success: true,
+                    output: answer.trim() || defaultAnswer,
+                });
+            });
+        });
+    }
+    getSchema() {
+        return {
+            name: 'ask_human',
+            description: 'Pause execution and ask the user a clarifying question. Use when you need information that cannot be inferred from context, or when multiple interpretations would lead to very different outcomes. Returns the human\'s typed response.',
+            parameters: {
+                type: 'object',
+                properties: {
+                    question: {
+                        type: 'string',
+                        description: 'The question to ask the user (be concise and specific)',
+                    },
+                    options: {
+                        type: 'array',
+                        items: { type: 'string' },
+                        description: 'Optional list of suggested answers the user can pick from',
+                    },
+                    timeout: {
+                        type: 'number',
+                        description: 'Seconds to wait before returning a default answer (default: 120)',
+                    },
+                    default: {
+                        type: 'string',
+                        description: 'Default answer to return if the user does not respond in time',
+                    },
+                },
+                required: ['question'],
+            },
+        };
+    }
+}
+let instance = null;
+export function getAskHumanTool() {
+    if (!instance) {
+        instance = new AskHumanTool();
+    }
+    return instance;
+}
+export function resetAskHumanTool() {
+    instance = null;
+}
+//# sourceMappingURL=ask-human-tool.js.map

package/dist/tools/ask-human-tool.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ask-human-tool.js","sourceRoot":"","sources":["../../src/tools/ask-human-tool.ts"],"names":[],"mappings":"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"}

package/dist/tools/bash/bash-tool.d.ts

@@ -77,6 +77,21 @@ export declare class BashTool implements Disposable {
      * Parses command arguments to identify file targets of rm, mv, etc.
      */
     private checkpointDestructiveTargets;
+    /**
+     * Shell-free exec — Codex-inspired direct process execution.
+     *
+     * Executes a pre-parsed command token array via spawn with `shell: false`,
+     * bypassing shell interpretation entirely. Prevents shell injection when the
+     * caller has already validated / split the argument vector.
+     *
+     * Use this when the command has been parsed by bash-parser and you want to
+     * avoid double-interpretation through sh/bash.
+     *
+     * @param argv    - [command, ...args] token array (must have at least 1 element)
+     * @param timeout - Max execution time in ms (default: 30000)
+     * @param cwd     - Working directory (default: currentDirectory)
+     */
+    shellFreeExec(argv: string[], timeout?: number, cwd?: string): Promise<ToolResult>;
     /**
      * Enable or disable self-healing
      */

package/dist/tools/bash/bash-tool.js

@@ -412,6 +412,68 @@ export class BashTool {
             // Parsing failed — skip checkpointing (command already validated)
         }
     }
+    /**
+     * Shell-free exec — Codex-inspired direct process execution.
+     *
+     * Executes a pre-parsed command token array via spawn with `shell: false`,
+     * bypassing shell interpretation entirely. Prevents shell injection when the
+     * caller has already validated / split the argument vector.
+     *
+     * Use this when the command has been parsed by bash-parser and you want to
+     * avoid double-interpretation through sh/bash.
+     *
+     * @param argv    - [command, ...args] token array (must have at least 1 element)
+     * @param timeout - Max execution time in ms (default: 30000)
+     * @param cwd     - Working directory (default: currentDirectory)
+     */
+    async shellFreeExec(argv, timeout = 30000, cwd) {
+        if (!argv || argv.length === 0) {
+            return { success: false, error: 'shellFreeExec: argv must be non-empty' };
+        }
+        const [cmd, ...args] = argv;
+        const workDir = cwd ?? this.currentDirectory;
+        const filteredEnv = getFilteredEnv();
+        return new Promise((resolve) => {
+            let stdout = '';
+            let stderr = '';
+            let timedOut = false;
+            const proc = spawn(cmd, args, {
+                shell: false,
+                cwd: workDir,
+                env: filteredEnv,
+                stdio: ['ignore', 'pipe', 'pipe'],
+            });
+            const timer = setTimeout(() => {
+                timedOut = true;
+                proc.kill('SIGKILL');
+            }, timeout);
+            const maxBuf = 1024 * 1024;
+            proc.stdout?.on('data', (d) => {
+                if (stdout.length < maxBuf)
+                    stdout += d.toString();
+            });
+            proc.stderr?.on('data', (d) => {
+                if (stderr.length < maxBuf)
+                    stderr += d.toString();
+            });
+            proc.on('close', (code) => {
+                clearTimeout(timer);
+                if (timedOut) {
+                    resolve({ success: false, error: 'Command timed out' });
+                }
+                else if (code === 0) {
+                    resolve({ success: true, output: stdout.trim() || 'Done' });
+                }
+                else {
+                    resolve({ success: false, error: stderr.trim() || `Exit code ${code}` });
+                }
+            });
+            proc.on('error', (err) => {
+                clearTimeout(timer);
+                resolve({ success: false, error: err.message });
+            });
+        });
+    }
     /**
      * Enable or disable self-healing
      */