execenv

type Class int

type DefaultExecutor struct{}

type Executor interface {
	Command(ctx context.Context, spec Spec) Process
}

type Process interface {
	// Start 启动子进程. 非阻塞, 和 *exec.Cmd.Start() 语义一致.
	// 错误场景: Path 不可达 / 权限不足 / 资源耗尽.
	Start() error

	// Wait 等待子进程退出, 返回 exit error (*exec.ExitError 或其他).
	// 必须在 Start() 成功后调用. 不能重复 Wait 同一进程.
	Wait() error

	// Run 便捷方法: Start() 然后 Wait() 一步.
	// 等价于 *exec.Cmd.Run(). 如果 Start 或 Wait 失败, 返回对应 error.
	//
	// 大量 caller (hooks / evolve / memory git / grep_engine / plugin_tool)
	// 用 cmd.Run() 一步跑完, 不想手写 Start+Wait 样板. 加入便捷方法让
	// 迁移成本最小化. backend 实现 = trivial 的 Start+Wait 包装.
	Run() error

	// StdinPipe 返回子进程标准输入的写入端. 必须在 Start() 前调用.
	// 返回的 WriteCloser 在 Wait() 后自动关闭.
	//
	// 和 Spec.Stdin 字段互斥: 设了 Stdin 字段不能再调 StdinPipe,
	// 对齐 *exec.Cmd 语义. 长驻双向通信场景 (stdio transport / memory
	// external scorer) 用 StdinPipe.
	StdinPipe() (io.WriteCloser, error)

	// StdoutPipe 返回子进程标准输出的读取端. 必须在 Start() 前调用.
	// 返回的 ReadCloser 在 Wait() 后自动关闭.
	// 和 Spec.Stdout 字段互斥.
	StdoutPipe() (io.ReadCloser, error)

	// StderrPipe 返回子进程标准错误的读取端. 必须在 Start() 前调用.
	// 返回的 ReadCloser 在 Wait() 后自动关闭.
	// 和 Spec.Stderr 字段互斥.
	StderrPipe() (io.ReadCloser, error)

	// Signal 向子进程发送任意信号 (SIGINT / SIGTERM / SIGHUP 等).
	// 等价于 *exec.Cmd.Process.Signal(sig). 如果进程未 Start 或已退出,
	// 返回 error. 用于 graceful shutdown 路径 (先 SIGINT 后 SIGKILL).
	//
	// 云端 backend 映射为信号转发到 microVM 内部的进程. 不支持的信号
	// (如某些实时信号) 由 backend 决定是映射还是 error.
	Signal(sig os.Signal) error

	// Kill 强制终止子进程 (SIGKILL 等价). 幂等: 未 Start 或已 Wait
	// 后调用返回 nil, 不 panic.
	//
	// Kill 是 Signal(syscall.SIGKILL) 的快捷方式, 单独保留是因为它是
	// 最常见的终止路径, 且幂等保证让 defer p.Kill() 可以无条件使用.
	Kill() error

	// SignalGroup 向子进程所在的 process group 发送信号.
	//
	// 和 Signal 的区别: Signal 只作用单个子进程 (叶子), SignalGroup
	// 作用整个 process group (含子 shell 派生的孙进程). bash 的
	// graceful kill 路径和 plugin_tool 的 force kill 路径依赖此语义
	// 来彻底清理进程树, 防止孤儿进程继续持有 /workspace fd 或网络端口.
	//
	// # 前置条件
	//
	// 必须在创建时设 Spec.IsolateProcessGroup=true, 让子进程成为独立
	// pgid 的 leader. 否则子进程继承父进程的 pgid, SignalGroup 会
	// 精确退化为 Signal 单进程语义 — 不会对父 pgid 发信号, 因为那
	// 会把宿主 (engine 本身) 一起杀掉. 退化路径让此方法在任何场景下
	// 调用都安全, 但 caller 应遵守前置条件获得真正的 group 语义.
	//
	// # Backend 语义
	//
	//   - 本地 DefaultExecutor: syscall.Kill(-pgid, sig) on Unix.
	//     Windows 退化为 Kill (Job Object 方案未来再做, 当前 core
	//     已是 POSIX-only 约束, 详见 default_executor.go 注释).
	//   - 云端 backend: 信号转发给 microVM 内整个 pgid, 或直接信号
	//     microVM 本身 (等效).
	//
	// # 为什么不在 Signal 里加 group 参数
	//
	// Signal 语义对齐 *exec.Cmd.Process.Signal (单进程), 改签名会
	// 破坏所有现有 caller. SignalGroup 作为独立方法让现有 Signal
	// caller (SIGHUP / SIGINT 的 graceful shutdown 单进程路径) 零破坏.
	//
	// 2026-04-15 commit 7a 新增, 为 bash/plugin_tool 的 pgid-level
	// kill 路径提供抽象. 是 M1 唯一**必须**扩容的 interface 方法 —
	// duck-type 解决不了 group 语义. 详见 platform/sandbox/DESIGN.md
	// section 7 和 next-session-task.md 的 pre-audit.
	SignalGroup(sig os.Signal) error

	// Output 便捷方法: Run + 读取 stdout 全部字节. 等价于 *exec.Cmd.Output().
	// 不能和 StdoutPipe / Spec.Stdout 混用.
	//
	// 为什么加这个便捷方法 (超出 DESIGN section 7 原 5 方法):
	// syslib/git + worktree + context 等代码大量用 cmd.Output() 一步拿
	// stdout. 如果 Process 只有 pipe + start + wait, 每个 caller 要多写
	// 5-10 行 pipe+read+wait 样板, 迁移成本翻倍. backend 实现成本 =
	// 一次性写 start+read+wait 包装.
	Output() ([]byte, error)

	// CombinedOutput 便捷方法: Run + 读取 stdout+stderr 合并字节.
	// 等价于 *exec.Cmd.CombinedOutput(). 不能和任何 Pipe / Spec Writer 混用.
	CombinedOutput() ([]byte, error)

	// ID 返回后端无关的进程标识符, 用于日志 / 任务追踪 / UI 展示.
	//
	// 本地 DefaultExecutor 返回 strconv.Itoa(cmd.Process.Pid), 云端
	// backend 返回 microVM_id 或 task_id. caller 只能把它当 opaque 字符串
	// 用, 不应解析回 pid 做进程操作 — 那是非 portable 的 POSIX 假设,
	// 违反 "不锁死 POSIX 进程模型" 红线.
	//
	// 如果进程未 Start 或 ID 不可用, 返回空字符串.
	ID() string
}

