sandbox

type BrowserTool ¶

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

BrowserTool drives a browser via the agent-browser CLI on the substrate it was built with. With an injected Sandbox it reuses a persistent, browser-scoped session container so the agent-browser daemon (and the page it controls) survive across calls — the property that makes multi-step browsing possible. The daemon self-reaps on idle (AGENT_BROWSER_IDLE_TIMEOUT_MS, set in the image) so no zombie browser pins resources between conversations. With no sandbox the same CLI is invoked on the host machine, where the daemon is already a long-lived host process and persists without a container.

func NewBrowserTool(sb agentcore.Sandbox, workspace *Workspace, limits agentcore.SandboxLimits, image string) *BrowserTool

func (t *BrowserTool) Name() string

func (t *BrowserTool) Run(ctx context.Context, args string) (string, error)

func (t *BrowserTool) Schema() agentcore.ToolSchema

type DockerSandbox ¶

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

DockerSandbox runs each command in an ephemeral, hardened container via the host `docker` CLI. It holds no daemon connection and keeps no state between calls: every Exec is `docker run --rm` with a fresh container, so a compromised execution cannot persist or reach a sibling.

func NewDockerSandbox(opts ...Option) *DockerSandbox

func (s *DockerSandbox) Available(ctx context.Context) bool

func (s *DockerSandbox) CloseSession(id string) error

func (s *DockerSandbox) Exec(ctx context.Context, req agentcore.SandboxExec) (agentcore.SandboxResult, error)

func (s *DockerSandbox) Image() string

func (s *DockerSandbox) Start(ctx context.Context, req agentcore.SandboxExec) (agentcore.SandboxProcess, error)

func (s *DockerSandbox) StopEgress()

type EditFileTool ¶

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

EditFileTool performs surgical in-place edits: it replaces an exact substring in a workspace file rather than rewriting the whole thing (Claude Code's Edit / pi's edit). This keeps large files cheap to change and makes intent reviewable — the model states the precise text it is swapping. It shares Workspace and the same substrate seam as read_file/write_file, so the read-modify-write happens wherever those happen — on the host under the symlink/escape guards by default, inside the sandbox when one is provided.

func NewEditFileTool(sb agentcore.Sandbox, workspace *Workspace) *EditFileTool

func (t *EditFileTool) Name() string

func (t *EditFileTool) Run(ctx context.Context, args string) (string, error)

func (t *EditFileTool) Schema() agentcore.ToolSchema

type EditLinesTool ¶

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

EditLinesTool applies several line-addressed changes to one immutable file snapshot. Every coordinate refers to the original snapshot, so an agent can change distant regions in one call without recalculating line numbers after each hunk. The whole-file hash remains the authority: line numbers make calls compact, while the hash prevents them from landing on a different revision.

func NewEditLinesTool(sb agentcore.Sandbox, workspace *Workspace) *EditLinesTool

func (t *EditLinesTool) Name() string

func (t *EditLinesTool) Run(ctx context.Context, args string) (string, error)

func (t *EditLinesTool) Schema() agentcore.ToolSchema

type EvalConfig ¶

type EvalConfig struct {
	Python         EvalPythonConfig     `json:"python,omitempty"`
	JavaScript     EvalJavaScriptConfig `json:"javascript,omitempty"`
	TimeoutSeconds int                  `json:"timeout_seconds,omitempty"`
	MaxOutputBytes int                  `json:"max_output_bytes,omitempty"`
	MaxBridgeCalls int                  `json:"max_bridge_calls,omitempty"`
}

EvalConfig selects the operator-provisioned Python and JavaScript runtimes used by the persistent eval tool. The zero-value JSON object is useful on a laptop (python3 and node on PATH); a server normally supplies language images or the combined AgentRay eval image.

func ParseEvalConfig(raw string) (EvalConfig, error)

type EvalJavaScriptConfig ¶

type EvalJavaScriptConfig struct {
	Command string   `json:"command,omitempty"`
	Args    []string `json:"args,omitempty"`
	Image   string   `json:"image,omitempty"`
}

type EvalPythonConfig ¶

type EvalPythonConfig struct {
	Command string   `json:"command,omitempty"`
	Args    []string `json:"args,omitempty"`
	Image   string   `json:"image,omitempty"`
}

