builtin

type ChangeKind string

type Config struct {
	// Dir is the working directory. File tools are confined to it. The
	// default is the current directory.
	Dir string
	// HTTPClient is used by web_fetch instead of the default client, which
	// refuses non-public addresses. The caller is then responsible for
	// restricting the addresses it can reach.
	HTTPClient *http.Client
	// AllowPrivateNetwork lets the default web_fetch client reach loopback,
	// private, link-local and shared (CGNAT, 100.64.0.0/10) addresses.
	AllowPrivateNetwork bool
	// MaxOutput caps the bytes of a tool result. The default is 30000.
	MaxOutput int
	// CommandTimeout is the default bash timeout. The default is two
	// minutes; the model may request up to ten.
	CommandTimeout time.Duration
	// Env is added to the environment of bash commands.
	Env []string
	// Todos is the list updated by todo_write. If nil, Tools creates one.
	Todos *TodoList
	// Files tracks the files read_file has read. When set, write_file,
	// edit_file and apply_patch only change or delete an existing file
	// after it was read and while it is unchanged since. If nil, Tools
	// creates one; tools constructed individually without it do not check.
	Files *FileTracker
	// NoApproval lets write_file, edit_file, apply_patch and bash run
	// without approval.
	NoApproval bool
	// CheckRedirect, if set, is called before web_fetch follows a
	// redirect, after the client's own checks, with the arguments of
	// http.Client.CheckRedirect; an error stops the fetch and is reported
	// to the model. permission.Policy.CheckRedirect applies WebFetch
	// permission rules to redirects this way.
	CheckRedirect func(req *http.Request, via []*http.Request) error
	// Edit selects the editing tools Tools returns besides write_file.
	Edit EditStyle
	// History, if set, saves the state of files before write_file,
	// edit_file and apply_patch change them, so the files of a session can
	// be restored to a checkpoint with agent.Runner.Rewind. If a save
	// fails, the tool changes nothing. Changes made by bash are not
	// tracked. A FileHistory forgets the files it restores in Files.
	History History
	// Sandbox, if set, runs every bash command, foreground and
	// background, inside it; see NewSandbox. Sandboxed commands need no
	// approval unless AskSandboxed is set; commands that run outside it
	// always do. See Bash.
	Sandbox Sandbox
	// SandboxFallback decides what bash does when Sandbox is set but not
	// available: SandboxRequired, the default, fails the command, and
	// SandboxBestEffort runs it unsandboxed after approval.
	SandboxFallback SandboxFallback
	// AskSandboxed keeps approval for sandboxed bash commands unless
	// NoApproval is set, like Claude Code's regular-permissions sandbox
	// mode.
	AskSandboxed bool
	// NoSandboxEscape removes bash's dangerously_disable_sandbox argument,
	// like Claude Code's allowUnsandboxedCommands set to false, so
	// commands always run in the sandbox.
	NoSandboxEscape bool
	// Shells holds the commands bash runs in the background, which
	// bash_output reads and kill_shell stops. If nil, Tools creates one;
	// bash constructed individually without it offers no background
	// commands. Close it, or call Close with the tools, when the agent is
	// done.
	Shells *Shells
	// ResetDir starts every bash command in Dir. By default a cd carries
	// over to later commands while it stays inside Dir.
	ResetDir bool
}

type EditStyle int

