feat(tools): add exec tool enhancement with background execution and PTY support

[liuy]

Background

Before this patch, picoclaw's exec tool only supports synchronous execution - it blocks and waits for the command to complete before returning. This limits the agent from:

• Running long-running commands (docker build, cargo build)
• Handling interactive input (sudo passwords, TUI apps)
• Managing persistent processes

Core Logic Comparison

┌─────────────────────────────────────────────────────────────────────┐
│                    BEFORE (without this patch)                      │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Execute(command)                                                   │
│       │                                                             │
│       ▼                                                             │
│  ┌─────────┐                                                        │
│  │ runSync │◄── blocks until command completes                      │
│  └────┬────┘                                                        │
│       │                                                             │
│       ▼                                                             │
│  returns result (complete)                                          │
│                                                                     │
│  ❌ No background execution                                         │
│  ❌ No PTY support                                                  │
│  ❌ No session concept                                              │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────────────┐
│                    AFTER (with this patch)                          │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  Execute(action, command, background?, pty?)                        │
│       │                                                             │
│       ├──────────────────────────────────────────────┐              │
│       │                                              │              │
│   action=run                                    action≠run           │
│       │                                              │              │
│       ▼                                              ▼              │
│  background=true?                              poll/read/            │
│       │                                         write/kill           │
│   ┌───┴───┐                                         │              │
│   yes     no                                         │              │
│   │       │                                          │              │
│   ▼       ▼                                          │              │
│ runBg   runSync                               operate on SessionMgr  │
│   │       │                                          │              │
│   ▼       ▼                                          │              │
│ session + sessionId ──────────────────────────► lookup session      │
│   │                                                         │       │
│   ▼                                                         ▼       │
│ returns immediately ✅                               returns status  │
│                                              ✅ non-blocking        │
│                                                                     │
│  ✅ Background execution (background=true)                          │
│  ✅ PTY support (pty=true, for interactive input like sudo)         │
│  ✅ SessionManager manages all running processes                    │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Changes

New Files

• pkg/tools/session.go - SessionManager, ProcessSession
• pkg/tools/session_process_unix.go - Unix process group kill (Setpgid + SIGKILL)
• pkg/tools/session_process_windows.go - Windows fallback
• pkg/tools/session_test.go - session management tests

Modified Files

• pkg/tools/shell.go - action routing (run/list/poll/read/write/kill)
• pkg/tools/types.go - ExecRequest/ExecResponse types
• pkg/tools/shell_test.go - new tests
• go.mod - added creack/pty dependency

Tool Description Enhancements

Improved exec tool descriptions for better agent usability:

• poll action: Added return format {sessionId, status: running|done, exitCode}
• read action: Added return format {sessionId, output, status: running|done}
• timeout default: Changed from 60s to 0 (no timeout)
• keys separator: Added clarification "(optional spaces around comma)"
• Session lifecycle: Added auto-cleanup 30 min, output buffer 100MB
• pty+background: Added "(can combine with background=true)"
• write action: Added "(only when status=running)"

Local Testing

All tests passed locally:

• go test ./... - All packages pass
• golangci-lint run ./... - No issues

Test Case: Snake Game with PTY

Agent created a snake game using curses and played it via PTY session:

#!/usr/bin/env python3
"""贪吃蛇 - LLM 友好版，输出纯文本网格，使用 curses 处理输入"""

import curses
import random

# 游戏参数
WIDTH = 20
HEIGHT = 15
FRAME_MS = 1500

def render(snake, food, score, direction):
    """渲染游戏画面为纯文本网格"""
    # 创建空网格
    grid = [['.' for _ in range(WIDTH)] for _ in range(HEIGHT)]
    
    # 绘制边界
    for x in range(WIDTH):
        grid[0][x] = '#'
        grid[HEIGHT-1][x] = '#'
    for y in range(HEIGHT):
        grid[y][0] = '#'
        grid[y][WIDTH-1] = '#'
    
    # 绘制蛇
    for i, (y, x) in enumerate(snake):
        if i == 0:
            grid[y][x] = '@'  # 蛇头
        else:
            grid[y][x] = 'o'  # 蛇身
    
    # 绘制食物
    grid[food[0]][food[1]] = '*'
    
    # 方向翻译
    dir_map = {
        'up': '↑ 上',
        'down': '↓ 下',
        'left': '← 左',
        'right': '→ 右'
    }
    dir_display = dir_map.get(direction, direction)
    
    output = []
    output.append(f"=== 贪吃蛇游戏 | 得分: {score} | 方向: {dir_display} ===")
    output.append("")
    for row in grid:
        output.append(' '.join(row))
    output.append("")
    output.append("蛇头: @  蛇身: o  食物: *  空地: .  墙: #")
    output.append("控制: 方向键=移动 q=退出")
    output.append("")
    output.append(f"蛇头位置: ({snake[0][1]}, {snake[0][0]})")
    output.append(f"食物位置: ({food[1]}, {food[0]})")
    output.append(f"蛇长度: {len(snake)}")
    
    return '\n'.join(output)

