Remote Sandbox Workspace Unification — Implementation Plan

	// === Lifecycle ===
	Name() string
	Workspace(userID string) string  // Returns the workspace root path for the given user
	Close() error

func (s *NoneSandbox) Workspace(userID string) string { return "" }

func (s *DockerSandbox) Workspace(userID string) string { return "/workspace" }

git add tools/sandbox.go tools/none_sandbox.go tools/docker_sandbox.go
git commit -m "feat(sandbox): add Workspace(userID) method to Sandbox interface"

	SandboxWorkDir   string   // 沙箱内工作目录（如 /workspace）

	SandboxWorkDir          string          // 沙箱内工作目录（如 Docker 为 /workspace，非沙箱时与 WorkspaceRoot 相同）

		SandboxWorkDir:       cfg.SandboxWorkDir,

		SandboxReadOnlyRoots: sandboxReadOnlyRoots(cfg.ReadOnlyRoots, "", cfg.WorkspaceRoot),

func defaultWorkspaceRoot(ctx *ToolContext) string {
	if ctx == nil {
		return ""
	}
	if ctx.Sandbox != nil && ctx.Sandbox.Name() != "none" {
		return ctx.Sandbox.Workspace(ctx.OriginUserID)
	}
	if ctx.WorkspaceRoot != "" {
		return ctx.WorkspaceRoot
	}
	return ctx.WorkingDir
}

func sandboxBaseDir(ctx *ToolContext) string {
	if ctx != nil && ctx.Sandbox != nil && ctx.Sandbox.Name() != "none" {
		return ctx.Sandbox.Workspace(ctx.OriginUserID)
	}
	return ""
}

func shouldUseSandbox(ctx *ToolContext) bool {
	return ctx != nil && ctx.Sandbox != nil && ctx.Sandbox.Name() != "none"
}

type mockSandbox struct {
	name      string
	workspace string
}

func (m *mockSandbox) Name() string                                               { return m.name }
func (m *mockSandbox) Workspace(userID string) string                             { return m.workspace }
func (m *mockSandbox) Exec(ctx context.Context, spec ExecSpec) (*ExecResult, error) {
	return nil, fmt.Errorf("not implemented")
}
func (m *mockSandbox) ReadFile(ctx context.Context, path string, userID string) ([]byte, error) {
	return nil, os.ErrNotExist
}
func (m *mockSandbox) WriteFile(ctx context.Context, path string, data []byte, perm os.FileMode, userID string) error {
	return nil
}
func (m *mockSandbox) Stat(ctx context.Context, path string, userID string) (*SandboxFileInfo, error) {
	return nil, os.ErrNotExist
}
func (m *mockSandbox) ReadDir(ctx context.Context, path string, userID string) ([]DirEntry, error) {
	return nil, os.ErrNotExist
}
func (m *mockSandbox) MkdirAll(ctx context.Context, path string, perm os.FileMode, userID string) error {
	return nil
}
func (m *mockSandbox) Remove(ctx context.Context, path string, userID string) error {
	return os.ErrNotExist
}
func (m *mockSandbox) RemoveAll(ctx context.Context, path string, userID string) error {
	return nil
}
func (m *mockSandbox) GetShell(userID string, workspace string) (string, error) {
	return "/bin/bash", nil
}
func (m *mockSandbox) Close() error                     { return nil }
func (m *mockSandbox) CloseForUser(userID string) error { return nil }
func (m *mockSandbox) IsExporting(userID string) bool    { return false }
func (m *mockSandbox) ExportAndImport(userID string) error { return nil }

func TestSandboxBaseDir(t *testing.T) {
	tests := []struct {
		name string
		ctx  *ToolContext
		want string
	}{
		{"nil ctx", nil, ""},
		{"none sandbox", &ToolContext{Sandbox: &mockSandbox{name: "none"}}, ""},
		{"remote sandbox", &ToolContext{
			Sandbox:     &mockSandbox{name: "remote", workspace: "/home/user/ws"},
			OriginUserID: "u1",
		}, "/home/user/ws"},
		{"docker sandbox", &ToolContext{
			Sandbox:     &mockSandbox{name: "docker", workspace: "/workspace"},
			OriginUserID: "u1",
		}, "/workspace"},
	}

	for _, tt := range tests {
		t.Run(tt.name, func(t *testing.T) {
			got := sandboxBaseDir(tt.ctx)
			if got != tt.want {
				t.Errorf("sandboxBaseDir() = %q, want %q", got, tt.want)
			}
		})
	}
}