type FileChange struct {
	// Checkpoint is the ID of the checkpoint the change belongs to.
	Checkpoint string `json:"checkpoint"`
	// Run and Turn identify the run, and its turn, that made the change;
	// for a sub-agent, the outermost run with a session.
	Run  string `json:"run,omitempty"`
	Turn int    `json:"turn,omitempty"`
	// Tool is the name of the tool that made the change. Restore records
	// the files' state before it as changes of the tool "rewind".
	Tool string `json:"tool,omitempty"`
	// Dir is the absolute working directory of the tool, and Path the
	// slash-separated path of the file relative to it.
	Dir  string     `json:"dir"`
	Path string     `json:"path"`
	Kind ChangeKind `json:"kind"`
	// From and To are those of the FileEdit.
	From string `json:"from,omitempty"`
	To   string `json:"to,omitempty"`

	// Existed reports whether the file existed before the change. Mode,
	// Size and Hash, the hex SHA-256 of the content, describe the file
	// then; Link is the target of a symbolic link.
	Existed bool        `json:"existed"`
	Mode    fs.FileMode `json:"mode,omitempty"`
	Size    int64       `json:"size,omitempty"`
	Hash    string      `json:"hash,omitempty"`
	Link    string      `json:"link,omitempty"`
	// Skipped, if set, says why the content was not saved, or, in a
	// Restoration, why the file was not restored.
	Skipped string `json:"skipped,omitempty"`

	Time time.Time `json:"time"`
	// Seq orders the changes of a session.
	Seq int64 `json:"seq"`
}

type FileEdit struct {
	// Path is the path of the file, relative to the tool's working
	// directory.
	Path string
	Kind ChangeKind
	// From and To are set for a file apply_patch moves: From on the file
	// it creates or replaces, To on the file it deletes.
	From, To string
}

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

type FileHistoryConfig struct {
	// Dir holds the history. The default is .agentx/history in the
	// current directory. Keep it out of the reach of the file tools, or
	// at least out of their working directory's version control.
	Dir string
	// MaxCheckpoints is the number of the most recent checkpoints kept
	// for each session; the default is 100, as in Claude Code. Older
	// checkpoints and their changes are removed.
	MaxCheckpoints int
	// MaxBytes bounds the total size of the file contents kept for each
	// session; the default is 1 GiB. The oldest checkpoints are removed
	// beyond it, except the latest.
	MaxBytes int64
	// MaxFileSize is the largest file whose content is saved; the default
	// is 16 MiB. Larger files are recorded but not restored.
	MaxFileSize int64
	// MaxAge is how long the history of a session is kept after its last
	// change; the default is 30 days, as in Claude Code.
	MaxAge time.Duration
}

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

type History interface {
	// Save records the current state of files, named relative to dir,
	// which a call of the named tool is about to change. The session, run
	// and turn are those of the run executing the call, found with
	// loop.CallingRun; for the call of a nested run, such as a
	// sub-agent's, they are those of the outermost run with a session,
	// found with loop.Run.Caller. Outside a run with a session nothing
	// is saved. If no checkpoint of the session is named after the run,
	// Save starts one.
	Save(ctx context.Context, tool, dir string, edits []FileEdit) error
	// Checkpoint starts a checkpoint of a session, unless the latest one
	// has the same ID.
	Checkpoint(ctx context.Context, sessionID, id string) error
	// Checkpoints returns the checkpoints of a session that are kept,
	// oldest first, each with the changes saved after it and before the
	// next.
	Checkpoints(ctx context.Context, sessionID string) ([]HistoryCheckpoint, error)
	// Restore returns tracked files to their state at the checkpoint and
	// reports files it cannot restore in Restoration.Skipped. On failure it
	// attempts to undo changes already applied; rollback can also fail.
	// It returns ErrCheckpointNotFound for a checkpoint that is not kept.
	Restore(ctx context.Context, sessionID, id string) (*Restoration, error)
	// Fork copies the history of a session to a new session, so changes
	// saved for either later do not affect the other's.
	Fork(ctx context.Context, from, to string) error
	// Delete removes the history of a session.
	Delete(ctx context.Context, sessionID string) error
}

type HistoryCheckpoint struct {
	ID   string
	Time time.Time
	// Changes are the changes saved after the checkpoint and before the
	// next one, oldest first.
	Changes []FileChange
}

type Restoration struct {
	// Files are the restored files, each in the state it was restored to.
	Files []FileChange
	// Skipped are files that were changed since the checkpoint but not
	// restored, with the reason in FileChange.Skipped.
	Skipped []FileChange
	// Undo is the ID of a checkpoint holding the state of the restored
	// files before the restore; restoring it undoes the restore. It is
	// empty if no file changed.
	Undo string
}