type Spec struct {
	// Class 是租户隔离粒度和信任级别的唯一信号源. 必填.
	Class Class

	// Path 是可执行文件路径 (宿主视角). 云端 backend 负责翻译成
	// 容器内路径 (例如 /usr/bin/git 在 microVM 里也是 /usr/bin/git).
	Path string

	// Args 是 Path 之后的参数列表, 不包含 Path 本身.
	// 对齐 exec.Command(name, arg ...string) 的第二参数语义.
	Args []string

	// Env 是经 execenv helper 构造后的最终环境变量 map.
	// 已按信任类归类 (白名单类 A / 全继承类 B), backend 不再做过滤.
	//
	// 陷阱警告: nil map 会让 DefaultExecutor 走 *exec.Cmd 默认行为
	// (继承 os.Environ 全部变量), 不是 "空 env". 类 A 白名单调用方
	// 必须传非 nil 的 map (通过 MinimalEnvMap helper 构造), 否则
	// 白名单失守, 秘密泄漏到陌生代码子进程.
	//
	// 强制约定: 调用方永远不自己写 map[string]string{} 或 nil,
	// 永远走 execenv 包的 helper 函数 (MinimalEnvMap / FullInheritMap
	// 等, 将在迁移阶段陆续新增). 这让陷阱在产品代码路径上不可达.
	Env map[string]string

	// Stdin 是子进程标准输入 (Reader 模式). 可为 nil 表示无 stdin.
	//
	// 和 StdinPipe() 方法二选一: 设了 Stdin 字段不能再调 StdinPipe,
	// 对齐 *exec.Cmd 语义. 大部分 caller 用 Stdin 字段 (简单场景),
	// 只有长驻双向通信 (stdio transport / memory scorer) 用 StdinPipe.
	Stdin io.Reader

	// Stdout 是子进程标准输出的写入目标 (Writer 模式). 可为 nil 表示
	// 丢弃 (走 /dev/null) 或走 StdoutPipe.
	//
	// 和 StdoutPipe() 方法二选一: 设了 Stdout 字段不能再调 StdoutPipe,
	// 对齐 *exec.Cmd 语义. 2026-04-15 caller-driven audit 发现 8+ caller
	// 用 Writer 模式 (cmd.Stdout = &bytes.Buffer{}), 只有 bash / bash_background
	// 用 Pipe 模式. 不支持 Writer 模式会让迁移成本暴涨, 所以加入 Spec.
	Stdout io.Writer

	// Stderr 是子进程标准错误的写入目标 (Writer 模式). 可为 nil.
	// 和 StderrPipe() 方法二选一. 语义和 Stdout 对称.
	Stderr io.Writer

	// WorkDir 是子进程工作目录 (LLM 感知的 cwd).
	// 云端 backend 翻译为 /workspace 的 bind mount 挂载点.
	WorkDir string

	// IsolateProcessGroup 请求后端把子进程隔离到独立进程组.
	//
	// 本地模式: DefaultExecutor 映射为 syscall.SysProcAttr{Setpgid: true, Pgid: 0},
	// 让 Kill/Signal 能作用于整个进程树 (防止子 shell 派生的孙进程成为孤儿).
	// 云端模式: E2B microVM 天然是隔离边界, 后端忽略此字段.
	//
	// 意图级字段, 刻意不暴露 POSIX 的 SysProcAttr 结构 — 后者是跨平台
	// 不兼容的底层 API, 违反 "Spec 只装跨 Class 通用信息" 红线.
	// ClassBash 的 caller (bash / bash_background) 必须显式设为 true,
	// 其他 Class 按需.
	IsolateProcessGroup bool

	// TenantID 是多租户隔离的身份标签. platform 层填充.
	// DefaultExecutor 忽略此字段 (本地 CLI 无多租户概念).
	//
	// core 层永远不自己填 TenantID, 这是 platform 层 tenant 包
	// 从 HTTP request 上下文解析后在 engine.New 之前注入的.
	TenantID string
}