git add tools/path_guard.go tools/path_guard_test.go
git commit -m "refactor(path_guard): use Sandbox interface instead of SandboxWorkDir"

		SandboxEnabled:   a.sandboxMode == "docker",

		SandboxEnabled:   a.sandboxMode != "none",

		SandboxEnabled:   parentCtx.SandboxEnabled,

		SandboxEnabled:   shouldUseSandbox(parentCtx),

		SandboxEnabled:   a.sandboxMode == "docker",

		SandboxEnabled:   a.sandboxMode != "none",

		SandboxEnabled:      a.sandboxMode == "docker",

		SandboxEnabled:      a.sandboxMode != "none",

git add agent/engine_wire.go agent/interactive.go
git commit -m "fix(sandbox): SandboxEnabled covers remote mode, remove SandboxWorkDir from builders"

	workDir := parentCtx.SandboxWorkDir
	if workDir == "" {
		workDir = parentCtx.WorkspaceRoot
	}

	workDir := parentCtx.WorkspaceRoot
	if parentCtx.Sandbox != nil && parentCtx.Sandbox.Name() != "none" {
		workDir = parentCtx.Sandbox.Workspace(parentCtx.OriginUserID)
	}

		if cwd != "" && cfg.SandboxEnabled && cfg.WorkspaceRoot != "" && cfg.SandboxWorkDir != "" {
			if strings.HasPrefix(cwd, cfg.WorkspaceRoot) {
				cwd = cfg.SandboxWorkDir + cwd[len(cfg.WorkspaceRoot):]
			}
		}

		if cwd != "" && cfg.Sandbox != nil && cfg.Sandbox.Name() != "none" && cfg.WorkspaceRoot != "" {
			sandboxWS := cfg.Sandbox.Workspace(cfg.OriginUserID)
			if sandboxWS != "" && strings.HasPrefix(cwd, cfg.WorkspaceRoot) {
				cwd = sandboxWS + cwd[len(cfg.WorkspaceRoot):]
			}
		}

			offloaded, wasOffloaded := cfg.OffloadStore.MaybeOffload(ctx, offloadSessionKey, tc.Name, tc.Arguments, offloadContent, cfg.WorkspaceRoot, "", cfg.OriginUserID)

			staleIDs := cfg.OffloadStore.InvalidateStaleReads(ctx, offloadSessionKey, cfg.WorkspaceRoot, "", cfg.OriginUserID)