type Sandbox interface {
	// Available returns nil if the sandbox can run commands on this
	// system, or an error saying why it cannot. bash asks before every
	// command, to decide whether the command needs approval and whether to
	// apply Config.SandboxFallback, so it should be cheap.
	Available() error
	// Wrap rewrites cmd, which has not been started, to run inside the
	// sandbox. dir is the working directory of the tools, Config.Dir,
	// which the sandbox should let the command write to; cmd.Dir is where
	// the command starts. Wrap may change cmd.Path, cmd.Args, cmd.Env and
	// cmd.SysProcAttr, but must keep cmd's descriptors, including
	// cmd.ExtraFiles, and run its program with its arguments. It returns
	// an error wrapping ErrSandboxUnavailable if the sandbox cannot run
	// commands.
	Wrap(cmd *exec.Cmd, dir string) error
}

type SandboxFallback int

type SandboxPolicy struct {
	// WritableRoots are directories commands may write to besides the
	// working directory and the temporary directories. A root whose path
	// passes through a symbolic link inside a writable root is refused,
	// since a command could retarget the link and widen the next
	// command's access.
	WritableRoots []string
	// ReadableRoots, if set, restricts reading to them, the writable
	// roots and the system directories programs need to run. If empty,
	// commands may read everything except DenyRead.
	ReadableRoots []string
	// DenyRead are files and directories commands may neither read nor
	// write, such as "~/.ssh" or "~/.aws/credentials". On Linux only
	// paths that exist when the command starts are hidden.
	DenyRead []string
	// ProtectedNames are entries at the top of each writable root that
	// stay read-only, so commands cannot change version control state or
	// agent configuration. On macOS they are protected even when missing,
	// so commands cannot create them either; on Linux only existing ones
	// are. A ".git" file pointing to a git directory protects that
	// directory too. Nil means DefaultProtectedNames; an empty non-nil
	// slice protects nothing.
	ProtectedNames []string
	// NoTempDirs keeps the temporary directories, $TMPDIR and /tmp,
	// read-only.
	NoTempDirs bool
	// AllowNetwork gives commands full network access.
	AllowNetwork bool
	// AllowedDomains are hosts commands may reach, unless AllowNetwork is
	// set, through an HTTP proxy that the sandbox starts on the loopback
	// interface and announces in HTTP_PROXY, HTTPS_PROXY and ALL_PROXY.
	// The proxy forwards plain HTTP requests and HTTPS CONNECT tunnels to
	// allowed hosts and refuses the rest. An entry is a host name, "*."
	// and a domain for its subdomains, "*" for every host, or an IP
	// address, IPv6 in brackets, each optionally followed by ":port". A
	// host name that resolves only to loopback or link-local addresses,
	// or to an address of this machine, is refused unless it is
	// "localhost" or ends in ".localhost". Programs that ignore the proxy
	// variables, and traffic other than TCP, cannot reach the network. On
	// Linux the proxy is bridged into the sandbox with socat, which must
	// be on PATH.
	AllowedDomains []string
	// AllowLocalBinding lets commands on macOS listen on ports and talk to
	// servers on the loopback interface. On Linux commands always have a
	// loopback interface of their own, isolated from the host's, unless
	// AllowNetwork is set.
	AllowLocalBinding bool
}

type Shells struct {
	// MaxRunning caps the background commands running at once; the
	// default is 8.
	MaxRunning int
	// MaxOutput caps the bytes of output kept per command; the oldest
	// output is dropped beyond it. The default is 1 MiB.
	MaxOutput int
	// contains filtered or unexported fields
}

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

type Todo struct {
	Content string `json:"content" jsonschema:"What needs to be done, in imperative form."`
	Status  string `json:"status" jsonschema:"enum=pending,enum=in_progress,enum=completed,description=Current status of the item."`
}

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