fix: 修复 AI 回复无法送达发送者 + 重复消息 + action角色泄露 + OS环境支持

广播逻辑重构: - AI 回复 (stream_start/response/stream_segments/multi_message/stream_end) 改用 broadcastToUser 发送给所有客户端 - 用户消息回显保持 broadcastToUserExcept 排除发送者消息去重与角色修复: - CacheMessage(user) 移至回复生成后，避免本轮 LLM 调用出现重复用户消息 - action 角色消息在 DB 存储时映射为 assistant，DeepSeek 等模型不支持自定义角色 - stream_end defer 机制确保错误路径也会终止客户端思考指示器 OS 完整环境支持: - host 包重构为 HostBackend 接口 + Direct/WSL/Docker 三种后端 - 新增 os_exec/os_file/os_system 工具供 AI 在完整 Linux 环境中自由操作其他: - 视觉模型注入 + 图片预处理后清空 Images 避免传给 Chat 模型 - 图片 URL 相对路径→绝对 URL 转换 - DevTools 链路追踪页面 + 重启修复 - 记忆搜索模糊匹配增强 - 后台思考定时调度支持 - 管理后台页面 (模型配置/用户管理等) - docs/api 更新广播机制说明 Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-05-29 12:46:17 +08:00
parent aac64ed8b7
commit 91c9ee4b2d
49 changed files with 5032 additions and 299 deletions
@@ -0,0 +1,204 @@
+package host
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"runtime"
+	"strings"
+	"time"
+)
+
+// DirectBackend executes commands directly on the host via os/exec,
+// with command allowlist and directory restrictions for safety.
+type DirectBackend struct {
+	sandbox     *Sandbox
+	allowedDirs []string
+}
+
+// NewDirectBackend creates a host execution backend that runs commands
+// directly on the host machine with sandbox restrictions.
+func NewDirectBackend(sandbox *Sandbox) *DirectBackend {
+	b := &DirectBackend{sandbox: sandbox}
+	if sandbox != nil {
+		b.allowedDirs = sandbox.cfg.AllowedDirs
+	}
+	return b
+}
+
+func (b *DirectBackend) Name() string { return "direct" }
+
+// SetAllowedDirs updates the directories accessible for file operations.
+func (b *DirectBackend) SetAllowedDirs(dirs []string) {
+	b.allowedDirs = dirs
+	if b.sandbox != nil {
+		b.sandbox.cfg.AllowedDirs = dirs
+	}
+}
+
+// Exec runs a command in the sandbox.
+func (b *DirectBackend) Exec(ctx context.Context, command, workDir string, timeout time.Duration) (*ExecResult, error) {
+	return b.sandbox.Exec(ctx, command, workDir, timeout)
+}
+
+// ReadFile reads the contents of a file within allowed directories.
+func (b *DirectBackend) ReadFile(path string, maxBytes int) (string, error) {
+	if maxBytes <= 0 {
+		maxBytes = 1024 * 1024
+	}
+	if err := b.validatePath(path); err != nil {
+		return "", err
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		return "", fmt.Errorf("cannot stat file: %w", err)
+	}
+	if info.IsDir() {
+		return "", fmt.Errorf("path is a directory: %s", path)
+	}
+	if info.Size() > int64(maxBytes) {
+		return "", fmt.Errorf("file too large: %d bytes (max %d)", info.Size(), maxBytes)
+	}
+	data, err := os.ReadFile(path)
+	if err != nil {
+		return "", fmt.Errorf("cannot read file: %w", err)
+	}
+	if len(data) > maxBytes {
+		data = data[:maxBytes]
+	}
+	return string(data), nil
+}
+
+// WriteFile writes data to a file within allowed directories.
+func (b *DirectBackend) WriteFile(path, content string, maxBytes int) error {
+	if maxBytes <= 0 {
+		maxBytes = 1024 * 1024
+	}
+	if len(content) > maxBytes {
+		return fmt.Errorf("content too large: %d bytes (max %d)", len(content), maxBytes)
+	}
+	if err := b.validatePath(path); err != nil {
+		return err
+	}
+	dir := filepath.Dir(path)
+	if err := os.MkdirAll(dir, 0755); err != nil {
+		return fmt.Errorf("cannot create directory: %w", err)
+	}
+	return os.WriteFile(path, []byte(content), 0644)
+}
+
+// ListDir lists directory contents within allowed directories.
+func (b *DirectBackend) ListDir(path string) ([]DirEntry, error) {
+	if err := b.validatePath(path); err != nil {
+		return nil, err
+	}
+	entries, err := os.ReadDir(path)
+	if err != nil {
+		return nil, fmt.Errorf("cannot read directory: %w", err)
+	}
+	result := make([]DirEntry, 0, len(entries))
+	for _, e := range entries {
+		info, _ := e.Info()
+		size := int64(0)
+		modTime := time.Time{}
+		if info != nil {
+			size = info.Size()
+			modTime = info.ModTime()
+		}
+		result = append(result, DirEntry{
+			Name:    e.Name(),
+			IsDir:   e.IsDir(),
+			Size:    size,
+			ModTime: modTime.Format(time.RFC3339),
+		})
+	}
+	return result, nil
+}
+
+// SystemInfo returns basic system information.
+func (b *DirectBackend) SystemInfo() map[string]interface{} {
+	hostname, _ := os.Hostname()
+	wd, _ := os.Getwd()
+
+	info := map[string]interface{}{
+		"hostname":   hostname,
+		"os":         runtime.GOOS,
+		"arch":       runtime.GOARCH,
+		"num_cpu":    runtime.NumCPU(),
+		"go_version": runtime.Version(),
+		"work_dir":   wd,
+		"backend":    "direct",
+	}
+
+	if runtime.GOOS == "windows" {
+		cmd := exec.Command("systeminfo")
+		out, err := cmd.Output()
+		if err == nil {
+			lines := strings.Split(string(out), "\n")
+			for _, line := range lines {
+				line = strings.TrimSpace(line)
+				if strings.Contains(line, "Total Physical Memory") {
+					parts := strings.SplitN(line, ":", 2)
+					if len(parts) == 2 {
+						info["total_memory"] = strings.TrimSpace(parts[1])
+					}
+				}
+				if strings.Contains(line, "OS Name") {
+					parts := strings.SplitN(line, ":", 2)
+					if len(parts) == 2 {
+						info["os_name"] = strings.TrimSpace(parts[1])
+					}
+				}
+			}
+		}
+	} else {
+		if data, err := os.ReadFile("/proc/meminfo"); err == nil {
+			for _, line := range strings.Split(string(data), "\n") {
+				if strings.HasPrefix(line, "MemTotal:") {
+					info["total_memory"] = strings.TrimSpace(strings.TrimPrefix(line, "MemTotal:"))
+					break
+				}
+			}
+		}
+	}
+	return info
+}
+
+// DiskUsage returns disk usage for the given path.
+func (b *DirectBackend) DiskUsage(path string) (map[string]interface{}, error) {
+	if err := b.validatePath(path); err != nil {
+		return nil, err
+	}
+	info, err := os.Stat(path)
+	if err != nil {
+		return nil, fmt.Errorf("cannot stat path: %w", err)
+	}
+	return map[string]interface{}{
+		"path":     path,
+		"is_dir":   info.IsDir(),
+		"size":     info.Size(),
+		"mod_time": info.ModTime().Format(time.RFC3339),
+	}, nil
+}
+
+func (b *DirectBackend) validatePath(path string) error {
+	absPath, err := filepath.Abs(path)
+	if err != nil {
+		return fmt.Errorf("cannot resolve path: %w", err)
+	}
+	if len(b.allowedDirs) == 0 {
+		return nil
+	}
+	for _, allowed := range b.allowedDirs {
+		absAllowed, err := filepath.Abs(allowed)
+		if err != nil {
+			continue
+		}
+		if strings.HasPrefix(absPath, absAllowed+string(os.PathSeparator)) || absPath == absAllowed {
+			return nil
+		}
+	}
+	return fmt.Errorf("path not in allowed directories: %s", path)
+}
@@ -0,0 +1,274 @@
+package host
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os/exec"
+	"strings"
+	"time"
+)
+
+// DockerBackend executes commands inside a Docker container,
+// providing a full Linux OS environment with container-level isolation.
+type DockerBackend struct {
+	container string
+	image     string
+	timeout   time.Duration
+}
+
+// NewDockerBackend creates a Docker backend that runs commands in the
+// specified container. If the container does not exist, it will be
+// created from the given image.
+func NewDockerBackend(container, image string, defaultTimeout time.Duration) *DockerBackend {
+	if defaultTimeout <= 0 {
+		defaultTimeout = 30 * time.Second
+	}
+	return &DockerBackend{
+		container: container,
+		image:     image,
+		timeout:   defaultTimeout,
+	}
+}
+
+func (b *DockerBackend) Name() string { return "docker" }
+
+// ensureContainer checks that the container exists and is running.
+// If it doesn't exist, it creates it from the configured image.
+func (b *DockerBackend) ensureContainer() error {
+	// Check if container exists and is running
+	check := exec.Command("docker", "inspect", "-f", "{{.State.Running}}", b.container)
+	out, err := check.Output()
+	if err == nil && strings.TrimSpace(string(out)) == "true" {
+		return nil
+	}
+
+	// Check if container exists but is stopped
+	if err == nil && strings.TrimSpace(string(out)) == "false" {
+		start := exec.Command("docker", "start", b.container)
+		if out, err := start.CombinedOutput(); err != nil {
+			return fmt.Errorf("cannot start container %s: %s — %w", b.container, string(out), err)
+		}
+		return nil
+	}
+
+	// Create and start a new container
+	create := exec.Command("docker", "run", "-d", "--name", b.container,
+		"--restart", "unless-stopped",
+		b.image, "sleep", "infinity")
+	if out, err := create.CombinedOutput(); err != nil {
+		return fmt.Errorf("cannot create container %s from image %s: %s — %w",
+			b.container, b.image, string(out), err)
+	}
+	return nil
+}
+
+// Exec runs a command inside the Docker container.
+func (b *DockerBackend) Exec(ctx context.Context, command, workDir string, timeout time.Duration) (*ExecResult, error) {
+	if command == "" {
+		return nil, fmt.Errorf("empty command")
+	}
+
+	if err := b.ensureContainer(); err != nil {
+		return nil, err
+	}
+
+	if timeout <= 0 {
+		timeout = b.timeout
+	}
+
+	execCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	// Build the shell command to run inside the container
+	script := command
+	if workDir != "" {
+		script = fmt.Sprintf("cd %s && %s", shellEscapeDocker(workDir), command)
+	}
+
+	cmd := exec.CommandContext(execCtx, "docker", "exec", b.container, "sh", "-c", script)
+
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+
+	start := time.Now()
+	err := cmd.Run()
+	elapsed := time.Since(start)
+
+	result := &ExecResult{
+		Duration: elapsed.Round(time.Millisecond).String(),
+		Stdout:   stdout.String(),
+		Stderr:   stderr.String(),
+	}
+
+	if execCtx.Err() == context.DeadlineExceeded {
+		result.TimedOut = true
+		result.ExitCode = -1
+		return result, fmt.Errorf("command timed out after %s", timeout)
+	}
+
+	if err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			result.ExitCode = exitErr.ExitCode()
+		} else {
+			result.ExitCode = -1
+		}
+	} else {
+		result.ExitCode = 0
+	}
+
+	return result, err
+}
+
+// ReadFile reads a file from inside the container using cat.
+func (b *DockerBackend) ReadFile(path string, maxBytes int) (string, error) {
+	if maxBytes <= 0 {
+		maxBytes = 1024 * 1024
+	}
+	if err := b.ensureContainer(); err != nil {
+		return "", err
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "docker", "exec", b.container, "cat", path)
+	out, err := cmd.Output()
+	if err != nil {
+		return "", fmt.Errorf("cannot read file %s: %w", path, err)
+	}
+	if len(out) > maxBytes {
+		out = out[:maxBytes]
+	}
+	return string(out), nil
+}
+
+// WriteFile writes content to a file inside the container.
+func (b *DockerBackend) WriteFile(path, content string, maxBytes int) error {
+	if maxBytes <= 0 {
+		maxBytes = 1024 * 1024
+	}
+	if len(content) > maxBytes {
+		return fmt.Errorf("content too large: %d bytes (max %d)", len(content), maxBytes)
+	}
+	if err := b.ensureContainer(); err != nil {
+		return err
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	// Create parent directory and write file
+	cmd := exec.CommandContext(ctx, "docker", "exec", "-i", b.container, "sh", "-c",
+		fmt.Sprintf("mkdir -p $(dirname %s) && cat > %s", shellEscapeDocker(path), shellEscapeDocker(path)))
+	cmd.Stdin = strings.NewReader(content)
+	_, err := cmd.Output()
+	if err != nil {
+		return fmt.Errorf("cannot write file %s: %w", path, err)
+	}
+	return nil
+}
+
+// ListDir lists a directory inside the container.
+func (b *DockerBackend) ListDir(path string) ([]DirEntry, error) {
+	if err := b.ensureContainer(); err != nil {
+		return nil, err
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "docker", "exec", b.container, "sh", "-c",
+		fmt.Sprintf("ls -la %s 2>/dev/null | tail -n +2 || echo ''", shellEscapeDocker(path)))
+	out, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("cannot list dir %s: %w", path, err)
+	}
+
+	lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+	result := make([]DirEntry, 0, len(lines))
+	for _, line := range lines {
+		if line == "" || strings.HasPrefix(line, "total ") {
+			continue
+		}
+		// Parse ls -la output: drwxr-xr-x 2 root root 4096 Jan 1 12:00 name
+		fields := strings.Fields(line)
+		if len(fields) < 9 {
+			continue
+		}
+		isDir := strings.HasPrefix(fields[0], "d")
+		name := fields[len(fields)-1]
+		if name == "." || name == ".." {
+			continue
+		}
+		var size int64
+		fmt.Sscanf(fields[4], "%d", &size)
+		result = append(result, DirEntry{
+			Name:  name,
+			IsDir: isDir,
+			Size:  size,
+		})
+	}
+	return result, nil
+}
+
+// SystemInfo returns system information from inside the container.
+func (b *DockerBackend) SystemInfo() map[string]interface{} {
+	info := map[string]interface{}{
+		"backend":   "docker",
+		"container": b.container,
+		"image":     b.image,
+	}
+
+	if err := b.ensureContainer(); err != nil {
+		info["error"] = err.Error()
+		return info
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	if out, err := exec.CommandContext(ctx, "docker", "exec", b.container, "uname", "-a").Output(); err == nil {
+		info["uname"] = strings.TrimSpace(string(out))
+	}
+	if out, err := exec.CommandContext(ctx, "docker", "exec", b.container, "hostname").Output(); err == nil {
+		info["hostname"] = strings.TrimSpace(string(out))
+	}
+	if out, err := exec.CommandContext(ctx, "docker", "exec", b.container, "free", "-h").Output(); err == nil {
+		info["memory"] = strings.TrimSpace(string(out))
+	}
+	if out, err := exec.CommandContext(ctx, "docker", "exec", b.container, "df", "-h", "/").Output(); err == nil {
+		lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+		if len(lines) > 1 {
+			info["disk"] = strings.TrimSpace(lines[1])
+		}
+	}
+	return info
+}
+
+// DiskUsage returns disk usage for a path inside the container.
+func (b *DockerBackend) DiskUsage(path string) (map[string]interface{}, error) {
+	if err := b.ensureContainer(); err != nil {
+		return nil, err
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "docker", "exec", b.container, "stat", path)
+	out, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("cannot stat path %s: %w", path, err)
+	}
+	return map[string]interface{}{
+		"path":   path,
+		"stat":   strings.TrimSpace(string(out)),
+	}, nil
+}
+
+// shellEscapeDocker escapes a string for safe use in a shell command.
+func shellEscapeDocker(s string) string {
+	escaped := strings.ReplaceAll(s, "'", "'\\''")
+	return "'" + escaped + "'"
+}
@@ -0,0 +1,323 @@
+package host
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"os/exec"
+	"path/filepath"
+	"strings"
+	"time"
+)
+
+// WSLBackend executes commands inside a WSL2 distribution,
+// providing a full Linux OS environment isolated from the Windows host.
+type WSLBackend struct {
+	distro   string
+	username string
+	password string
+	timeout  time.Duration
+
+	userEnsured bool
+}
+
+// NewWSLBackend creates a WSL backend that runs commands in the
+// specified WSL distribution as the given user. On first use,
+// the user is automatically created with sudo privileges.
+func NewWSLBackend(distro, username, password string, defaultTimeout time.Duration) *WSLBackend {
+	if defaultTimeout <= 0 {
+		defaultTimeout = 30 * time.Second
+	}
+	if username == "" {
+		username = "cyrene"
+	}
+	return &WSLBackend{
+		distro:   distro,
+		username: username,
+		password: password,
+		timeout:  defaultTimeout,
+	}
+}
+
+func (b *WSLBackend) Name() string { return "wsl" }
+
+// ensureUser creates the configured user inside the WSL distro on first call.
+// The user gets sudo privileges and the configured password.
+func (b *WSLBackend) ensureUser() error {
+	if b.userEnsured {
+		return nil
+	}
+
+	// Check if user already exists
+	checkCtx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+	checkCmd := exec.CommandContext(checkCtx, "wsl.exe", "-d", b.distro, "--", "id", b.username)
+	if checkCmd.Run() == nil {
+		b.userEnsured = true
+		return nil
+	}
+
+	// Create user with home directory, set password, add to sudo group
+	// If password is empty, create user without password (sudo won't need it
+	// if NOPASSWD is configured, but we still set a random one for safety)
+	pwd := b.password
+	if pwd == "" {
+		pwd = "cyrene"
+	}
+
+	// Escape single quotes in password for the shell echo command
+	escapedPwd := strings.ReplaceAll(pwd, "'", "'\\''")
+	script := fmt.Sprintf(
+		"useradd -m -s /bin/bash %s && echo '%s:%s' | chpasswd && usermod -aG sudo %s",
+		b.username, b.username, escapedPwd, b.username,
+	)
+
+	createCtx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
+	defer cancel()
+	createCmd := exec.CommandContext(createCtx, "wsl.exe", "-d", b.distro, "--", "bash", "-c", script)
+	if out, err := createCmd.CombinedOutput(); err != nil {
+		return fmt.Errorf("cannot create user %s: %s — %w", b.username, string(out), err)
+	}
+
+	b.userEnsured = true
+	return nil
+}
+
+// Exec runs a command inside the WSL distribution via bash.
+func (b *WSLBackend) Exec(ctx context.Context, command, workDir string, timeout time.Duration) (*ExecResult, error) {
+	if command == "" {
+		return nil, fmt.Errorf("empty command")
+	}
+
+	if err := b.ensureUser(); err != nil {
+		return nil, err
+	}
+
+	if timeout <= 0 {
+		timeout = b.timeout
+	}
+
+	execCtx, cancel := context.WithTimeout(ctx, timeout)
+	defer cancel()
+
+	// Build the bash command to run inside WSL
+	script := command
+	if workDir != "" {
+		wslPath := windowsToWSLPath(workDir)
+		script = fmt.Sprintf("cd %s && %s", shellEscape(wslPath), command)
+	}
+
+	cmd := exec.CommandContext(execCtx, "wsl.exe", "-d", b.distro, "--", "bash", "-c", script)
+
+	var stdout, stderr bytes.Buffer
+	cmd.Stdout = &stdout
+	cmd.Stderr = &stderr
+
+	start := time.Now()
+	err := cmd.Run()
+	elapsed := time.Since(start)
+
+	result := &ExecResult{
+		Duration: elapsed.Round(time.Millisecond).String(),
+		Stdout:   stdout.String(),
+		Stderr:   stderr.String(),
+	}
+
+	if execCtx.Err() == context.DeadlineExceeded {
+		result.TimedOut = true
+		result.ExitCode = -1
+		return result, fmt.Errorf("command timed out after %s", timeout)
+	}
+
+	if err != nil {
+		if exitErr, ok := err.(*exec.ExitError); ok {
+			result.ExitCode = exitErr.ExitCode()
+		} else {
+			result.ExitCode = -1
+		}
+	} else {
+		result.ExitCode = 0
+	}
+
+	return result, err
+}
+
+// ReadFile reads a file from the WSL filesystem using cat.
+func (b *WSLBackend) ReadFile(path string, maxBytes int) (string, error) {
+	if maxBytes <= 0 {
+		maxBytes = 1024 * 1024
+	}
+	if err := b.ensureUser(); err != nil {
+		return "", err
+	}
+	wslPath := windowsToWSLPath(path)
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "wsl.exe", "-d", b.distro, "--", "cat", wslPath)
+	out, err := cmd.Output()
+	if err != nil {
+		return "", fmt.Errorf("cannot read file %s: %w", path, err)
+	}
+	if len(out) > maxBytes {
+		out = out[:maxBytes]
+	}
+	return string(out), nil
+}
+
+// WriteFile writes content to a file in the WSL filesystem.
+func (b *WSLBackend) WriteFile(path, content string, maxBytes int) error {
+	if maxBytes <= 0 {
+		maxBytes = 1024 * 1024
+	}
+	if len(content) > maxBytes {
+		return fmt.Errorf("content too large: %d bytes (max %d)", len(content), maxBytes)
+	}
+	if err := b.ensureUser(); err != nil {
+		return err
+	}
+	wslPath := windowsToWSLPath(path)
+	// Create parent directory first
+	dir := filepath.Dir(wslPath)
+	_ = exec.Command("wsl.exe", "-d", b.distro, "--", "mkdir", "-p", dir).Run()
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "wsl.exe", "-d", b.distro, "--", "bash", "-c",
+		fmt.Sprintf("cat > %s", shellEscape(wslPath)))
+	cmd.Stdin = strings.NewReader(content)
+	_, err := cmd.Output()
+	if err != nil {
+		return fmt.Errorf("cannot write file %s: %w", path, err)
+	}
+	return nil
+}
+
+// ListDir lists a directory in the WSL filesystem using ls.
+func (b *WSLBackend) ListDir(path string) ([]DirEntry, error) {
+	if err := b.ensureUser(); err != nil {
+		return nil, err
+	}
+	wslPath := windowsToWSLPath(path)
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "wsl.exe", "-d", b.distro, "--", "bash", "-c",
+		fmt.Sprintf("stat -c '%%n|%%F|%%s|%%Y' %s/* 2>/dev/null || echo ''", shellEscape(wslPath)))
+	out, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("cannot list dir %s: %w", path, err)
+	}
+
+	lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+	result := make([]DirEntry, 0, len(lines))
+	for _, line := range lines {
+		if line == "" {
+			continue
+		}
+		parts := strings.SplitN(line, "|", 4)
+		if len(parts) < 4 {
+			continue
+		}
+		var size int64
+		fmt.Sscanf(parts[2], "%d", &size)
+		var modTimeUnix int64
+		fmt.Sscanf(parts[3], "%d", &modTimeUnix)
+		modTime := time.Unix(modTimeUnix, 0).Format(time.RFC3339)
+		isDir := strings.Contains(parts[1], "directory")
+		result = append(result, DirEntry{
+			Name:    filepath.Base(parts[0]),
+			IsDir:   isDir,
+			Size:    size,
+			ModTime: modTime,
+		})
+	}
+	return result, nil
+}
+
+// SystemInfo returns system information from inside the WSL distribution.
+func (b *WSLBackend) SystemInfo() map[string]interface{} {
+	info := map[string]interface{}{
+		"backend": "wsl",
+		"distro":  b.distro,
+	}
+
+	if err := b.ensureUser(); err != nil {
+		info["error"] = err.Error()
+		return info
+	}
+
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	// uname
+	if out, err := exec.CommandContext(ctx, "wsl.exe", "-d", b.distro, "--", "uname", "-a").Output(); err == nil {
+		info["uname"] = strings.TrimSpace(string(out))
+	}
+
+	// hostname
+	if out, err := exec.CommandContext(ctx, "wsl.exe", "-d", b.distro, "--", "hostname").Output(); err == nil {
+		info["hostname"] = strings.TrimSpace(string(out))
+	}
+
+	// memory info
+	if out, err := exec.CommandContext(ctx, "wsl.exe", "-d", b.distro, "--", "free", "-h").Output(); err == nil {
+		info["memory"] = strings.TrimSpace(string(out))
+	}
+
+	// disk info
+	if out, err := exec.CommandContext(ctx, "wsl.exe", "-d", b.distro, "--", "df", "-h", "/").Output(); err == nil {
+		lines := strings.Split(strings.TrimSpace(string(out)), "\n")
+		if len(lines) > 1 {
+			info["disk"] = strings.TrimSpace(lines[1])
+		}
+	}
+
+	return info
+}
+
+// DiskUsage returns disk usage for a path inside WSL.
+func (b *WSLBackend) DiskUsage(path string) (map[string]interface{}, error) {
+	wslPath := windowsToWSLPath(path)
+	ctx, cancel := context.WithTimeout(context.Background(), 10*time.Second)
+	defer cancel()
+
+	cmd := exec.CommandContext(ctx, "wsl.exe", "-d", b.distro, "--", "stat", wslPath)
+	out, err := cmd.Output()
+	if err != nil {
+		return nil, fmt.Errorf("cannot stat path %s: %w", path, err)
+	}
+
+	// Parse stat output minimally
+	result := map[string]interface{}{
+		"path":   path,
+		"wsl_path": wslPath,
+		"stat":   strings.TrimSpace(string(out)),
+	}
+	return result, nil
+}
+
+// windowsToWSLPath converts a Windows path to its WSL equivalent.
+// C:\Users\foo → /mnt/c/Users/foo
+// If the path is already a WSL path (starts with /), return as-is.
+func windowsToWSLPath(path string) string {
+	if strings.HasPrefix(path, "/") {
+		return path // Already a Unix path
+	}
+	// Handle Windows drive letter: C:\... → /mnt/c/...
+	if len(path) >= 2 && path[1] == ':' {
+		drive := strings.ToLower(string(path[0]))
+		rest := strings.TrimPrefix(path[2:], "\\")
+		rest = strings.ReplaceAll(rest, "\\", "/")
+		return fmt.Sprintf("/mnt/%s/%s", drive, rest)
+	}
+	return path
+}
+
+// shellEscape escapes a string for safe use in a shell command.
+func shellEscape(s string) string {
+	// Use single quotes and escape any single quotes in the string
+	escaped := strings.ReplaceAll(s, "'", "'\\''")
+	return "'" + escaped + "'"
+}
@@ -0,0 +1,143 @@
+package host
+
+import (
+	"context"
+	"os"
+	"strings"
+	"testing"
+	"time"
+)
+
+func TestWSLBackendIntegration(t *testing.T) {
+	distro := os.Getenv("WSL_DISTRO")
+	if distro == "" {
+		t.Skip("WSL_DISTRO not set, skipping WSL integration test (set WSL_DISTRO=cyrene-wsl to run)")
+	}
+
+	backend := NewWSLBackend(distro, "cyrene", "test123", 30*time.Second)
+	mgr := NewManager(backend)
+	ctx := context.Background()
+
+	// 1. Basic command
+	t.Run("echo", func(t *testing.T) {
+		r, err := mgr.Exec(ctx, "echo 'hello from WSL OS env'", "", 10*time.Second)
+		if err != nil {
+			t.Fatalf("exec failed: %v", err)
+		}
+		if r.ExitCode != 0 {
+			t.Fatalf("exit=%d, stderr=%s", r.ExitCode, r.Stderr)
+		}
+		if !strings.Contains(r.Stdout, "hello from WSL OS env") {
+			t.Fatalf("unexpected stdout: %s", r.Stdout)
+		}
+		t.Logf("echo OK: %s (duration=%s)", strings.TrimSpace(r.Stdout), r.Duration)
+	})
+
+	// 2. Complex commands - package manager
+	t.Run("apt", func(t *testing.T) {
+		r, err := mgr.Exec(ctx, "apt --version 2>&1", "", 10*time.Second)
+		if err != nil {
+			t.Fatalf("exec failed: %v", err)
+		}
+		t.Logf("apt OK: %s", strings.TrimSpace(r.Stdout))
+	})
+
+	// 3. Python (should be pre-installed on Ubuntu)
+	t.Run("python", func(t *testing.T) {
+		r, err := mgr.Exec(ctx, "python3 --version 2>&1", "", 10*time.Second)
+		if err != nil {
+			t.Fatalf("exec failed: %v", err)
+		}
+		t.Logf("python OK: %s", strings.TrimSpace(r.Stdout))
+	})
+
+	// 4. Pipeline & shell features
+	t.Run("pipeline", func(t *testing.T) {
+		r, err := mgr.Exec(ctx, "echo 'a\nb\nc\nd' | wc -l", "", 10*time.Second)
+		if err != nil {
+			t.Fatalf("exec failed: %v", err)
+		}
+		if r.ExitCode != 0 {
+			t.Fatalf("exit=%d", r.ExitCode)
+		}
+		t.Logf("pipeline OK: %s", strings.TrimSpace(r.Stdout))
+	})
+
+	// 5. File write & read
+	t.Run("file_rw", func(t *testing.T) {
+		err := mgr.WriteFile("/tmp/cyrene-wsl-test.txt", "Hello from Cyrene OS!", 1024*1024)
+		if err != nil {
+			t.Fatalf("write failed: %v", err)
+		}
+		content, err := mgr.ReadFile("/tmp/cyrene-wsl-test.txt", 1024*1024)
+		if err != nil {
+			t.Fatalf("read failed: %v", err)
+		}
+		if content != "Hello from Cyrene OS!" {
+			t.Fatalf("content mismatch: %q", content)
+		}
+		t.Logf("file r/w OK: %q", content)
+	})
+
+	// 6. Directory listing
+	t.Run("listdir", func(t *testing.T) {
+		entries, err := mgr.ListDir("/etc")
+		if err != nil {
+			t.Fatalf("listdir failed: %v", err)
+		}
+		if len(entries) == 0 {
+			t.Fatal("expected entries in /etc")
+		}
+		t.Logf("listdir OK: %d entries in /etc", len(entries))
+		for _, e := range entries {
+			if e.Name == "os-release" || e.Name == "hostname" {
+				t.Logf("  - %s (isDir=%v, size=%d)", e.Name, e.IsDir, e.Size)
+			}
+		}
+	})
+
+	// 7. System info
+	t.Run("sysinfo", func(t *testing.T) {
+		info := mgr.SystemInfo()
+		if info["backend"] != "wsl" {
+			t.Fatalf("unexpected backend: %v", info["backend"])
+		}
+		if info["distro"] != distro {
+			t.Fatalf("unexpected distro: %v", info["distro"])
+		}
+		t.Logf("sysinfo OK: backend=%v, distro=%v", info["backend"], info["distro"])
+		if uname, ok := info["uname"]; ok {
+			t.Logf("  uname: %v", uname)
+		}
+		if hostname, ok := info["hostname"]; ok {
+			t.Logf("  hostname: %v", hostname)
+		}
+		if mem, ok := info["memory"]; ok {
+			t.Logf("  memory: %v", mem)
+		}
+	})
+
+	// 8. workDir
+	t.Run("workdir", func(t *testing.T) {
+		r, err := mgr.Exec(ctx, "pwd", "/tmp", 10*time.Second)
+		if err != nil {
+			t.Fatalf("exec failed: %v", err)
+		}
+		if !strings.Contains(r.Stdout, "/tmp") {
+			t.Fatalf("expected /tmp, got: %s", r.Stdout)
+		}
+		t.Logf("workdir OK: pwd=%s", strings.TrimSpace(r.Stdout))
+	})
+
+	// 9. Timeout
+	t.Run("timeout", func(t *testing.T) {
+		r, err := mgr.Exec(ctx, "sleep 10", "", 1*time.Second)
+		if err == nil {
+			t.Fatal("expected timeout")
+		}
+		if !r.TimedOut {
+			t.Fatal("expected TimedOut=true")
+		}
+		t.Logf("timeout OK: timed_out=%v", r.TimedOut)
+	})
+}
@@ -2,207 +2,72 @@ package host

 import (
 	"context"
-	"fmt"
-	"os"
-	"os/exec"
-	"path/filepath"
-	"runtime"
-	"strings"
 	"time"
 )

