sandbox

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 context.Context, tokenCtx 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"`
	Progress   string `json:"progress,omitempty"`
	Done       string `json:"done,omitempty"`
	Fail       string `json:"fail,omitempty"`

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

	// task ask fields. Question carries the blocking-RPC question text for
	// `boid task ask <text>`. The broker holds the connection open until the
	// answer arrives; the answer is returned verbatim in ExecResponse.Stdout
	// (the boid builtin reply framing is ExecResponse, so no separate
	// BoidResponse type is needed).
	Question string `json:"question,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
	// MissingSecrets lists "ENV_NAME (secret:key)" entries for env vars that
	// the kit declared via the "secret:" prefix but failed to resolve at
	// register time. When non-empty, the broker rejects exec requests for
	// this command (fail-closed) instead of silently letting host env /
	// host-side config fallbacks take over.
	MissingSecrets []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"`
	Fetch     *FetchRequest `json:"fetch,omitempty"`
	Streaming bool          `json:"streaming,omitempty"`
}

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

type FetchRequest struct {
	URL string `json:"url"`
}

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"`
	SetUpstream    bool     `json:"set_upstream,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 HarnessType string

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 NFTRule struct {
	Args []string
}

type Plan struct {
	Mounts       []Mount
	Files        []FileWrite
	Symlinks     []Symlink
	NFTRules     []NFTRule
	CleanupPaths []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 the job id; it namespaces the generated /tmp/boid-<ID>-* files.
	ID string

	// --- Filesystem primitives ---
	// Mounts are applied in order to compose the sandbox root filesystem.
	Mounts []Mount
	// Files are materialized inside the sandbox (after pivot_root) before the
	// entry command runs.
	Files []FileWrite
	// Symlinks are created inside the sandbox.
	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. Also used as the cwd reported to
	// the broker for the job-done call (must be within the project/worktree root).
	WorkDir string
	// Env is the environment for the entry process.
	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. Doubles as the job-done output fallback when no payload patch exists.
	StdoutCaptureFile string
	// TTY, when true, the entry process inherits the caller's PTY on stdio.
	TTY bool

	// --- Completion / broker ---
	// Foreground indicates a user-facing job (boid exec): stdout/stderr are
	// inherited and no broker job-done callback fires on exit. Hook jobs leave
	// this false so the runner posts `boid job done` through the broker.
	Foreground bool
	// PayloadPatchPath is the sandbox-internal path the agent writes its result
	// patch to (HOME/.boid/output/payload_patch.json). The runner reads it as the
	// job-done output. Broker socket path and token are carried in Env
	// (BOID_BROKER_SOCKET / BOID_BROKER_TOKEN).
	PayloadPatchPath string

	// --- Bookkeeping ---
	// RootDir, if non-empty, is the host directory used as the sandbox ROOT (a
	// tmpfs is mounted on it). Go-side cleanup removes it after exit.
	RootDir string
	// CleanupPaths are removed by runner-outer after the sandbox process tree
	// exits (used for staging dirs). Removal runs in the host mount namespace,
	// where the sandbox's bind mounts are already gone.
	CleanupPaths []string
	// HarnessType, when non-empty, directs runner-inner-child to hand the
	// agent process off to the matching HarnessAdapter.Run() instead of
	// exec-ing Argv verbatim. Empty preserves the legacy exec path used by
	// boid exec jobs and any non-agent hook job. See sandbox.HarnessType.
	HarnessType HarnessType

	// UserAnswer carries the Q&A reply that should be threaded into the
	// adapter's RunContext.UserAnswer. Empty for fresh starts and for resumes
	// without a Q&A reply.
	UserAnswer 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
}