🤖 refactor: remove MUX_PROMPT/MUX_OUTPUT in favor of stdout/stderr

Replace the special environment file mechanism with standard Unix conventions:
- stdout: sent to agent as tool result
- stderr: shown to user in UI only (not sent to agent)

This simplifies the implementation and makes scripts work identically
whether run inside mux or directly from the command line.

_Generated with mux_

Change-Id: Idbb4b8006a81a92dd7676693002bd652ddd62e00
Signed-off-by: Thomas Kosiewski <[email protected]>

Author: ThomasK33

docs/scripts.md

@@ -61,7 +61,7 @@ To make your scripts effective AI tools:
    ```
 
 2. **Robustness**: Use `set -euo pipefail` to ensure the script fails loudly if something goes wrong, allowing the AI to catch the error.
-3. **Feedback**: Use `MUX_PROMPT` to guide the AI on what to do next if the script succeeds or fails (see below).
+3. **Clear Output**: Write structured output to stdout so the agent can understand results and take action.
 
 ## Usage
 
@@ -95,64 +95,49 @@ Scripts run with:
   - **Human**: Visible in the chat card.
   - **Agent**: Returned as the tool execution result.
 
-### Environment Variables
+### Standard Streams
 
-Scripts receive special environment variables for controlling cmux behavior and interacting with the agent:
+Scripts follow Unix conventions for output:
 
-#### `MUX_OUTPUT` (User Toasts)
+- **stdout**: Sent to the agent as the tool result. Use this for structured output the agent should act on.
+- **stderr**: Shown to the user in the UI but **not** sent to the agent. Use this for progress messages, logs, or debugging info that doesn't need AI attention.
 
-Path to a temporary file for custom toast display content. Write markdown here for rich formatting in the UI toast:
+This design means scripts work identically whether run inside mux or directly from the command line.
 
-```bash
-#!/usr/bin/env bash
-# Description: Deploy with custom output
-
-echo "Deploying..." # Logged to stdout
-
-# Write formatted output for toast display
-cat >> "$MUX_OUTPUT" << 'EOF'
-## 🚀 Deployment Complete
-
-✅ Successfully deployed to staging
-EOF
-```
-
-#### `MUX_PROMPT` (Agent Feedback)
-
-Path to a temporary file for **sending messages back to the agent**. This is powerful for "Human-in-the-loop" or "Chain-of-thought" workflows where a script performs an action and then asks the agent to analyze the result.
+#### Example: Test Runner
 
 ```bash
 #!/usr/bin/env bash
-# Description: Run tests and ask Agent to fix failures
+# Description: Run tests and report failures for the agent to fix
+
+set -euo pipefail
 
-if ! npm test > test.log 2>&1; then
-  echo "❌ Tests failed" >> "$MUX_OUTPUT"
+# Progress to stderr (user sees it, agent doesn't)
+echo "Running test suite..." >&2
 
-  # Feed the failure log back to the agent automatically
-  cat >> "$MUX_PROMPT" << EOF
-The test suite failed. Here is the log:
+if npm test > test.log 2>&1; then
+  # Success message to stdout (agent sees it)
+  echo "✅ All tests passed"
+else
+  # Structured failure info to stdout (agent sees and can act on it)
+  cat << EOF
+❌ Tests failed. Here is the log:
 
 \`\`\`
 $(cat test.log)
 \`\`\`
 
 Please analyze this error and propose a fix.
 EOF
+  exit 1
 fi
 ```
 
 **Result**:
 
-1. Script fails.
-2. Agent receives the tool output (stderr/stdout) **PLUS** the content of `MUX_PROMPT` as part of the tool result.
-3. Agent can immediately act on the instructions in `MUX_PROMPT`.
-
-**Note**: If a human ran the script, the content of `MUX_PROMPT` is sent as a **new user message** to the agent, triggering a conversation.
-
-### File Size Limits
-
-- **MUX_OUTPUT**: Maximum 10KB (truncated if exceeded)
-- **MUX_PROMPT**: Maximum 100KB (truncated if exceeded)
+1. User sees "Running test suite..." progress message.
+2. On failure, agent receives the structured error with test log and instructions.
+3. Agent can immediately analyze and propose fixes.
 
 ## Example Scripts
 

src/browser/components/Messages/ScriptExecutionMessage.tsx