def main(stdscr):
    # 设置非阻塞输入
    stdscr.nodelay(True)
    
    # 初始化蛇
    snake = [(5, 7)]  # 只有蛇头
    food = (3, 10)
    direction = 'right'
    score = 0
    
    while True:
        # 渲染画面（清屏 + 输出）
        stdscr.clear()
        stdscr.addstr(0, 0, render(snake, food, score, direction))
        stdscr.refresh()
        
        # 等待按键（非阻塞，每 50ms 检查一次）
        new_direction = direction
        for _ in range(FRAME_MS // 50):
            key = stdscr.getch()
            if key == ord('q'):
                return
            # 检测 curses.KEY_UP/DOWN/LEFT/RIGHT（依赖 terminfo）
            elif key == curses.KEY_UP and direction != 'down':
                new_direction = 'up'
            elif key == curses.KEY_DOWN and direction != 'up':
                new_direction = 'down'
            elif key == curses.KEY_LEFT and direction != 'right':
                new_direction = 'left'
            elif key == curses.KEY_RIGHT and direction != 'left':
                new_direction = 'right'
            
            curses.napms(50)  # 等待 50ms
        
        direction = new_direction
        
        # 计算新头部位置
        head_y, head_x = snake[0]
        if direction == 'up':
            head_y -= 1
        elif direction == 'down':
            head_y += 1
        elif direction == 'left':
            head_x -= 1
        elif direction == 'right':
            head_x += 1
        
        # 检查碰撞
        if (head_y <= 0 or head_y >= HEIGHT-1 or
            head_x <= 0 or head_x >= WIDTH-1 or
            (head_y, head_x) in snake):
            stdscr.clear()
            stdscr.addstr(0, 0, "游戏结束！")
            stdscr.addstr(1, 0, f"最终得分: {score}")
            stdscr.refresh()
            curses.napms(2000)
            break
        
        # 移动蛇
        snake.insert(0, (head_y, head_x))
        
        # 检查吃到食物
        if (head_y, head_x) == food:
            score += 10
            while True:
                food = (random.randint(1, HEIGHT-2), random.randint(1, WIDTH-2))
                if food not in snake:
                    break
        else:
            snake.pop()

if __name__ == "__main__":
    curses.wrapper(main)

Agent execution flow:

1. exec action=run command="python3 snake_curses.py" background=true pty=true → sessionId
2. exec action=read sessionId=xxx → see game screen
3. exec action=send-keys sessionId=xxx keys="right, down, left, up" → control snake
4. exec action=kill sessionId=xxx → end game

This demonstrates PTY support for interactive TUI applications.

Related Issue

Fixes #1733

[yinwm]

Code Review: ExitCode Handling Issue

I found one issue while reviewing this PR:

[CRITICAL] ExitCode is not properly captured

Location: pkg/tools/shell.go:566-573 and pkg/tools/shell.go:613-619

Problem: The current implementation only sets ExitCode to 0 or 1 based on cmd.ProcessState.Success(), losing the actual exit code:

if cmd.ProcessState.Success() {
    session.ExitCode = 0
} else {
    session.ExitCode = 1  // ❌ Should be cmd.ProcessState.ExitCode()
}

Impact: Cannot distinguish between different failure modes:

• OOM killed → exit code 137
• Segmentation fault → exit code 139
• Signal killed → exit code -1
• Custom exit codes → lost

Fix: Use cmd.ProcessState.ExitCode() to capture the actual exit code:

session.ExitCode = cmd.ProcessState.ExitCode()

---

Other minor observations (acceptable for this use case):

• Goroutine in NewSessionManager() runs for process lifetime - acceptable since it's a global singleton
• API change working_dir → cwd - acceptable since primarily LLM Agent usage
• 8-char session ID has 32-bit entropy - acceptable for expected concurrency levels

Overall: Great feature addition! The background execution and PTY support are well-designed.

[liuy]

Thanks for the review! Fixed the ExitCode issue - now using cmd.ProcessState.ExitCode() to capture the actual exit code. This correctly distinguishes:

• OOM killed (137)
• Segmentation fault (139)
• Signal killed (-1)
• Custom exit codes

[yinwm]

LGTM! The ExitCode issue has been fixed. Ready to merge.