workspace

type AgentsInstructionFile struct {
	// Path 是这份 AGENTS.md 清理后的绝对路径。
	Path string
	// Text 是文件全文。
	Text string
}

type DirectoryEntry struct {
	Name        string
	IsDirectory bool
	IsFile      bool
}

type DirectoryFile struct {
	// RelativePath 是相对遍历根目录的路径，用 / 分隔。
	RelativePath string
	// Mode 是跟随符号链接后的权限位。
	Mode        fs.FileMode
	IsDirectory bool
}

type FileContent struct {
	Content []byte
	// Size 是文件报告的大小；/proc 等文件可能为 0。
	Size int64
	// EOF 这次读取是否已经读到文件末尾？
	EOF bool
}

type FileMetadata struct {
	IsDirectory bool
	// IsFile 是不是普通文件？
	IsFile     bool
	IsSymlink  bool
	Size       int64
	Mode       fs.FileMode
	ModifiedAt time.Time
}

type LocalWorkspaceOpt struct {
	// RootDirectory 是工作区根目录，必须是绝对路径。
	RootDirectory string
	// Environment 是执行命令用的环境变量，格式同 os.Environ；为 nil 时继承当前进程的环境。
	Environment []string
}

type Process interface {
	// Wait 等待命令结束并返回退出码；返回时输出已全部写入请求中的 Writer。被 Terminate 结束时退出码为 -1。
	Wait() (int, error)
	// Terminate 结束命令所在的整个进程组；没能确认结束时返回错误，可以重试；进程组已不存在时返回 nil。
	Terminate() error
	// WriteTerminalInput 把 data 原样写进 TTY 命令的终端，返回实际写入的字节数；
	// 非 TTY 命令返回 ErrTTYInputUnsupported，命令已结束时返回写入错误。
	WriteTerminalInput(data []byte) (int, error)
	// ResizeTerminal 修改 TTY 命令的终端行列数；非 TTY 命令返回 ErrTTYInputUnsupported，virtual 命令返回 ErrTTYUnsupported。
	ResizeTerminal(rows, cols uint16) error
	// Close 放手这条命令：关闭本地这一端，让 Wait 尽快返回。SSH 关闭命令的会话，不证明远端已停止，Wait 随后返回错误；
	// 本机和 virtual 等同于 Terminate。只在不能无限等待的收尾路径上、Terminate 失败之后调用。
	Close() error
}

type ProcessRequest struct {
	// Command 是交给 bash -c 执行的命令文本。
	Command string
	// Directory 是命令的工作目录，绝对路径。
	Directory string
	// TTY 是否在终端里运行命令？在终端里运行时输出全部写入 Stdout。
	TTY bool
	// Rows、Cols 是 TTY 命令的初始终端行列数；为零时按 24×80。
	Rows, Cols uint16
	// Stdin 是非 TTY 命令的一次性输入，nil 时读到空输入；TTY 命令的输入用 Process.WriteTerminalInput，传 Stdin 返回错误。
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
}

type SSHWorkspace interface {
	Workspace
	// Close 关闭当前连接；之后的调用返回 net.ErrClosed。可重复调用。
	Close() error
}

type SSHWorkspaceOpt struct {
	// RootDirectory 是远端工作区根目录的绝对路径。
	RootDirectory string
	// Address 是 [user@]host[:port]；省略 user 时使用本机用户名，省略 port 时为 22。
	Address string
	// IdentityFile 是本机私钥路径，可为空。
	IdentityFile string
	// Telemetry 是遥测管道，用于连接建立、断开与保活失败的日志；nil 时使用全局兜底。
	Telemetry *telemetry.Telemetry
}

type VirtualFile struct {
	// Content 是现成的文件内容。
	Content []byte
	// Load 在第一次读取时调用一次，返回文件内容。
	Load func(ctx context.Context) ([]byte, error)
}

type VirtualWorkspaceOpt struct {
	// RootDirectory 是工作区在虚拟文件系统中的绝对路径，省略时为 /workspace。
	RootDirectory string
	// Files 是创建时写入的文件，键为绝对路径，父目录自动创建。
	Files map[string]*VirtualFile
}

type Workspace interface {
	// GetRootDirectory 返回工作区根目录的绝对路径，工具以它为相对路径的基准。
	GetRootDirectory() string
	// GetHomeDirectory 返回工作区所在机器上当前用户的主目录：本机是 serve 进程的用户（os.UserHomeDir），
	// SSH 是登录用户（SFTP 的初始目录，sftp.Client.Getwd）；virtual 没有主目录，返回 errors.ErrUnsupported。
	GetHomeDirectory(ctx context.Context) (string, error)
	// ReadFile 跟随符号链接，从 offset 起读取最多 limit 字节，不足时读到文件末尾；目标不是普通文件时返回 ErrNotRegularFile。
	ReadFile(ctx context.Context, path string, offset int64, limit int) (*FileContent, error)
	// WriteFile 写入完整内容，父目录须已存在；目标在工作区外时返回 ErrOutsideWorkspace；
	// createOnly 且目标已存在时返回满足 fs.ErrExist 的错误。
	WriteFile(ctx context.Context, path string, content []byte, mode fs.FileMode, createOnly bool) error
	// OpenFileReader 打开文件顺序读取，跟随符号链接，不限于工作区根目录；path 为相对根目录的路径或绝对路径。
	// 文件不存在时返回满足 fs.ErrNotExist 的错误；读完由调用方 Close。ctx 只约束打开。
	OpenFileReader(ctx context.Context, path string) (io.ReadCloser, error)
	// CreateFileWriter 创建或覆盖一个文件并返回写入端，权限位为 mode（不受 umask 影响）；
	// path 为相对根目录的路径或绝对路径，可以在根目录外；父目录不存在时创建；Close 返回 nil 才算写完。ctx 只约束创建。
	CreateFileWriter(ctx context.Context, path string, mode fs.FileMode) (io.WriteCloser, error)
	// GetMetadata 返回路径的元数据；followSymlinks 为 false 时描述符号链接本身；不存在时返回满足 fs.ErrNotExist 的错误。
	GetMetadata(ctx context.Context, path string, followSymlinks bool) (*FileMetadata, error)
	// ReadDirectory 按名称顺序返回目录的直接子项，不跟随符号链接。
	ReadDirectory(ctx context.Context, path string) ([]*DirectoryEntry, error)
	// CreateDirectory 递归创建工作区内的目录，已存在时成功。
	CreateDirectory(ctx context.Context, path string) error
	// Remove 删除工作区内的一个文件或空目录。
	Remove(ctx context.Context, path string) error
	// StartProcess 在 request.Directory 启动一条 bash 命令；ctx 只约束启动，结束命令使用 Process.Terminate。
	// request.Stdin 非 nil 时，调用方不再写入后要关闭它的写端，命令才能结束读取。
	StartProcess(ctx context.Context, request *ProcessRequest) (Process, error)
	// Dial 从工作区所在的机器建立一条网络连接：本机直接连；SSH 经这条 SSH 连接转发，由远端发起，
	// 地址也在远端解析；virtual 返回 errors.ErrUnsupported。
	Dial(ctx context.Context, network, address string) (net.Conn, error)
	// GetHTTPProxy 返回从工作区所在机器发出 HTTP 请求时要经过的代理，签名同 http.Transport.Proxy：
	// 本机按 serve 进程的 HTTPS_PROXY、HTTP_PROXY、NO_PROXY（http.ProxyFromEnvironment）；
	// SSH 拿不到远端 shell 的代理设置，返回 nil 表示直连；virtual 返回 nil。
	GetHTTPProxy(request *http.Request) (*url.URL, error)
}