sandbox

type BasicMountEntry struct {
	Source   string
	Target   string
	ReadOnly bool
}

type BindMount struct {
	Source   string
	Target   string // if empty, defaults to Source
	Mode     string // "rw" | "" (ro default)
	IsFile   bool   // if true, treat target as a file (touch before bind, skip type detection)
	Optional bool   // if true, skip mount when Source does not exist on the host
}

type BoidExecutor interface {
	ExecuteBoidBuiltin(ctx TokenContext, req *BoidRequest) *ExecResponse
}

type BoidOp string

type BoidRequest struct {
	Op        BoidOp `json:"op"`
	JobID     string `json:"job_id,omitempty"`
	TaskID    string `json:"task_id,omitempty"`
	TaskField string `json:"task_field,omitempty"`
	// ProjectID is extracted by the shim for broker authorization / project
	// resolver; it is also present inside CreatePatch when the YAML includes
	// project_id. The executor prefers createReq.ProjectID from CreatePatch
	// and falls back to this field, then to ctx.ProjectID.
	ProjectID string `json:"project_id,omitempty"`

	ExitCode int    `json:"exit_code,omitempty"`
	Output   string `json:"output,omitempty"`

	// CreatePatch is a JSON-serialised api.CreateTaskRequest. The shim builds
	// it from the full YAML map so that every field (including previously
	// dropped ones such as instructions, traits, readonly, worktree,
	// branch_prefix, id) is forwarded without enumeration.
	CreatePatch json.RawMessage `json:"create_patch,omitempty"`

	// UpdatePatch is a JSON-serialised api.UpdateTaskRequest. The shim
	// assembles it from --patch-file and/or individual flags (--title,
	// --description, --payload-file).
	UpdatePatch json.RawMessage `json:"update_patch,omitempty"`

	// task import fields
	ImportTasks           []json.RawMessage `json:"import_tasks,omitempty"`
	ImportProjectOverride string            `json:"import_project_override,omitempty"`

	// task list fields
	WorkspaceID string `json:"workspace_id,omitempty"`
	Status      string `json:"status,omitempty"`
	Limit       int    `json:"limit,omitempty"`

	// task notify fields
	Message    string `json:"message,omitempty"`
	Ask        string `json:"ask,omitempty"`
	QuestionID string `json:"question_id,omitempty"`
	SessionID  string `json:"session_id,omitempty"`
	Progress   string `json:"progress,omitempty"`
	Done       string `json:"done,omitempty"`
	Fail       string `json:"fail,omitempty"`

	// task answer fields
	Answer string `json:"answer,omitempty"`

	// task delete fields
	Force bool `json:"force,omitempty"`

	// action send fields
	ActionType string `json:"action_type,omitempty"`
	Payload    []byte `json:"payload,omitempty"`
}

type Broker struct {
	SocketPath      string
	BoidBinary      string
	BoidExecutor    BoidExecutor
	ProjectResolver ProjectResolver
	// contains filtered or unexported fields
}

type BuiltinPolicy struct {
	AllowedOps map[string]struct{}
	// AllowedCwdRoots lists additional cwd roots permitted for this builtin
	// beyond the per-token entry root (project/worktree dir). Used so that
	// e.g. gate jobs can target /tmp or the host project dir without the
	// broker needing to know the role itself.
	AllowedCwdRoots []string
}

type CommandDef struct {
	Name               string
	Path               string
	AllowedPatterns    []string
	DeniedPatterns     []string
	AllowedSubcommands []string
	AllowStdin         bool
	Env                map[string]string
}

type ExecRequest struct {
	Command   string       `json:"command"`
	Args      []string     `json:"args"`
	Cwd       string       `json:"cwd,omitempty"`
	Stdin     []byte       `json:"stdin,omitempty"`
	Token     string       `json:"token"`
	Boid      *BoidRequest `json:"boid,omitempty"`
	Git       *GitRequest  `json:"git,omitempty"`
	Streaming bool         `json:"streaming,omitempty"`
}

type ExecResponse struct {
	ExitCode int    `json:"exit_code"`
	Stdout   string `json:"stdout"`
	Stderr   string `json:"stderr"`
}

type FileWrite struct {
	Path    string // absolute path inside sandbox
	Content string
}

type GitBinding struct {
	ProjectDir     string
	WorktreeRoot   string
	SnapshotBranch string
	Upstream       GitUpstream
	Remotes        map[string]GitRemote
}

type GitOp string

type GitRemote struct {
	FetchURL string
	PushURL  string
}