type EvalSessionRegistry ¶

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

EvalSessionRegistry retains language runtimes across the short-lived tool instances built for consecutive turns of one conversation. Capacity is a soft limit: active sessions are never killed to make room for another call.

func NewEvalSessionRegistry(capacity int, idle time.Duration) *EvalSessionRegistry

func (r *EvalSessionRegistry) Close()

type EvalTool ¶

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

EvalTool executes one Python or JavaScript cell in a retained, conversation-and-language-scoped subprocess. The registry—not this per-run tool instance—owns the process, so state survives runtime rebuilding while Python and JavaScript can never share globals accidentally.

func NewEvalTool(sb agentcore.Sandbox, workspace *Workspace, registry *EvalSessionRegistry, namespace string, config EvalConfig) (*EvalTool, error)

func (t *EvalTool) Name() string

func (t *EvalTool) Run(ctx context.Context, args string) (string, error)

func (t *EvalTool) RunRich(ctx context.Context, args string) (agentcore.ToolOutput, error)

func (t *EvalTool) Schema() agentcore.ToolSchema

type GlobTool ¶

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

GlobTool lists workspace files whose relative path matches a glob pattern (Claude Code's Glob), supporting * ? and ** segments. Results are sorted for stable output and capped for token safety.

func NewGlobTool(sb agentcore.Sandbox, workspace *Workspace) *GlobTool

func (t *GlobTool) Name() string

func (t *GlobTool) Parallel() bool

func (t *GlobTool) Run(ctx context.Context, args string) (string, error)

func (t *GlobTool) Schema() agentcore.ToolSchema

type GrepTool ¶

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

GrepTool searches file contents in the workspace by regular expression (Claude Code's Grep / pi's grep). The matching is always pure Go regexp in this process — only the file I/O moves: a guarded host walk by default, or a batched listing + read inside the sandbox when one is provided. Keeping RE2 above the substrate seam is what makes both paths return the same lines in the same order. Returns file:line:match lines, capped for token safety.

func NewGrepTool(sb agentcore.Sandbox, workspace *Workspace) *GrepTool

func (t *GrepTool) Name() string

func (t *GrepTool) Parallel() bool

func (t *GrepTool) Run(ctx context.Context, args string) (string, error)

func (t *GrepTool) Schema() agentcore.ToolSchema

type HTTPOption ¶

type HTTPOption func(*HTTPTool)

HTTPOption configures an HTTPTool. It is distinct from Option, which configures the DockerSandbox backend.

func WithHTTPAllowHosts(hosts []string) HTTPOption

func WithHTTPAllowPlain(allow bool) HTTPOption

func WithHTTPTimeout(d time.Duration) HTTPOption

func WithHTTPWorkspace(ws *Workspace) HTTPOption

type HTTPTool ¶

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

HTTPTool makes guarded outbound HTTP requests. It is the worked consumer of the credential vault (governance F7): the place a {{cred:NAME}} secret actually gets used.

The tool is deliberately dumb about credentials: the agentcore loop resolves {{cred:NAME}} placeholders in the argument JSON at the trust boundary before Run is ever called, so an Authorization header the model wrote as "Bearer {{cred:API_KEY}}" arrives here already resolved to the real value — the model never saw the literal, and this tool never needs the vault.

Where the request is made from depends on the substrate. With no sandbox (the default) it goes out from the host process over net/http. With a sandbox it goes out from inside the container, so a compromised request cannot reach anything the container's network envelope does not permit. The resolved secret then has to cross that boundary, and it does so on the container's stdin as a curl config — never in argv (readable via `ps` by every process in the container) and never in an environment variable. See httpsandbox.go.

What it is careful about either way is SSRF. An agent that can make arbitrary outbound requests can reach cloud metadata (169.254.169.254), internal services, and localhost. Defenses, default-deny:

• scheme must be https (http is opt-in)
• the URL host must be in the configured allowlist
• a guarded dialer re-checks the resolved IP at connect time and refuses loopback / private / link-local / unspecified addresses, which also closes the DNS-rebinding TOCTOU gap (allowlisted name re-pointed at a blocked IP). On the sandbox path the same check runs in the egress proxy the container's traffic is confined to, so the backstop survives the move.
• redirects are not followed (a 3xx is surfaced to the model as-is)

Safe for concurrent use: the allowlist is read-only after construction and http.Client is concurrency-safe.

func NewHTTPRequestTool(sb agentcore.Sandbox, opts ...HTTPOption) *HTTPTool

func (t *HTTPTool) AllowHosts() []string

func (t *HTTPTool) Name() string

func (t *HTTPTool) Run(ctx context.Context, args string) (string, error)

func (t *HTTPTool) Schema() agentcore.ToolSchema

type HostSandbox ¶

type HostSandbox struct{}

HostSandbox runs commands directly on the host machine. It is the substrate every tool in this package falls back to when no agentcore.Sandbox is injected, which makes the sandbox parameter optional in both directions: nil means "run here", non-nil means "run in there", and the tools above keep a single code path either way.

It is NOT isolation. It is the closest honest host analogue of the agentcore.Sandbox contract, and it keeps exactly the parts of that contract a plain process can keep:

• Env is the only environment the child sees. os.Environ() is never inherited, so a prompt-injected `env` or `cat /proc/self/environ` cannot read the server's DB creds or API keys — the one guarantee worth the most and the one a bare exec.CommandContext would have thrown away.
• Workdir is resolved through Mounts, so a command runs in the agent workspace rather than the server's working directory.
• TimeoutSeconds is enforced with a hard kill of the whole process group, so a command that backgrounded work does not outlive its own timeout.

What it cannot keep, and what a caller must weigh before choosing it:

• The filesystem is the host's. WritableFS is not enforceable; a command can read anything the server process can read and write anywhere it can write.
• The network is the host's. Network and NetworkAllow are not enforceable — there is no container to route through the egress proxy.
• MemoryMB / CPUs / PidsLimit are not enforceable; only the timeout is.
• Image is meaningless and ignored.
• Session is ignored: the host filesystem already persists across calls, so a persistent tool needs no session container to keep its state.

So: HostSandbox is the right substrate for an embedded or local consumer of this package (a CLI on a developer's machine, a single-tenant deployment where the agent is already trusted with the box). It is the wrong substrate for a hosted, multi-tenant deployment running model-authored commands, which is why internal/runtime keeps the shell/computer/browser tools gated on a real sandbox being wired.

func NewHostSandbox() *HostSandbox

func (h *HostSandbox) Exec(ctx context.Context, req agentcore.SandboxExec) (agentcore.SandboxResult, error)

func (h *HostSandbox) Start(ctx context.Context, req agentcore.SandboxExec) (agentcore.SandboxProcess, error)

type InjectionGuard ¶

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

InjectionGuard is a runtime prompt-injection / exfiltration filter installed as a BeforeToolCall hook. Where AGT's PromptDefense statically grades a system prompt *before* deployment, this scans the actual tool *arguments* the model emits *at* runtime — the live vector for indirect injection, where attacker text smuggled through retrieved data steers the agent into exfiltrating secrets or overriding its instructions.

It is deterministic regex (zero LLM cost), default-deny on match, and feeds the block reason back to the model so the run continues safely rather than failing silently. It is a cheap second layer behind the Sandbox, not a replacement: the sandbox stops a malicious command from reaching anything; the guard stops many such commands from ever being issued.

func NewInjectionGuard() *InjectionGuard

func (g *InjectionGuard) Hook() agentcore.BeforeToolCall

func (g *InjectionGuard) Match(s string) bool

type LSPConfig ¶

type LSPConfig struct {
	Servers        []LSPServerConfig `json:"servers"`
	TimeoutSeconds int               `json:"timeout_seconds,omitempty"`
}

LSPConfig is operator-authored configuration for the read-only language intelligence tool. Binaries are deliberately provisioned out of band: the agent may use a configured server, but never install or download one.

func ParseLSPConfig(raw string) (LSPConfig, error)

type LSPServerConfig ¶

type LSPServerConfig struct {
	Name                  string         `json:"name"`
	Command               string         `json:"command"`
	Args                  []string       `json:"args,omitempty"`
	Extensions            []string       `json:"extensions"`
	LanguageID            string         `json:"language_id,omitempty"`
	DiagnosticsOnly       bool           `json:"diagnostics_only,omitempty"`
	Image                 string         `json:"image,omitempty"`
	InitializationOptions map[string]any `json:"initialization_options,omitempty"`
	Settings              map[string]any `json:"settings,omitempty"`
}

type LSPSessionRegistry ¶

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

LSPSessionRegistry retains initialized language servers across the short-lived tool instances built for consecutive turns. It is deliberately process-local: another server replica starts a clean client, so correctness never depends on sticky routing or a shared daemon.

Capacity is a soft limit. An in-flight client is never killed to make room.

func NewLSPSessionRegistry(capacity int, idle time.Duration) *LSPSessionRegistry

func (r *LSPSessionRegistry) Close()

type LSPTool ¶

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

LSPTool provides bounded read-only language intelligence. A process-local registry retains initialized servers by conversation and complete server identity; every action still synchronizes fresh workspace bytes.

func NewLSPTool(sb agentcore.Sandbox, workspace *Workspace, config LSPConfig) (*LSPTool, error)

func NewLSPToolWithRegistry(sb agentcore.Sandbox, workspace *Workspace, registry *LSPSessionRegistry, namespace string, config LSPConfig) (*LSPTool, error)

func (t *LSPTool) Name() string

func (t *LSPTool) Run(ctx context.Context, args string) (string, error)

func (t *LSPTool) Schema() agentcore.ToolSchema

type Option ¶

type Option func(*DockerSandbox)

Option configures a DockerSandbox.

func WithComputerUseImage(image string) Option

func WithDockerBinary(bin string) Option

func WithImage(image string) Option

type ReadFileTool ¶

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

ReadFileTool reads a workspace file. sb decides where the read happens, not what it produces: the windowing, line numbering and truncation notice below run identically over either substrate.

func NewReadFileTool(sb agentcore.Sandbox, workspace *Workspace) *ReadFileTool

func (t *ReadFileTool) Name() string

func (t *ReadFileTool) Parallel() bool

func (t *ReadFileTool) Run(ctx context.Context, args string) (string, error)

func (t *ReadFileTool) Schema() agentcore.ToolSchema

type SearchProvider ¶

type SearchProvider interface {
	// Search runs one query and returns ranked results, best first, at most
	// maxResults of them.
	Search(ctx context.Context, query string, maxResults int) ([]SearchResult, error)
}

SearchProvider is the pluggable backend behind web_search. The provider is configuration, not code: the registry picks an implementation from the agent's tool config and hands it here, so adding a provider never touches the tool. Implementations must make their own egress safe — the built-in ones dial through NewGuardedClient, which re-checks every resolved IP.

func NewDuckDuckGoSearch(client *http.Client) SearchProvider

type SearchResult ¶

type SearchResult struct {
	Title   string
	URL     string
	Snippet string
}

SearchResult is one ranked hit: title, URL, and a short snippet.

type ShellTool ¶

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

ShellTool lets the agent run a shell command on whichever substrate it was built with. With an injected Sandbox the command runs inside it and sees nothing of the host: no filesystem, no environment, no network unless granted. With no sandbox it falls back to HostSandbox and runs on the host — still with only the declared env visible (a prompt-injected `cat /proc/self/environ` cannot read the server's DB creds or API keys) and still under the timeout, but with the host's filesystem and network. Which substrate is appropriate is the caller's decision; see HostSandbox for what is and is not enforceable there.

func NewComputerUseTool(sb agentcore.Sandbox, ws *Workspace, networkAllow ...string) *ShellTool

func NewShellTool(sb agentcore.Sandbox, limits agentcore.SandboxLimits, ws *Workspace) *ShellTool

func (t *ShellTool) Name() string

func (t *ShellTool) Run(ctx context.Context, args string) (string, error)

func (t *ShellTool) Schema() agentcore.ToolSchema

type WebFetchOption ¶

type WebFetchOption func(*WebFetchTool)

func WithWebFetchTimeout(timeout time.Duration) WebFetchOption

type WebFetchTool ¶

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

WebFetchTool fetches an arbitrary public URL and returns its readable text (Claude Code's WebFetch). It is the open-egress counterpart to http_request: where http_request is host-allowlisted for talking to specific APIs, web_fetch is meant for reading the open web, so it has no host allowlist. SSRF is still closed off at the IP layer — the same guarded dialer as http_request re-checks every resolved address (including each redirect hop) and refuses loopback / private / link-local / metadata, so "no allowlist" does not mean "can reach internal services". HTML is reduced to text to keep results small.

With a sandbox injected the fetch is made from inside the container instead. Because the tool has no host allowlist of its own, the container's egress is pinned per call to the requested URL's host (and its subdomains) — an empty egress allowlist would hand the container an open network with no IP guard, which is exactly the SSRF surface this tool exists to close. The visible consequence is that a redirect off that host is refused by the egress proxy rather than followed.

func NewWebFetchTool(sb agentcore.Sandbox, ws *Workspace, options ...WebFetchOption) *WebFetchTool

func (t *WebFetchTool) Name() string

func (t *WebFetchTool) Parallel() bool

func (t *WebFetchTool) Run(ctx context.Context, args string) (string, error)

func (t *WebFetchTool) Schema() agentcore.ToolSchema

type WebSearchTool ¶

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

WebSearchTool answers a query with ranked web results (title/url/snippet). It is the discovery counterpart to web_fetch: search finds the pages, web_fetch reads one. There is no host allowlist — the result set is whatever the provider returns — but the provider's own egress rides the same guarded dialer as every other host-side outbound tool, so loopback / private / link-local / metadata addresses are refused at connect time.

Host substrate only, for the same reason as http_request: the default sandbox image has no HTTP client to run the request through.

func NewWebSearchTool(p SearchProvider, maxResults int) *WebSearchTool

func (t *WebSearchTool) Name() string

func (t *WebSearchTool) Parallel() bool

func (t *WebSearchTool) Run(ctx context.Context, args string) (string, error)

func (t *WebSearchTool) Schema() agentcore.ToolSchema

type Workspace ¶

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

Workspace guards file tools to one host directory. It accepts only relative paths, cleans them, follows the root symlink once, and rejects traversal before any filesystem operation happens.

func NewWorkspace(root string) (*Workspace, error)

func WorkspaceFor(base string, scope WorkspaceScope) (*Workspace, error)

func (w *Workspace) Resolve(rel string) (string, string, error)

func (w *Workspace) Root() string

type WorkspaceScope ¶

type WorkspaceScope struct {
	WorkspaceID    string
	ProjectID      string
	AgentID        string
	ConversationID string

	// Pinned is a folder the user chose, and it replaces the derived path
	// entirely rather than nesting under it.
	//
	// The derived layout is the right default because it keeps conversations from
	// colliding and needs no decision from anyone. But an agent is often pointed
	// at work that already exists — a repository, a directory of documents — and
	// the answer to "which folder?" is then a folder the user already has, not
	// one AgentRay invented. Pinning is that answer: the same directory across
	// every conversation with this agent, which is also what makes the agent's
	// output somewhere the user can find it.
	//
	// It must be an absolute path (a leading ~ is expanded). Unlike the derived
	// segments it is NOT sanitized into a single component — the whole point is
	// that it names a real place — so it is only ever set from an authenticated
	// operator's configuration, never from anything the model can write.
	Pinned string

	// PinDisabled refuses Pinned and falls back to the derived layout.
	//
	// "The user's call" is only the right default when the user setting the path
	// is the person who owns the host. On a hosted, multi-tenant deployment they
	// are not: workspace owner/admin is reachable by self-serve signup, so an
	// unconfined pin would hand a tenant the host filesystem — read via the file
	// tools, and read-write via the bind mount the sandboxed tools take on
	// Workspace.Root(). It is re-checked here rather than only where the value is
	// saved, because a row written before this existed is still in the database.
	PinDisabled bool
}

WorkspaceScope identifies the one conversation a workspace belongs to. Every field is optional; a missing one becomes unnamedSegment, so a partially identified run still gets a usable, stable directory rather than an error.

type WriteFileTool ¶

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

func NewWriteFileTool(sb agentcore.Sandbox, workspace *Workspace) *WriteFileTool

func (t *WriteFileTool) Name() string

func (t *WriteFileTool) Run(ctx context.Context, args string) (string, error)

func (t *WriteFileTool) Schema() agentcore.ToolSchema