@@ -96,25 +96,11 @@ export const ScriptExecutionMessage: React.FC<ScriptExecutionMessageProps> = ({
 
           {!isPending && result.output && (
             <DetailSection>
-              <DetailLabel>Stdout / Stderr</DetailLabel>
+              <DetailLabel>Output (agent-visible)</DetailLabel>
               <DetailContent>{result.output}</DetailContent>
             </DetailSection>
           )}
 
-          {!isPending && result.outputFile && (
-            <DetailSection>
-              <DetailLabel>MUX_OUTPUT</DetailLabel>
-              <DetailContent>{result.outputFile}</DetailContent>
-            </DetailSection>
-          )}
-
-          {!isPending && result.promptFile && (
-            <DetailSection>
-              <DetailLabel>MUX_PROMPT</DetailLabel>
-              <DetailContent>{result.promptFile}</DetailContent>
-            </DetailSection>
-          )}
-
           {!isPending && result.truncated && (
             <DetailSection>
               <DetailLabel>Truncation</DetailLabel>

src/browser/utils/messages/modelMessageTransform.ts

@@ -204,8 +204,7 @@ export function injectModeTransition(
  * Logic:
  * - Identifies messages with metadata.muxMetadata.type === "script-execution"
  * - Replaces them with a simple user text message
- * - Content format: "Script '<name>' executed (exit code <N>).\nStdout/Stderr:\n<output>"
- * - Explicitly EXCLUDES the full MUX_OUTPUT and MUX_PROMPT content to save tokens
+ * - Content format: "Script '<name>' executed (exit code <N>).\nOutput:\n<output>"
  * - Preserves the rest of the message structure (id, role, other metadata)
  */
 export function transformScriptMessagesForLLM(messages: MuxMessage[]): MuxMessage[] {
@@ -227,25 +226,21 @@ export function transformScriptMessagesForLLM(messages: MuxMessage[]): MuxMessag
 
     let llmContent = `Script '${scriptMeta.scriptName}' executed (exit code ${result.exitCode}).`;
 
-    // Include Stdout/Stderr if present
+    // Include output if present (this is stdout which is agent-visible)
     if (result.output) {
-      llmContent += `\nStdout/Stderr:\n${result.output}`;
+      llmContent += `\nOutput:\n${result.output}`;
     } else {
-      llmContent += `\nStdout/Stderr: (no output)`;
+      llmContent += `\nOutput: (no output)`;
     }
 
-    // Surface script errors for Codex/LLM reviewers even when no output exists.
+    // Surface script errors for LLM reviewers even when no output exists.
     if ("error" in result) {
       const trimmedError = result.error.trim();
       if (trimmedError.length > 0) {
         llmContent += `\nError:\n${trimmedError}`;
       }
     }
 
-    // EXCLUDE MUX_OUTPUT and MUX_PROMPT from the LLM context for the script message itself.
-    // MUX_PROMPT is sent as a separate user message by ChatInput, so including it here would be duplication.
-    // MUX_OUTPUT is intended for user toasts, not LLM context.
-
     return [
       {
         ...msg,

src/browser/utils/messages/transformScriptMessagesForLLM.test.ts

@@ -4,7 +4,7 @@ import type { MuxMessage } from "@/common/types/message";
 import type { BashToolResult } from "@/common/types/tools";
 
 describe("transformScriptMessagesForLLM", () => {
-  it("should include stdout/stderr in script execution messages", () => {
+  it("should include output in script execution messages", () => {
     const scriptResult: BashToolResult = {
       success: true,
       output: "some stdout output",
@@ -38,34 +38,32 @@ describe("transformScriptMessagesForLLM", () => {
     expect(textPart.type).toBe("text");
     if (textPart.type === "text") {
       expect(textPart.text).toContain("Script 'test.sh' executed");
-      expect(textPart.text).toContain("Stdout/Stderr:");
+      expect(textPart.text).toContain("Output:");
       expect(textPart.text).toContain("some stdout output");
     }
   });
 
-  it("should exclude MUX_OUTPUT and MUX_PROMPT from script execution messages (avoid duplication)", () => {
+  it("should show (no output) when script has empty stdout", () => {
     const scriptResult: BashToolResult = {
       success: true,
-      output: "stdout stuff",
+      output: "",
       exitCode: 0,
       wall_duration_ms: 100,
-      outputFile: "User toast",
-      promptFile: "Model prompt",
     };
 
     const messages: MuxMessage[] = [
       {
-        id: "script-all",
+        id: "script-empty",
         role: "user",
-        parts: [{ type: "text", text: "Executed script: /script all" }],
+        parts: [{ type: "text", text: "Executed script: /script empty" }],
         metadata: {
           muxMetadata: {
             type: "script-execution",
-            id: "script-all",
+            id: "script-empty",
             historySequence: 0,
             timestamp: 123,
-            command: "/script all",
-            scriptName: "all.sh",
+            command: "/script empty",
+            scriptName: "empty.sh",
             args: [],
             result: scriptResult,
           },
@@ -78,10 +76,7 @@ describe("transformScriptMessagesForLLM", () => {
     const textPart = result[0].parts[0];
     expect(textPart.type).toBe("text");
     if (textPart.type === "text") {
-      expect(textPart.text).not.toContain("MUX_OUTPUT");
-      expect(textPart.text).not.toContain("User toast");
-      expect(textPart.text).not.toContain("MUX_PROMPT");
-      expect(textPart.text).not.toContain("Model prompt");
+      expect(textPart.text).toContain("Output: (no output)");
     }
   });
 
@@ -118,7 +113,7 @@ describe("transformScriptMessagesForLLM", () => {
     const textPart = result[0].parts[0];
     expect(textPart.type).toBe("text");
     if (textPart.type === "text") {
-      expect(textPart.text).toContain("Stdout/Stderr: (no output)");
+      expect(textPart.text).toContain("Output: (no output)");
       expect(textPart.text).toContain("Error:");
       expect(textPart.text).toContain("Permission denied");
     }

src/common/types/tools.ts

@@ -25,8 +25,6 @@ export type BashToolResult =
         reason: string;
         totalLines: number;
       };
-      outputFile?: string; // Content from MUX_OUTPUT env file
-      promptFile?: string; // Content from MUX_PROMPT env file
     })
   | (CommonBashFields & {
       success: false;
@@ -38,8 +36,6 @@ export type BashToolResult =
         reason: string;
         totalLines: number;
       };
-      outputFile?: string; // Content from MUX_OUTPUT env file
-      promptFile?: string; // Content from MUX_PROMPT env file
     });
 
 // File Read Tool Types

src/common/utils/tools/tools.test.ts

@@ -117,7 +117,7 @@ describe("getToolsForModel", () => {
     expect(demoTool).toBeDefined();
   });
 
-  it("should include MUX_PROMPT and MUX_OUTPUT in tool result", async () => {
+  it("should return stdout as agent-visible output", async () => {
     const mockScripts = [
       {
         name: "diagnose",
@@ -134,14 +134,12 @@ describe("getToolsForModel", () => {
       success: true,
       data: {
         exitCode: 0,
-        stdout: "Standard output",
+        stdout: "Standard output from script",
         stderr: "",
-        outputFileContent: "User notification",
-        promptFileContent: "Agent instruction",
         toolResult: {
           success: true,
           exitCode: 0,
-          output: "",
+          output: "Standard output from script",
           wall_duration_ms: 1000,
         },
       },
@@ -171,9 +169,98 @@ describe("getToolsForModel", () => {
       })
     );
 
-    expect(result).toContain("Standard output");
-    expect(result).toContain("--- MUX_OUTPUT ---\nUser notification");
-    expect(result).toContain("--- MUX_PROMPT ---\nAgent instruction");
+    expect(result).toContain("Standard output from script");
+    // stderr is frontend-only, should not appear in result on success
+    expect(result).not.toContain("Error:");
+  });
+
+  it("should return (no stdout) when script produces no output", async () => {
+    const mockScripts = [
+      {
+        name: "silent",
+        description: "Silent script",
+        isExecutable: true,
+      },
+    ];
+
+    const mockListScripts = listScripts as unknown as Mock<typeof listScripts>;
+    mockListScripts.mockResolvedValue(mockScripts);
+
+    const mockRunScript = runWorkspaceScript as unknown as Mock<typeof runWorkspaceScript>;
+    mockRunScript.mockResolvedValue({
+      success: true,
+      data: {
+        exitCode: 0,
+        stdout: "",
+        stderr: "",
+        toolResult: {
+          success: true,
+          exitCode: 0,
+          output: "",
+          wall_duration_ms: 100,
+        },
+      },
+    });
+
+    const tools = await getToolsForModel(
+      "anthropic:claude-3-5-sonnet",
+      config,
+      "workspace-id",
+      mockInitStateManager
+    );
+
+    const silentTool = tools.script_silent as unknown as {
+      execute: (args: { args: string[] }) => Promise<string>;
+    };
+    const result = await silentTool.execute({ args: [] });
+
+    expect(result).toBe("(no stdout)");
+  });
+
+  it("should include stderr in result only on non-zero exit", async () => {
+    const mockScripts = [
+      {
+        name: "failing",
+        description: "Failing script",
+        isExecutable: true,
+      },
+    ];
+
+    const mockListScripts = listScripts as unknown as Mock<typeof listScripts>;
+    mockListScripts.mockResolvedValue(mockScripts);
+
+    const mockRunScript = runWorkspaceScript as unknown as Mock<typeof runWorkspaceScript>;
+    mockRunScript.mockResolvedValue({
+      success: true,
+      data: {
+        exitCode: 1,
+        stdout: "",
+        stderr: "Something went wrong",
+        toolResult: {
+          success: false,
+          exitCode: 1,
+          output: "",
+          error: "Something went wrong",
+          wall_duration_ms: 100,
+        },
+      },
+    });
+
+    const tools = await getToolsForModel(
+      "anthropic:claude-3-5-sonnet",
+      config,
+      "workspace-id",
+      mockInitStateManager
+    );
+
+    const failingTool = tools.script_failing as unknown as {
+      execute: (args: { args: string[] }) => Promise<string>;
+    };
+    const result = await failingTool.execute({ args: [] });
+
+    expect(result).toContain("(no stdout)");
+    expect(result).toContain("Error: Something went wrong");
+    expect(result).toContain("(Exit Code: 1)");
   });
 
   it("should handle script discovery failure gracefully", async () => {