-// Manager provides controlled access to the host machine.
-// It wraps a Sandbox for command execution and adds file system
-// operations with path allow-list enforcement.
+// HostBackend defines the interface for command execution and file system
+// operations. Implementations include DirectBackend (host OS), WSLBackend
+// (Windows Subsystem for Linux), and DockerBackend (container).
+type HostBackend interface {
+	Exec(ctx context.Context, command, workDir string, timeout time.Duration) (*ExecResult, error)
+	ReadFile(path string, maxBytes int) (string, error)
+	WriteFile(path, content string, maxBytes int) error
+	ListDir(path string) ([]DirEntry, error)
+	SystemInfo() map[string]interface{}
+	DiskUsage(path string) (map[string]interface{}, error)
+	Name() string
+}
+
+// Manager provides controlled access to the host machine. It delegates
+// to a HostBackend implementation which may be direct, WSL, or Docker.
 type Manager struct {
-	sandbox    *Sandbox
-	allowedDirs []string
+	backend HostBackend
 }

-// NewManager creates a new host Manager.
-func NewManager(sandbox *Sandbox) *Manager {
-	m := &Manager{sandbox: sandbox}
-	if sandbox != nil {
-		m.allowedDirs = sandbox.cfg.AllowedDirs
-	}
-	return m
+// NewManager creates a new host Manager with the given backend.
+func NewManager(backend HostBackend) *Manager {
+	return &Manager{backend: backend}
 }

-// SetAllowedDirs updates the list of directories accessible for file operations.
+// SetAllowedDirs updates directory restrictions. Only effective for
+// DirectBackend; WSL and Docker backends are no-ops.
 func (m *Manager) SetAllowedDirs(dirs []string) {
-	m.allowedDirs = dirs
-	m.sandbox.cfg.AllowedDirs = dirs
+	if db, ok := m.backend.(*DirectBackend); ok {
+		db.SetAllowedDirs(dirs)
+	}
 }

-// Exec runs a command in the sandbox.
+// Exec runs a command via the configured backend.
 func (m *Manager) Exec(ctx context.Context, command, workDir string, timeout time.Duration) (*ExecResult, error) {
-	return m.sandbox.Exec(ctx, command, workDir, timeout)
+	return m.backend.Exec(ctx, command, workDir, timeout)
 }

-// ReadFile reads the contents of a file within allowed directories.
+// ReadFile reads a file via the configured backend.
 func (m *Manager) ReadFile(path string, maxBytes int) (string, error) {
-	if maxBytes <= 0 {
-		maxBytes = 1024 * 1024
-	}
-	if err := m.validatePath(path); err != nil {
-		return "", err
-	}
-	info, err := os.Stat(path)
-	if err != nil {
-		return "", fmt.Errorf("cannot stat file: %w", err)
-	}
-	if info.IsDir() {
-		return "", fmt.Errorf("path is a directory: %s", path)
-	}
-	if info.Size() > int64(maxBytes) {
-		return "", fmt.Errorf("file too large: %d bytes (max %d)", info.Size(), maxBytes)
-	}
-	data, err := os.ReadFile(path)
-	if err != nil {
-		return "", fmt.Errorf("cannot read file: %w", err)
-	}
-	if len(data) > maxBytes {
-		data = data[:maxBytes]
-	}
-	return string(data), nil
+	return m.backend.ReadFile(path, maxBytes)
 }

-// WriteFile writes data to a file within allowed directories.
+// WriteFile writes a file via the configured backend.
 func (m *Manager) WriteFile(path, content string, maxBytes int) error {
-	if maxBytes <= 0 {
-		maxBytes = 1024 * 1024
-	}
-	if len(content) > maxBytes {
-		return fmt.Errorf("content too large: %d bytes (max %d)", len(content), maxBytes)
-	}
-	if err := m.validatePath(path); err != nil {
-		return err
-	}
-	dir := filepath.Dir(path)
-	if err := os.MkdirAll(dir, 0755); err != nil {
-		return fmt.Errorf("cannot create directory: %w", err)
-	}
-	return os.WriteFile(path, []byte(content), 0644)
+	return m.backend.WriteFile(path, content, maxBytes)
 }

-// ListDir lists directory contents within allowed directories.
+// ListDir lists a directory via the configured backend.
 func (m *Manager) ListDir(path string) ([]DirEntry, error) {
-	if err := m.validatePath(path); err != nil {
-		return nil, err
-	}
-	entries, err := os.ReadDir(path)
-	if err != nil {
-		return nil, fmt.Errorf("cannot read directory: %w", err)
-	}
-	result := make([]DirEntry, 0, len(entries))
-	for _, e := range entries {
-		info, _ := e.Info()
-		size := int64(0)
-		modTime := time.Time{}
-		if info != nil {
-			size = info.Size()
-			modTime = info.ModTime()
-		}
-		result = append(result, DirEntry{
-			Name:    e.Name(),
-			IsDir:   e.IsDir(),
-			Size:    size,
-			ModTime: modTime.Format(time.RFC3339),
-		})
-	}
-	return result, nil
+	return m.backend.ListDir(path)
 }

-// DirEntry represents a filesystem directory entry.
-type DirEntry struct {
-	Name    string `json:"name"`
-	IsDir   bool   `json:"is_dir"`
-	Size    int64  `json:"size"`
-	ModTime string `json:"mod_time"`
-}
-
-// SystemInfo returns basic system information.
+// SystemInfo returns system information from the configured backend.
 func (m *Manager) SystemInfo() map[string]interface{} {
-	hostname, _ := os.Hostname()
-	wd, _ := os.Getwd()
-
-	info := map[string]interface{}{
-		"hostname":    hostname,
-		"os":          runtime.GOOS,
-		"arch":        runtime.GOARCH,
-		"num_cpu":     runtime.NumCPU(),
-		"go_version":  runtime.Version(),
-		"work_dir":    wd,
-	}
-
-	if runtime.GOOS == "windows" {
-		cmd := exec.Command("systeminfo")
-		out, err := cmd.Output()
-		if err == nil {
-			lines := strings.Split(string(out), "\n")
-			for _, line := range lines {
-				line = strings.TrimSpace(line)
-				if strings.Contains(line, "Total Physical Memory") {
-					parts := strings.SplitN(line, ":", 2)
-					if len(parts) == 2 {
-						info["total_memory"] = strings.TrimSpace(parts[1])
-					}
-				}
-				if strings.Contains(line, "OS Name") {
-					parts := strings.SplitN(line, ":", 2)
-					if len(parts) == 2 {
-						info["os_name"] = strings.TrimSpace(parts[1])
-					}
-				}
-			}
-		}
-	} else {
-		if data, err := os.ReadFile("/proc/meminfo"); err == nil {
-			for _, line := range strings.Split(string(data), "\n") {
-				if strings.HasPrefix(line, "MemTotal:") {
-					info["total_memory"] = strings.TrimSpace(strings.TrimPrefix(line, "MemTotal:"))
-					break
-				}
-			}
-		}
-	}
-	return info
+	return m.backend.SystemInfo()
 }

-// DiskUsage returns disk usage for the given path.
+// DiskUsage returns disk usage info from the configured backend.
 func (m *Manager) DiskUsage(path string) (map[string]interface{}, error) {
-	if err := m.validatePath(path); err != nil {
-		return nil, err
-	}
-	info, err := os.Stat(path)
-	if err != nil {
-		return nil, fmt.Errorf("cannot stat path: %w", err)
-	}
-	result := map[string]interface{}{
-		"path":     path,
-		"is_dir":   info.IsDir(),
-		"size":     info.Size(),
-		"mod_time": info.ModTime().Format(time.RFC3339),
-	}
-	return result, nil
+	return m.backend.DiskUsage(path)
 }

-func (m *Manager) validatePath(path string) error {
-	absPath, err := filepath.Abs(path)
-	if err != nil {
-		return fmt.Errorf("cannot resolve path: %w", err)
-	}
-	if len(m.allowedDirs) == 0 {
-		return nil
-	}
-	for _, allowed := range m.allowedDirs {
-		absAllowed, err := filepath.Abs(allowed)
-		if err != nil {
-			continue
-		}
-		if strings.HasPrefix(absPath, absAllowed+string(os.PathSeparator)) || absPath == absAllowed {
-			return nil
-		}
-	}
-	return fmt.Errorf("path not in allowed directories: %s", path)
+// BackendName returns the name of the active backend.
+func (m *Manager) BackendName() string {
+	return m.backend.Name()
 }
@@ -50,6 +50,14 @@ func NewSandbox(cfg SandboxConfig) *Sandbox {
 	return &Sandbox{cfg: cfg}
 }

+// DirEntry represents a filesystem directory entry.
+type DirEntry struct {
+	Name    string `json:"name"`
+	IsDir   bool   `json:"is_dir"`
+	Size    int64  `json:"size"`
+	ModTime string `json:"mod_time,omitempty"`
+}
+
 // ExecResult holds the result of a sandboxed command execution.
 type ExecResult struct {
 	Stdout   string `json:"stdout"`
@@ -62,7 +62,7 @@ func TestManagerFileOps(t *testing.T) {
 	tmpDir := os.TempDir()
 	cfg.AllowedDirs = []string{tmpDir}
 	sandbox := NewSandbox(cfg)
-	mgr := NewManager(sandbox)
+	mgr := NewManager(NewDirectBackend(sandbox))
 	mgr.SetAllowedDirs([]string{tmpDir})

 	testPath := filepath.Join(tmpDir, "cyrene-test-file.txt")
@@ -102,7 +102,7 @@ func TestManagerFileOps(t *testing.T) {
 func TestManagerSystemInfo(t *testing.T) {
 	cfg := DefaultSandboxConfig()
 	sandbox := NewSandbox(cfg)
-	mgr := NewManager(sandbox)
+	mgr := NewManager(NewDirectBackend(sandbox))

 	info := mgr.SystemInfo()
 	if info["hostname"] == nil || info["hostname"] == "" {
@@ -121,7 +121,7 @@ func TestPathValidation(t *testing.T) {
 	cfg := DefaultSandboxConfig()
 	cfg.AllowedDirs = []string{os.TempDir()}
 	sandbox := NewSandbox(cfg)
-	mgr := NewManager(sandbox)
+	mgr := NewManager(NewDirectBackend(sandbox))
 	mgr.SetAllowedDirs([]string{os.TempDir()})

 	// Should fail: access outside allowed dirs