RFC: Exec Tool Enhancement - PTY + Background Support

[liuy]

RFC: picoclaw Exec Tool Enhancement

Problem

picoclaw exec only supports synchronous execution, cannot handle long-running tasks and interactive scenarios.

Scenario Table

Scenario	PTY	Background
Long-running builds (docker build, cargo build)	❌	✅
Server processes (npm run dev)	❌	✅
Password input (sudo apt-upgrade)	✅	✅
Interactive Git (rebase -i)	✅	❌
Interactive REPL (python)	✅	❌
Container interaction (docker exec -it)	✅	❌
Coding Agent	⚠️ optional	✅

Exec Tool Definition

type ExecTool struct{}

type ExecRequest struct {
    // action
    Action string // "run" | "list" | "poll" | "read" | "write" | "kill"
    
    // run parameters
    Command   string
    PTY       bool
    Background bool
    Timeout   int
    Env      map[string]string
    
    // other action parameters
    SessionID string
    Data      string
}

Action Reference

Action	Description	Parameters
run	Execute command	command, pty, background, timeout
list	List all sessions	-
poll	Check session status	sessionId
read	Read output	sessionId
write	Send input	sessionId, data
kill	Terminate session	sessionId

Usage Examples

Background Task

// 1. Start docker build
exec({ action: "run", command: "docker build -t myapp .", background: true })
// Returns: { sessionId: "abc123" }

// 2. Check status
exec({ action: "poll", sessionId: "abc123" })
// Returns: { status: "running" }

// 3. Read output
exec({ action: "read", sessionId: "abc123" })
// Returns: { output: "Step 1/5: FROM node..." }

// 4. Kill
exec({ action: "kill", sessionId: "abc123" })

Interactive Password Input

// 1. Start sudo command
exec({ action: "run", command: "sudo apt-upgrade", pty: true, background: true })

// 2. Agent detects "Password:" in output
exec({ action: "read", sessionId: "def456" })
// Returns: { output: "[sudo] password for user: " }

// 3. Request password from user, then send
exec({ action: "write", sessionId: "def456", data: "mypassword\n" })

// 4. Continue execution
exec({ action: "poll", sessionId: "def456" })

Interactive REPL

// 1. Start python REPL
exec({ action: "run", command: "python", pty: true })

// 2. Send command
exec({ action: "write", sessionId: "ghi789", data: "print(hello)\n" })

// 3. Read output
exec({ action: "read", sessionId: "ghi789" })

Comparison with OpenClaw

Feature	OpenClaw	picoclaw (proposed)
exec	✅	✅ (enhanced)
pty param	✅	✅
background param	✅	✅
process management	separate process tool	single exec tool

OpenClaw uses two tools (exec + process). We propose a single exec tool with embedded process management via actions.