git add agent/engine.go agent/engine_wire.go
git commit -m "fix(subagent): use Sandbox.Workspace for prompt and CWD, remove SandboxWorkDir from offload"

		} else if toolCtx != nil && toolCtx.SandboxWorkDir != "" {
			dir = toolCtx.SandboxWorkDir // e.g. /workspace

		} else if toolCtx != nil && toolCtx.Sandbox != nil && toolCtx.Sandbox.Name() != "none" {
			dir = toolCtx.Sandbox.Workspace(toolCtx.OriginUserID)

	if ctx != nil && ctx.SandboxEnabled && ctx.WorkspaceRoot != "" {

	if shouldUseSandbox(ctx) {

	if ctx != nil && ctx.SandboxEnabled && ctx.WorkspaceRoot != "" {

	if shouldUseSandbox(ctx) {

	if ctx != nil && ctx.SandboxEnabled && ctx.WorkspaceRoot != "" {

	if shouldUseSandbox(ctx) {

	if ctx != nil && ctx.SandboxEnabled && ctx.WorkspaceRoot != "" {

	if shouldUseSandbox(ctx) {

	if ctx != nil && ctx.SandboxEnabled && ctx.WorkspaceRoot != "" {

	if shouldUseSandbox(ctx) {

	sandboxBaseDir(ctx)

	sandboxBase := ctx.SandboxWorkDir

	sandboxBase := sandboxBaseDir(ctx)

	if ctx.Sandbox != nil && ctx.SandboxWorkDir != "" {

	if shouldUseSandbox(ctx) {

	useSandbox := ctx != nil && ctx.Sandbox != nil && ctx.SandboxWorkDir != ""

	useSandbox := shouldUseSandbox(ctx)

			filepath.Join(ctx.SandboxWorkDir, "skills"),
			filepath.Join(ctx.SandboxWorkDir, ".skills"),

			filepath.Join(sandboxBaseDir(ctx), "skills"),
			filepath.Join(sandboxBaseDir(ctx), ".skills"),

		spec.Dir = ctx.SandboxWorkDir // 容器内路径，如 /workspace

		spec.Dir = ctx.Sandbox.Workspace(ctx.OriginUserID) // 容器内路径，如 /workspace

// Before:
ctx := &ToolContext{
    SandboxWorkDir: "/workspace",
    ...
}

// After:
ctx := &ToolContext{
    Sandbox:     &mockSandbox{name: "docker", workspace: "/workspace"},
    OriginUserID: "test-user",
    ...
}

	ctx := &ToolContext{
		WorkspaceRoot:  filepath.Join(root, "host-workspace"),
		Sandbox:       &mockSandbox{name: "docker", workspace: sandboxDir},
		SandboxEnabled: true,
		OriginUserID:   "test-user",
	}

git add tools/shell.go tools/read.go tools/edit.go tools/grep.go tools/glob.go tools/cd.go tools/feishu_mcp/file.go tools/feishu_mcp/download.go tools/skill.go tools/sandbox_exec.go tools/sandbox_unit_test.go tools/path_guard_test.go
git commit -m "refactor(tools): replace SandboxWorkDir with Sandbox interface in all tool guards"

// sandboxWorkDir returns the sandbox working directory path.
// In docker mode, this is "/workspace" (the container-internal mount point).
// In none mode, this is empty (no sandbox path mapping needed).
func (a *Agent) sandboxWorkDir() string {
	if a.sandboxMode == "docker" {
		return "/workspace"
	}
	return ""
}

	sandboxWorkDir := ""
	if cfg.SandboxMode == "docker" || cfg.SandboxMode == "remote" {
		sandboxWorkDir = "/workspace"
	}

	skillStore := NewSkillStore(cfg.WorkDir, globalSkillDirs, cfg.Sandbox, sandboxWorkDir)

	skillStore := NewSkillStore(cfg.WorkDir, globalSkillDirs, cfg.Sandbox)

	agentStore := NewAgentStore(cfg.WorkDir, agentsDir, cfg.Sandbox, sandboxWorkDir)

	agentStore := NewAgentStore(cfg.WorkDir, agentsDir, cfg.Sandbox)

	sandboxWorkDir string        // 沙箱内工作目录（"/workspace" for docker/remote, "" for none）

func NewSkillStore(workDir string, globalDirs []string, sandbox tools.Sandbox) *SkillStore {
	return &SkillStore{
		workDir:    workDir,
		globalDirs: globalDirs,
		sandbox:    sandbox,
	}
}

func (s *SkillStore) userSkillsDir(senderID string) string {
	if s.sandbox != nil && s.sandbox.Name() != "none" {
		return filepath.Join(s.sandbox.Workspace(senderID), "skills")
	}
	return tools.UserSkillsRoot(s.workDir, senderID)
}

func (s *SkillStore) isUserSkillsSandboxed() bool {
	return s.sandbox != nil && s.sandbox.Name() != "none"
}

	sandboxWorkDir string

func NewAgentStore(workDir string, globalDir string, sandbox tools.Sandbox) *AgentStore {
	return &AgentStore{workDir: workDir, globalDir: globalDir, sandbox: sandbox}
}

func (s *AgentStore) userAgentsDir(senderID string) string {
	if s.sandbox != nil && s.sandbox.Name() != "none" {
		return filepath.Join(s.sandbox.Workspace(senderID), "agents")
	}
	return tools.UserAgentsRoot(s.workDir, senderID)
}

	if i == 0 || s.sandbox == nil || s.sandbox.Name() == "none" {

	sandboxWorkDir string // "/workspace" for docker/remote, "" for none

func NewRegistryManager(store *SkillStore, agentStore *AgentStore, sharedStore *sqlite.SharedSkillRegistry, workDir string, sandbox tools.Sandbox) *RegistryManager {
	return &RegistryManager{
		store:       store,
		agentStore:  agentStore,
		sharedStore: sharedStore,
		workDir:     workDir,
		sandbox:     sandbox,
	}
}

func (rm *RegistryManager) useSandbox() bool {
	return rm.sandbox != nil && rm.sandbox.Name() != "none"
}

func (rm *RegistryManager) userSkillsDir(senderID string) string {
	if rm.useSandbox() {
		return filepath.Join(rm.sandbox.Workspace(senderID), "skills")
	}
	return tools.UserSkillsRoot(rm.workDir, senderID)
}

func (rm *RegistryManager) userAgentsDir(senderID string) string {
	if rm.useSandbox() {
		return filepath.Join(rm.sandbox.Workspace(senderID), "agents")
	}
	return tools.UserAgentsRoot(rm.workDir, senderID)
}

	sandboxWorkDir := ""
	if cfg.SandboxMode == "docker" || cfg.SandboxMode == "remote" {
		sandboxWorkDir = "/workspace"
	}
	a.registryManager = NewRegistryManager(a.skills, a.agents, sharedRegistry, cfg.WorkDir, cfg.Sandbox, sandboxWorkDir)

	a.registryManager = NewRegistryManager(a.skills, a.agents, sharedRegistry, cfg.WorkDir, cfg.Sandbox)

git add agent/agent.go agent/skills.go agent/agents.go agent/registry.go
git commit -m "refactor(agent): remove sandboxWorkDir, use Sandbox.Workspace in stores"

	promptWorkDir := a.workDir
	if a.sandboxMode == "docker" {
		promptWorkDir = "/workspace"
	}

	promptWorkDir := a.workDir
	if a.sandboxMode == "docker" {
		promptWorkDir = "/workspace"
	} else if a.sandboxMode == "remote" {
		// Remote mode: promptWorkDir is per-user, set dynamically in middleware
		// Here we use a placeholder; actual per-request workDir is set by
		// SystemPromptMiddleware which reads from sandbox
		promptWorkDir = "" // will be overridden per-request
	}

workDir := a.workDir
if a.sandbox != nil && a.sandbox.Name() == "remote" && senderID != "" {
	if ws := a.sandbox.Workspace(senderID); ws != "" {
		workDir = ws
	}
}

git add agent/context.go agent/middleware.go
git commit -m "fix(prompt): resolve remote sandbox workspace for system prompt"

// Skill/agent sync config
	globalSkillDirs []string // server-side global skill directories
	agentsDir       string   // server-side global agents directory

// RemoteSandboxSyncConfig holds directories to sync to runners on registration.
type RemoteSandboxSyncConfig struct {
	GlobalSkillDirs []string // server-side global skill directories
	AgentsDir       string   // server-side global agents directory
}

func NewRemoteSandbox(cfg RemoteSandboxConfig, syncCfg RemoteSandboxSyncConfig) (*RemoteSandbox, error) {

	rs := &RemoteSandbox{
		// ... existing fields ...
		globalSkillDirs: syncCfg.GlobalSkillDirs,
		agentsDir:       syncCfg.AgentsDir,
	}

	// Sync global skills and agents to runner on registration
	go rs.syncToRunner(reg.UserID, reg.Workspace)

// syncToRunner copies global skills and agents to the runner's workspace.
// Runs in a goroutine after registration; errors are logged, not fatal.
func (rs *RemoteSandbox) syncToRunner(userID, workspace string) {
	if workspace == "" || (len(rs.globalSkillDirs) == 0 && rs.agentsDir == "") {
		return
	}

	ctx, cancel := context.WithTimeout(context.Background(), 60*time.Second)
	defer cancel()

	log.WithFields(log.Fields{
		"user_id":  userID,
		"workspace": workspace,
	}).Info("Syncing global skills/agents to runner")

	// Sync skills
	for _, srcDir := range rs.globalSkillDirs {
		rs.syncDirToRunner(ctx, userID, workspace, srcDir, ".skills")
	}

	// Sync agents
	if rs.agentsDir != "" {
		rs.syncAgentsToRunner(ctx, userID, workspace, rs.agentsDir, ".agents")
	}

	log.WithField("user_id", userID).Info("Skill/agent sync to runner complete")
}

// syncDirToRunner copies skill subdirectories from a server directory to the runner.
func (rs *RemoteSandbox) syncDirToRunner(ctx context.Context, userID, workspace, srcDir, dstSubdir string) {
	entries, err := os.ReadDir(srcDir)
	if err != nil {
		log.WithError(err).Warnf("syncToRunner: cannot read skill dir %s", srcDir)
		return
	}

	for _, e := range entries {
		if !e.IsDir() {
			continue
		}
		srcSkill := filepath.Join(srcDir, e.Name())
		dstSkill := filepath.Join(workspace, dstSubdir, e.Name())
		rs.syncTreeToRunner(ctx, userID, srcSkill, dstSkill)
	}
}

// syncAgentsToRunner copies .md agent files from a server directory to the runner.
func (rs *RemoteSandbox) syncAgentsToRunner(ctx context.Context, userID, workspace, srcDir, dstSubdir string) {
	entries, err := os.ReadDir(srcDir)
	if err != nil {
		log.WithError(err).Warnf("syncToRunner: cannot read agents dir %s", srcDir)
		return
	}

	for _, e := range entries {
		if e.IsDir() || !strings.HasSuffix(e.Name(), ".md") {
			continue
		}
		srcPath := filepath.Join(srcDir, e.Name())
		dstPath := filepath.Join(workspace, dstSubdir, e.Name())
		rs.syncFileToRunner(ctx, userID, srcPath, dstPath)
	}
}

// syncTreeToRunner recursively copies a directory tree to the runner.
func (rs *RemoteSandbox) syncTreeToRunner(ctx context.Context, userID, srcDir, dstDir string) {
	entries, err := os.ReadDir(srcDir)
	if err != nil {
		return
	}
	for _, e := range entries {
		srcPath := filepath.Join(srcDir, e.Name())
		dstPath := filepath.Join(dstDir, e.Name())
		if e.IsDir() {
			rs.syncTreeToRunner(ctx, userID, srcPath, dstPath)
		} else {
			rs.syncFileToRunner(ctx, userID, srcPath, dstPath)
		}
	}
}

// syncFileToRunner copies a single file to the runner.
func (rs *RemoteSandbox) syncFileToRunner(ctx context.Context, userID, srcPath, dstPath string) {
	data, err := os.ReadFile(srcPath)
	if err != nil {
		log.WithError(err).Warnf("syncToRunner: cannot read %s", srcPath)
		return
	}

	if err := rs.MkdirAll(ctx, filepath.Dir(dstPath), 0o755, userID); err != nil {
		log.WithError(err).Warnf("syncToRunner: mkdir %s", filepath.Dir(dstPath))
		return
	}

	if err := rs.WriteFile(ctx, dstPath, data, 0o644, userID); err != nil {
		log.WithError(err).Warnf("syncToRunner: write %s", dstPath)
		return
	}
}

	// V4: remote 模式下跳过全局 skill 同步（skill 由 remote sandbox 管理）
	if ctx.Sandbox != nil && ctx.Sandbox.Name() == "remote" {
		return
	}

	// Remote mode: skills are synced on runner registration, skip host-side sync
	if ctx.Sandbox != nil && ctx.Sandbox.Name() == "remote" {
		return
	}

git add tools/remote_sandbox.go tools/skill_sync.go
git commit -m "feat(remote-sandbox): sync global skills/agents to runner on registration"

Sandbox:     &mockSandbox{name: "docker", workspace: "/workspace"},
OriginUserID: "test-user",

		SandboxWorkDir:       env.tmpDir,

git add agent/engine_test.go agent/integration_test.go
git commit -m "test: update engine tests to use Sandbox.Workspace instead of SandboxWorkDir"

git add -A
git commit -m "chore: final cleanup for remote sandbox workspace unification"