type GitRequest struct {
	Op             GitOp    `json:"op"`
	Remote         string   `json:"remote,omitempty"`
	Refspecs       []string `json:"refspecs,omitempty"`
	DryRun         bool     `json:"dry_run,omitempty"`
	Verbose        bool     `json:"verbose,omitempty"`
	Quiet          bool     `json:"quiet,omitempty"`
	Prune          bool     `json:"prune,omitempty"`
	Tags           bool     `json:"tags,omitempty"`
	Force          bool     `json:"force,omitempty"`
	Porcelain      bool     `json:"porcelain,omitempty"`
	ForceWithLease bool     `json:"force_with_lease,omitempty"`
	Delete         bool     `json:"delete,omitempty"`
	// Source and Dest are used exclusively for GitOpCloneLocal.
	// Source is the peer project path to clone from; Dest is the destination
	// directory within the current worktree. Both are validated by the broker.
	Source string `json:"source,omitempty"`
	Dest   string `json:"dest,omitempty"`
}

type GitUpstream struct {
	Remote   string
	MergeRef string
}

type HookFile struct {
	Source     string // host-side absolute path
	TargetName string // filename inside sandbox .boid/hooks/
}

type Mount struct {
	Source     string // host path (empty for tmpfs)
	Target     string // absolute path inside sandbox
	Type       MountType
	ReadOnly   bool
	Slave      bool     // mount --make-rslave after mounting
	IsFile     bool     // target is a file, not a directory
	DetectType bool     // detect file vs dir at runtime (if/elif)
	Guard      string   // shell test expression; if non-empty, wrap in if [ $Guard ]; then
	NeedsDirs  []string // subdirs to create under Target before ro remount
}

type MountType string

type ProjectResolver func(ref string) (uuid string, err error)

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

type Sandbox interface {
	Setup(cfg SandboxConfig) error
	Shell(windowName string, cmd string) (string, error)
	Cleanup() error
}

type SandboxConfig struct {
	ProjectDir    string
	WorkspaceDirs map[string]string // project-id -> dir (readonly mounts)
	TaskFile      string
	HostCommands  []string
	Bindings      []string
	Env           map[string]string
	BoidBinary    string
	BrokerSocket  string
	ServerSocket  string
}

type SecretResolver func(key string) (string, error)

type Spec struct {
	// ID is used to namespace the generated /tmp/boid-<ID>-{outer,setup,inner}.sh files.
	ID string

	// --- Filesystem primitives ---
	// Mounts are applied in order to compose the sandbox root filesystem.
	Mounts []Mount
	// Files are materialized inside the sandbox before the entry command runs.
	Files []FileWrite
	// Symlinks are created inside the sandbox (e.g. /opt/boid/bin/<cmd> → boid).
	Symlinks []Symlink

	// --- Network ---
	// ProxyPort, when > 0, engages the nft drop policy + HTTP proxy env vars.
	ProxyPort int

	// --- Process ---
	// Argv is the program and arguments to invoke (POSIX argv).
	Argv []string
	// WorkDir is the cwd for the entry process.
	WorkDir string
	// Env is exported before the entry command runs.
	Env map[string]string
	// StdinBytes, when non-empty, is piped into the entry's stdin.
	StdinBytes []byte
	// StdoutCaptureFile, when non-empty, redirects stdout to that sandbox-internal path.
	StdoutCaptureFile string
	// ExitScript is wrapped in `trap '<ExitScript>' EXIT`. Empty = no trap (suits exec-replaced shells).
	ExitScript string
	// TTY, when true, preserves the caller's TTY through pasta so Argv can run as a full terminal app.
	TTY bool

	// --- Bookkeeping ---
	// RootDir, if non-empty, is used as the sandbox ROOT directory so Go-side
	// cleanup can remove it after exit. If empty, setup script creates one with mktemp.
	RootDir string
	// CleanupPaths are removed by outer.sh after pasta returns (used for staging dirs).
	// Removal runs outside the sandbox mount namespace, so still-active bind
	// mounts cannot cause rm to traverse onto host files.
	CleanupPaths []string
}

type StreamChunk struct {
	Type     string `json:"type"`
	Data     string `json:"data,omitempty"`
	ExitCode int    `json:"exit_code,omitempty"`
}

type Symlink struct {
	LinkPath   string // absolute path inside sandbox (where the symlink is created)
	LinkTarget string // what the symlink points to (resolved relative to LinkPath)
}

type TokenContext struct {
	JobID             string
	TaskID            string
	ProjectID         string
	WorkspaceID       string
	AllowedProjectIDs []string
	Role              string
	// ProjectDir is the project's host-side work directory. Independent of
	// spec.Visibility.ProjectDir (which drives sandbox mount layout and is
	// intentionally empty for gate jobs): host-side operations the broker
	// performs on behalf of the sandbox (git binding, host-command cwd) have
	// their own notion of "which project are we operating on" that doesn't
	// care whether the sandbox itself can see the tree.
	ProjectDir  string
	WorktreeDir string
	// WorkspacePeers maps peer project IDs to their host-side work directories.
	// Used by the broker to validate git clone --local source paths: only paths
	// within a known peer project are permitted as clone sources.
	WorkspacePeers map[string]string
}