ptc

type Binding struct {
	Name string
	// Signature JS 调用形态，如 "get_logs(host, count)"。由宿主用自己的工具目录
	// 翻译而来——ptc 不认识任何 schema 类型。
	Signature string
	Call      func(ctx context.Context, argsJSON string) (string, error)
}

type CallRecord struct {
	Name   string `json:"name"`
	Status string `json:"status"` // ok|error
	Bytes  int    `json:"bytes"`
	MS     int64  `json:"ms"`
	Error  string `json:"error,omitempty"`
}

type Discovered struct {
	Name        string `json:"name"`
	Signature   string `json:"signature,omitempty"`
	Description string `json:"description,omitempty"`
}

type Discoverer func(query string) []Discovered

type ExecutionAborted struct {
	// Err 底层错误（管道 EOF 等）。
	Err error
	// Exit 子进程退出状态描述（如 "signal: killed" / "exit status 1"）。
	Exit string
	// Signaled 子进程是否被**信号**终止（被内核杀掉）。
	//
	// Unix 上被信号终止时 `ExitCode()` 返回 -1；Windows 上退出码恒为实际值。
	// 故这个判据跨平台成立，不需要按平台分实现。
	Signaled bool
	// Stderr 子进程 stderr 的尾部（崩溃原因就在这里），**已脱敏**。
	//
	// 没有它，宿主只看到一个退出码——而退出码分不清「被内核杀掉（兜底生效）」
	// 与「自己 fatal 退出（启动失败或 runtime 报错）」。这是**死因**，不是日志。
	//
	// 为什么是脱敏后的：子进程常把连接串、API key、token 打进 stderr
	// （MCP server 启动时的配置回显最常见），而这段文本会**原样**进诊断报告
	// 与错误消息——那等于凭据泄漏面。脱敏用上游 guardx/logredact（凭据形态打码），
	// 本仓 pii 管的是个人信息，两者互补不重叠。
	//
	// 脱敏发生在**写入这个字段时**（不是 Error() 渲染时）：字段是公开的，
	// 宿主可以直接读 e.Stderr——只在渲染面脱敏等于给宿主留了原文出口。
	Stderr string
}

type Options struct {
	Timeout  time.Duration
	MaxCalls int
	MaxBytes int
	// Discover 可选：暴露程序内工具发现入口 discover(query)。
	// 为 nil 则**根本不暴露**该全局——没装配的东西不该以空壳形式出现在沙箱里，
	// 那会让模型以为「没有别的工具了」而放弃检索。
	Discover Discoverer
	// Stages 每次绑定调用前必过的判定环，与普通工具调用走的是**同一套** Stage。
	//
	// # 为什么这条是必需的而不是可选优化
	//
	// 程序里的 host.<tool>(...) 直达宿主工具。若这里不接判定环，本包就成了
	// 「整条链上唯一绕过所有门禁的路径」：披露门不判、审计门不判、SSRF 出站门不判。
	// 而本包恰恰是对外推荐的那条路（N 轮 ReAct 塌缩成 1 轮、原始数据不过模型面），
	// 于是**看起来更安全的路径反而最不安全**——这正是 OpenCode 2.0 #52333 的形状：
	// 信任边界移动了，沙箱没跟着移动。
	//
	// 为 nil 时不接任何判定，行为与本包引入 Stages 之前逐字一致（不破坏既有调用方），
	// 但那条路径因此**不带门禁**——接入方须自行确认这是有意的。
	Stages []invoke.Stage
}

type Position struct {
	Line   int
	Column int
}

type Provider struct {
	// Bindings 挂给程序的宿主绑定。
	Bindings []Binding
	// Discover 程序内工具发现入口（nil = 不暴露该全局）。
	Discover Discoverer
	// Stages 每次绑定调用前必过的判定环（nil = 不接判定）。
	Stages []invoke.Stage
}

type Result struct {
	OK        bool
	Value     string // return 值的 JSON 文本（成功时恒合法 JSON，undefined→"null"）
	Error     string
	ErrorKind string
	// Location 出错位置（1-based 行列）。取不到时为零值——不猜：假的行号会让模型
	// 去改一行根本没问题的代码，比没有行号更坏。
	Location Position
	// Suggestions 面向模型的修复建议，由 ErrorKind 唯一决定（成功时为 nil）。
	Suggestions []string
	Calls       int
	Bytes       int
	CallLog     []CallRecord
	// contains filtered or unexported fields
}

type RunEnv struct {
	Table []ToolTableEntry
	OnRun func(Result)
}

type SubprocessOptions struct {
	// Program 被执行的程序体（由子进程里的 goja 解释）。
	Program string
	// Bindings 宿主工具绑定。**实现留在父侧**——子进程只拿到名字与调用形态。
	Bindings []Binding
	// Stages 每次绑定调用前必过的判定环（与普通工具调用同一套）。
	Stages []invoke.Stage
	// Timeout 墙钟期限。<=0 用 DefaultTimeout。
	Timeout time.Duration
	// MaxCalls 调用数上限。<=0 用 DefaultMaxCalls。
	MaxCalls int
	// MaxBytes 输出字节上限。<=0 用 DefaultMaxBytes。
	MaxBytes int
	// MaxMemory 内存上限（字节）。<=0 = 不要求。
	MaxMemory int64
	// Discover 可选：程序内工具发现入口。
	Discover Discoverer
	// Egress 子进程的出口要求（零值 = 不限制，行为与旧版逐字一致）。
	//
	// 为什么这个字段必须在**配置**上而不是靠子进程自己读环境：子进程起来之后
	// 它的出站流量完全在本进程 netguard 之外，父侧唯一能施加影响的时点就是
	// spawn 之前。装配（谁决定这一档）归宿主；兑现与判据归 egress。
	Egress egress.Spec
	// EgressBackend 兑现 Egress 声明的那个对象（通常是宿主起的强制代理）。
	//
	// # 为什么必须有这一格
	//
	// Egress 只写「要求哪一档」，它本身不会跑到任何地方去。而在 spawn 之前，
	// 父侧唯一能做的事就是问一句「**你**能兑现这一档吗」——没有这一问，
	// 声明与执行之间就没有任何信号：宿主写了「只经代理」，子进程照样裸奔出网，
	// 而报告里那一条显示「已声明」。
	//
	// # nil 的含义是「没人声明」，不是「不限制」
	//
	// 不填它而 Egress 又要求了限制 ⇒ **拒绝执行**（fail closed）。安全判据里
	// 沉默必须按最弱处理：「没人反对」不等于「做得到」。不要求限制时它不被问。
	//
	// 判据在 egress.Spec.SatisfiedBy，本字段只负责把兑现者带到位——判定与
	// 声明面同源，不在本包另立一套。
	EgressBackend egress.Enforcer
	// ExePath 子进程可执行文件路径。空 = 用宿主自己的可执行文件（re-exec）。
	//
	// **re-exec 宿主自己的二进制**是默认：随包发小二进制要宿主额外安装，
	// 接入成本高一个量级。代价是宿主要在 main 里加一行 `ptc.MaybeRunChild()`。
	ExePath string
}

type SubprocessProvider struct {
	// contains filtered or unexported fields
}

type ToolTableEntry struct {
	Name string
	Run  func(ctx context.Context, args string) (string, error)
}