shell

type Command struct {
	// Name is what the script types, e.g. "grep". Required, unique per shell.
	Name string
	// Summary is one short line for the tool description the model reads,
	// e.g. "search text (-r -n -l -i -c -v -E -o -w)". Required.
	Summary string
	// Run executes one invocation. It returns nil for exit status 0, an
	// ExitError for another status, and any other error for a failure the
	// shell reports on stderr with status 1. Run must honour ctx.
	//
	// Run is called concurrently: the commands of a pipeline and background
	// jobs run at once, and one Command may be registered with several
	// Shells, so it must be safe for concurrent use. The Invocation and its
	// streams belong to that call only: the shell owns Stdin, Stdout and
	// Stderr (Run must not close them) and they must not be used after Run
	// returns; a goroutine Run starts must end before Run returns. A panic is
	// reported as an internal error with status 2.
	Run func(ctx context.Context, invocation *Invocation) error
}

type ExitError uint8

type ExternalOptions struct {
	// Name is the command name scripts use, e.g. "git". Required, one word.
	Name string
	// Path is the absolute path of the host binary, e.g. "/usr/bin/git".
	// Required; External checks that it exists.
	Path string
	// Directory is the host working directory of the program, e.g. a git
	// checkout. Required and absolute. The program sees the host file
	// system there, not the workspace, and the shell's cd does not move it
	// unless FollowWorkingDirectory is set.
	Directory string
	// FollowWorkingDirectory declares Directory the host path of the
	// workspace root (a workspace that is an osfs Storage over Directory):
	// the program then runs in the host directory that matches the shell's
	// working directory, so "cd repos/app && git status" works on that
	// checkout. A working directory that exists only in the shell (made by
	// mkdir, not on disk) fails the run.
	FollowWorkingDirectory bool
	// Environment is the complete environment of the program as
	// NAME=value; nil or empty means none. The host environment and the
	// script's variables are never passed.
	Environment []string
	// Allow, if set, is asked before every run with the arguments (without
	// the name). A non-nil error refuses the run: its text goes to stderr
	// and the exit status is 1. It is called concurrently when a script runs
	// the program in a pipeline or a background job, and from every Shell
	// the Command is registered with, so it must be safe for concurrent
	// use. The slice is a copy it may keep or change.
	Allow func(arguments []string) error
	// Timeout bounds one run; zero means none beyond the shell's own
	// timeout. A program that runs out of time is killed with its process
	// group (exit status 124).
	Timeout time.Duration
	// Summary is the line the tool description shows; empty means "host
	// program <Path>".
	Summary string
}

type Invocation struct {
	// Arguments are the arguments after the command name, already expanded by
	// the shell (globs, variables, quotes).
	Arguments []string
	// Stdin, Stdout and Stderr are the command's streams. Output written to
	// them is bounded by the shell, not by the command.
	Stdin  io.Reader
	Stdout io.Writer
	Stderr io.Writer
	// Directory is the shell's working directory as a path of Storage
	// without leading slash: "" is "/". With the default MountPoint "/" it
	// is a workspace path; with MountPoint "/work/repo" the workspace root
	// is "work/repo".
	Directory string
	// Storage is what the script sees: the workspace at the MountPoint, with
	// /tmp and /dev/fd mounted. Commands resolve operands against Directory
	// with Resolve and never touch host files.
	Storage vfs.Storage
	// Environment holds the shell's exported variables as NAME=value.
	Environment []string
	// contains filtered or unexported fields
}

type Options struct {
	// Storage is the workspace the script sees at MountPoint. Required.
	Storage vfs.Storage
	// MountPoint is the absolute path where the workspace appears in the
	// shell, "/" when empty. Scripts start there; pwd, realpath and find
	// print paths below it. Other paths are missing, except /tmp and /dev.
	// Set it to the host directory a Storage mirrors (an osfs over that
	// directory) so built-in commands and External programs agree on every
	// absolute path. It must not be /tmp or lie in /dev; below /tmp it is
	// fine (the workspace then shows up in /tmp next to the scratch files).
	MountPoint string
	// HideHiddenPaths hides workspace files with a path segment that starts
	// with "." or "_" (.env, .git/hooks, _private), the rule of
	// agent.VFSToolOptions.HideHiddenPaths: listings, globs, ls, find and
	// grep -r leave them out, and reading, writing or deleting one fails
	// with "No such file or directory". /tmp is not affected. The rule
	// checks the path as spelled: over a Storage that follows symbolic
	// links, a visible link (public -> .env) reaches a hidden file, so pair
	// it with osfs.Options.RefuseSymlinks (the CLI does).
	HideHiddenPaths bool
	// Commands are added to the built-in commands (Builtins); a Command with
	// the name of a built-in replaces it. Names must be unique, and must not
	// be shell builtins (cd, echo, test, ...), which the interpreter runs
	// itself.
	Commands []Command
	// Environment holds the variables a script starts with, as NAME=value.
	// The host environment is never passed. HOME defaults to MountPoint.
	Environment []string
	// Timeout bounds one Run; zero means DefaultTimeout, negative disables
	// it. A script that runs out of time is stopped with exit status 124.
	Timeout time.Duration
	// MaximumOutputBytes bounds Result.Output (stdout and stderr together):
	// the first and the last half are kept, the middle is cut with a marker
	// that counts against the limit (a limit too small for the marker keeps
	// the halves without it).
	// Zero means DefaultMaximumOutputBytes, negative keeps everything.
	MaximumOutputBytes int
	// ToolName is the name Register gives the tool; empty means
	// DefaultToolName.
	ToolName string
}

type Result struct {
	// Output is stdout and stderr interleaved as the script wrote them,
	// bounded by Options.MaximumOutputBytes.
	Output string
	// ExitCode is the script's exit status, as $? would show it: 127 for a
	// command that does not exist, 124 when the timeout stopped the script, 2
	// for a syntax error.
	ExitCode int
	// Truncated reports that the middle of Output was cut.
	Truncated bool
}

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