Documentation
¶
Overview ¶
Package capabilities implements policy-checked sandbox host bindings for filesystem, search, AST outlining, atomic transactions, git, shell checks, session state, and external MCP servers.
Index ¶
- Constants
- type ASTBinder
- type DirectReadRequest
- type DirectReadResult
- type EditHunk
- type EditTxBinder
- type FSSearchBinder
- type FileEditSpec
- type FileLockTable
- type FileOutline
- type MCPBridge
- type MCPBridgeOptions
- type SearchHit
- type ShellGitBinder
- func (b *ShellGitBinder) Bind(env *sandbox.ExecutionEnv) error
- func (b *ShellGitBinder) RunArgv(parentCtx context.Context, env *sandbox.ExecutionEnv, cwd, file string, ...) (map[string]any, error)
- func (b *ShellGitBinder) RunChecksBatch(ctx context.Context, baseCwd string, args []any) (map[string]any, error)
- func (b *ShellGitBinder) RunSingleCommand(parentCtx context.Context, cwd, cmdLine string, timeoutSec int, ...) (map[string]any, error)
- func (b *ShellGitBinder) RunSingleCommandDuration(parentCtx context.Context, cwd, cmdLine string, timeoutDur time.Duration, ...) (map[string]any, error)
- type StateBinder
- type StateStore
- func (s *StateStore) Clear()
- func (s *StateStore) ClearForSession(sessionID string)
- func (s *StateStore) ClearSessionSpills(sessionID string)
- func (s *StateStore) Delete(key string) bool
- func (s *StateStore) DeleteForSession(sessionID, key string) bool
- func (s *StateStore) Flush()
- func (s *StateStore) Get(key string) any
- func (s *StateStore) GetResolved(key string) (val any, resolvedKey string, found bool)
- func (s *StateStore) GetResolvedForSession(sessionID, key string) (val any, resolvedKey string, found bool)
- func (s *StateStore) Keys() []string
- func (s *StateStore) KeysForSession(sessionID string) []string
- func (s *StateStore) SaveAutoSpill(val any) string
- func (s *StateStore) SaveAutoSpillForSession(sessionID string, val any) string
- func (s *StateStore) Set(key string, val any) error
- type SymbolInfo
- type TasksBinder
- type ToolDescriptor
Constants ¶
const ( MaxSandboxReadBytes = 2 * 1024 * 1024 // 2 MB per file inside sandbox memory (never directly enters LLM context) MaxSearchLineBytes = 300 // UTF-8-safe per-line preview cap for search.rg (long lines warn) )
const ( DefaultDirectReadMaxLines = 800 DefaultDirectReadMaxBytes = 48 * 1024 // 48 KB per parallel read tool call MaxDirectReadBytes = 256 * 1024 // 256 KB upper cap MaxDirectReadImageBytes = 5 * 1024 * 1024 // 5 MB image cap )
const ( DefaultShellTimeout = 15 * time.Second MaxShellTimeout = 120 * time.Second )
const ( MaxStateEntryBytes = 512 * 1024 // 512 KB per persisted user key MaxStateTotalBytes = 4 * 1024 * 1024 // 4 MB per workspace session (persisted user entries) MaxSpillEntryBytes = 4 * 1024 * 1024 // 4 MB per in-memory auto-spill entry MaxSpillTotalBytes = 4 * 1024 * 1024 // 4 MB in-memory cap per session for auto-spills )
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type ASTBinder ¶
ASTBinder exposes `ast.outline`, `ast.outlines`, and `ast.enclosingSymbol` to guest programs.
type DirectReadRequest ¶ added in v0.3.0
type DirectReadRequest struct {
Path string `json:"path"`
Cwd string `json:"cwd,omitempty"`
StartLine int `json:"startLine,omitempty"`
EndLine int `json:"endLine,omitempty"`
Tail int `json:"tail,omitempty"`
ByteOffset int `json:"byteOffset,omitempty"`
LineNumbers *bool `json:"lineNumbers,omitempty"`
MaxBytes int `json:"maxBytes,omitempty"`
}
DirectReadRequest represents arguments for the standalone MCP `read` tool.
type DirectReadResult ¶ added in v0.3.0
DirectReadResult holds formatted text output and optional multimodal image payload for MCP content blocks.
func ReadFileDirect ¶ added in v0.3.0
func ReadFileDirect(pol *policy.Engine, cwd string, req DirectReadRequest) (*DirectReadResult, error)
ReadFileDirect serves the standalone `read` MCP tool with policy enforcement, line-range / tail / byteOffset pagination, and native image multimodal output.
type EditHunk ¶
type EditHunk struct {
Target string `json:"target"`
Replacement string `json:"replacement"`
StartLine int `json:"startLine,omitempty"`
EndLine int `json:"endLine,omitempty"`
ReplaceAll bool `json:"replaceAll,omitempty"`
Nth int `json:"nth,omitempty"` // 1-based: replace only the Nth match (like sed s/x/y/N)
Symbol string `json:"symbol,omitempty"` // restrict matching to a symbol's lines, e.g. "Editor::on_escape"
}
EditHunk represents a single non-overlapping replacement inside a file.
type EditTxBinder ¶
type EditTxBinder struct {
Policy *policy.Engine
ShellRunner *ShellGitBinder
Locks *FileLockTable
Events *events.Hub
SessionID string
RunID string
}
EditTxBinder exposes `edit.*` (`apply`, `replace`) and `tx.*` (`begin` -> atomic transactions with rollback).
func (*EditTxBinder) Bind ¶
func (b *EditTxBinder) Bind(env *sandbox.ExecutionEnv) error
type FSSearchBinder ¶
type FSSearchBinder struct {
Policy *policy.Engine
Locks *FileLockTable
Events *events.Hub
SessionID string
RunID string
// contains filtered or unexported fields
}
FSSearchBinder exposes `fs.*` and `search.*` to guest programs.
func (*FSSearchBinder) Bind ¶
func (b *FSSearchBinder) Bind(env *sandbox.ExecutionEnv) error
type FileEditSpec ¶
type FileEditSpec struct {
Path string `json:"path"`
Hunks []EditHunk `json:"hunks,omitempty"`
Create *string `json:"create,omitempty"`
Overwrite bool `json:"overwrite,omitempty"`
EOL string `json:"eol,omitempty"`
}
FileEditSpec describes edits or creation for one file.
type FileLockTable ¶ added in v0.3.0
type FileLockTable struct {
// contains filtered or unexported fields
}
FileLockTable serializes concurrent file writes/edits/transactions on overlapping files across parallel `exec` calls so an uncommitted transaction's rollback can never clobber another concurrent call's committed write. Same-owner acquisitions are ref-counted and re-entrant (so `tx` + `fs.write`/`edit.replace` inside one `exec` never self-deadlock), and cross-exec wait cycles are detected immediately across multi-edge wait graphs.
func NewFileLockTable ¶ added in v0.3.0
func NewFileLockTable() *FileLockTable
NewFileLockTable creates a process-shared file lock coordinator.
func (*FileLockTable) Acquire ¶ added in v0.3.0
func (l *FileLockTable) Acquire(ctx context.Context, ownerID string, paths ...string) (func(), error)
Acquire atomically claims all requested paths for ownerID (re-entrant with reference counting).
func (*FileLockTable) AcquireIn ¶ added in v0.3.0
func (l *FileLockTable) AcquireIn(ctx context.Context, cwd, ownerID string, paths ...string) (func(), error)
AcquireIn atomically claims all requested paths for ownerID and formats any conflict/timeout error relative to cwd with original filename casing preserved.
func (*FileLockTable) ReleaseOwner ¶ added in v0.3.0
func (l *FileLockTable) ReleaseOwner(ownerID string)
ReleaseOwner force-releases every file lock currently held by ownerID and wakes waiting writers.
type FileOutline ¶
type FileOutline struct {
File string `json:"file"`
TotalLines int `json:"totalLines"`
Symbols []SymbolInfo `json:"symbols"`
Error string `json:"error,omitempty"`
}
FileOutline groups extracted symbols for a file.
type MCPBridge ¶
type MCPBridge struct {
Policy *policy.Engine
WorkspaceDir string
SelfName string // e.g. "mcplex" or "agy-ptc", excluded to prevent recursion
ConfigPaths []string
CacheDirs []string
IncludeAntigravityPaths bool
// contains filtered or unexported fields
}
MCPBridge multiplexes discovery (cached schemas + live tools/list) and lazy execution of external MCP servers.
func NewMCPBridge ¶
NewMCPBridge constructs an external MCP multiplexer with Antigravity default paths.
func NewMCPBridgeWithOptions ¶
func NewMCPBridgeWithOptions(pol *policy.Engine, workspaceDir string, opts MCPBridgeOptions) *MCPBridge
NewMCPBridgeWithOptions constructs an external MCP multiplexer with explicit config/cache options.
func (*MCPBridge) CallExternalTool ¶
func (m *MCPBridge) CallExternalTool(ctx context.Context, cwd, rawRef string, callArgs map[string]any) (any, error)
CallExternalTool resolves an MCP server & tool name (supporting sanitized `_` -> `-` matching) and invokes it.
type MCPBridgeOptions ¶
type MCPBridgeOptions struct {
ConfigPaths []string // explicit mcpServers JSON config files (--mcp-config)
CacheDirs []string // optional pre-cached schema directories
IncludeAntigravityPaths bool // read ~/.gemini/config/mcp_config.json and ~/.gemini/antigravity*/mcp
SelfName string
}
MCPBridgeOptions configures downstream MCP config discovery and schema caching.
type SearchHit ¶
type SearchHit struct {
File string `json:"file"`
Line int `json:"line"`
Column int `json:"column,omitempty"`
Text string `json:"text"`
Before []string `json:"before,omitempty"`
After []string `json:"after,omitempty"`
Subtext string `json:"match,omitempty"`
}
SearchHit represents a single structured search match returned to guest TypeScript.
type ShellGitBinder ¶
type ShellGitBinder struct {
Policy *policy.Engine
Events *events.Hub
SessionID string
RunID string
}
ShellGitBinder exposes `sh.*` (`exec`, `checks`) and `git.*` (`status`, `diff`, `log`, `show`, `branch`, `blame`, `query`).
func (*ShellGitBinder) Bind ¶
func (b *ShellGitBinder) Bind(env *sandbox.ExecutionEnv) error
func (*ShellGitBinder) RunArgv ¶
func (b *ShellGitBinder) RunArgv(parentCtx context.Context, env *sandbox.ExecutionEnv, cwd, file string, argv []string, opts map[string]any) (map[string]any, error)
RunArgv executes file+argv directly (no shell): no quoting/dialect issues, stdout and stderr kept separate.
func (*ShellGitBinder) RunChecksBatch ¶
func (b *ShellGitBinder) RunChecksBatch(ctx context.Context, baseCwd string, args []any) (map[string]any, error)
RunChecksBatch runs multiple build/lint/test commands concurrently and returns a unified pass/fail envelope.
func (*ShellGitBinder) RunSingleCommand ¶
func (b *ShellGitBinder) RunSingleCommand(parentCtx context.Context, cwd, cmdLine string, timeoutSec int, settle, compact bool) (map[string]any, error)
RunSingleCommand executes one shell command with a timeout in seconds (compatibility wrapper).
func (*ShellGitBinder) RunSingleCommandDuration ¶
func (b *ShellGitBinder) RunSingleCommandDuration(parentCtx context.Context, cwd, cmdLine string, timeoutDur time.Duration, settle, compact bool) (map[string]any, error)
RunSingleCommandDuration executes one shell command after validating policy rules, killing the entire child process tree on timeout.
type StateBinder ¶
type StateBinder struct {
Store *StateStore
SessionID string
}
StateBinder binds the `state` namespace (`get`, `set`, `delete`, `keys`, `clear`, `page`) into the sandbox.
func (*StateBinder) Bind ¶
func (b *StateBinder) Bind(env *sandbox.ExecutionEnv) error
type StateStore ¶
type StateStore struct {
// contains filtered or unexported fields
}
StateStore provides fast in-memory + disk-persisted key-value storage across PTC turns. User-set entries persist per workspace; auto-spills (`__result_N` / `__last_result` alias) live in session-scoped in-memory buckets so concurrent HTTP sessions never cross-contaminate.
func NewStateStore ¶
func NewStateStore(dataDir, workspaceDir string) *StateStore
NewStateStore creates or loads a workspace-scoped state store under dataDir.
func (*StateStore) Clear ¶
func (s *StateStore) Clear()
Clear wipes all persisted entries and all in-memory auto-spills in the store.
func (*StateStore) ClearForSession ¶ added in v0.4.0
func (s *StateStore) ClearForSession(sessionID string)
ClearForSession clears persisted user KV entries and sessionID's auto-spills without dropping other sessions' active spills.
func (*StateStore) ClearSessionSpills ¶ added in v0.4.0
func (s *StateStore) ClearSessionSpills(sessionID string)
ClearSessionSpills removes all in-memory auto-spills belonging to sessionID without touching user KV or other sessions.
func (*StateStore) Delete ¶
func (s *StateStore) Delete(key string) bool
Delete removes a key from the store in the default session.
func (*StateStore) DeleteForSession ¶ added in v0.4.0
func (s *StateStore) DeleteForSession(sessionID, key string) bool
DeleteForSession removes a user key or a session-scoped spill key (`__result_N` / `__last_result`).
func (*StateStore) Flush ¶
func (s *StateStore) Flush()
Flush persists pending user KV changes to disk.
func (*StateStore) Get ¶
func (s *StateStore) Get(key string) any
Get retrieves a detached copy of key's value in the default session (or nil if absent).
func (*StateStore) GetResolved ¶
func (s *StateStore) GetResolved(key string) (val any, resolvedKey string, found bool)
GetResolved retrieves a detached copy of key's value in the default session along with its resolved key.
func (*StateStore) GetResolvedForSession ¶ added in v0.4.0
func (s *StateStore) GetResolvedForSession(sessionID, key string) (val any, resolvedKey string, found bool)
GetResolvedForSession retrieves a detached copy of key's value scoped to sessionID for spill keys (`__last_result`, `__result_N`) while sharing workspace user KV entries.
func (*StateStore) Keys ¶
func (s *StateStore) Keys() []string
Keys lists all keys currently readable in the default session.
func (*StateStore) KeysForSession ¶ added in v0.4.0
func (s *StateStore) KeysForSession(sessionID string) []string
KeysForSession lists all user keys plus sessionID's active spill keys (`__result_N` and `__last_result`).
func (*StateStore) SaveAutoSpill ¶
func (s *StateStore) SaveAutoSpill(val any) string
SaveAutoSpill atomically saves an oversized return value into the default session spill pool.
func (*StateStore) SaveAutoSpillForSession ¶ added in v0.4.0
func (s *StateStore) SaveAutoSpillForSession(sessionID string, val any) string
SaveAutoSpillForSession atomically saves an oversized return value into sessionID's in-memory spill pool under a unique `__result_N` key and updates that session's `__last_result` alias under the same lock.
type SymbolInfo ¶
type SymbolInfo struct {
Kind string `json:"kind"`
Name string `json:"name"`
Signature string `json:"signature,omitempty"`
StartLine int `json:"startLine"`
EndLine int `json:"endLine"`
}
SymbolInfo describes a top-level or nested code symbol with 1-based inclusive line numbers.
type TasksBinder ¶ added in v0.3.0
TasksBinder exposes `tasks.*` inside the TypeScript sandbox so scripts can orchestrate long-running background tasks and daemons alongside local file/search/git capabilities.
func (*TasksBinder) Bind ¶ added in v0.3.0
func (b *TasksBinder) Bind(env *sandbox.ExecutionEnv) error
type ToolDescriptor ¶
type ToolDescriptor struct {
Ref string `json:"ref"`
Provider string `json:"provider"`
Name string `json:"name"`
Description string `json:"description"`
InputSchema map[string]any `json:"inputSchema,omitempty"`
}
ToolDescriptor represents a discoverable builtin or MCP action inside `tools.*`.