kit

type Entry struct {
	// Source is the original host path. Omitted from the on-disk
	// manifest so the sandbox cannot learn the host layout.
	Source string `json:"-"`
	// Target is the path relative to the kit root. Empty when the
	// file isn't staged into the kit because it's already reachable
	// inside the sandbox via the live workspace mount.
	Target string `json:"target,omitempty"`
}

type Manifest struct {
	AgentRef    string      `json:"agent_ref"`
	BuiltAt     time.Time   `json:"built_at"`
	Skills      []Entry     `json:"skills,omitempty"`
	PromptFiles []Entry     `json:"prompt_files,omitempty"`
	Redactions  []Redaction `json:"redactions,omitempty"`
}

type Options struct {
	// AgentRef is the user-facing reference to the agent (a YAML path,
	// an OCI ref, a URL or a builtin name). Used for cache keying and
	// for loading the team config so the kit knows which prompt files
	// and skills to ship.
	AgentRef string

	// EnvProvider is forwarded to [config.Resolve] so URL-sourced
	// agents can pick up GITHUB_TOKEN. May be nil.
	EnvProvider environment.Provider

	// HostCwd is the host's working directory. Prompt-file lookups
	// walk up from it the same way the in-sandbox runtime would.
	HostCwd string

	// HostHome overrides the host's $HOME for prompt-file lookups.
	// Empty means "use os.UserHomeDir".
	HostHome string

	// Workspace is the absolute host path that the sandbox mounts as
	// the agent's live working directory. Files under it are not
	// staged into the kit because the sandbox sees them through the
	// live mount; staging them would duplicate content and ship a
	// stale, redacted copy alongside the live one.
	Workspace string

	// CacheDir is the parent directory under which the kit will be
	// staged. Empty means "use [paths.GetCacheDir]/sandbox-kits".
	CacheDir string
}

type Redaction struct {
	// Source is the host path of the original file. Omitted from the
	// on-disk manifest for the same reason as [Entry.Source].
	Source string `json:"-"`
	// Target is the path relative to the kit root.
	Target string `json:"target"`
}

type Result struct {
	// HostDir is the absolute host path of the staged kit. Mount it
	// read-only at [MountPath] inside the sandbox and forward
	// `-e DOCKER_AGENT_KIT_DIR=<MountPath>` so the in-sandbox
	// resolvers find it.
	HostDir string

	// Manifest describes what was staged. It contains absolute host
	// source paths and is meant for caller-side inspection only — the
	// on-disk copy under <HostDir>/manifest.json is sanitised so the
	// sandbox cannot learn the host filesystem layout.
	Manifest Manifest

	// NeedsToolInstall reports whether the agent has at least one
	// MCP / LSP toolset that the in-sandbox runtime might auto-install
	// (the toolset has a Command set and Version isn't "false"/"off").
	// Callers use this to decide whether to allowlist the package
	// hosts the auto-installer reaches — we keep that gated so we
	// don't open holes in the sandbox proxy when no agent could
	// possibly need them.
	NeedsToolInstall bool
}