capabilities

package
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 21, 2026 License: MIT Imports: 45 Imported by: 0

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

View Source
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)
)
View Source
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
)
View Source
const (
	DefaultShellTimeout = 15 * time.Second
	MaxShellTimeout     = 120 * time.Second
)
View Source
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 for process-local auto-spills

)

Variables

This section is empty.

Functions

This section is empty.

Types

type ASTBinder

type ASTBinder struct {
	Policy *policy.Engine
}

ASTBinder exposes `ast.outline`, `ast.outlines`, and `ast.enclosingSymbol` to guest programs.

func (*ASTBinder) Bind

func (b *ASTBinder) Bind(env *sandbox.ExecutionEnv) error

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

type DirectReadResult struct {
	Text      string
	ImageData string
	ImageMIME string
	IsImage   bool
}

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

func NewMCPBridge(pol *policy.Engine, workspaceDir string) *MCPBridge

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) Bind

func (m *MCPBridge) Bind(env *sandbox.ExecutionEnv) error

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.

func (*MCPBridge) Close

func (m *MCPBridge) Close()

Close shuts down any pooled child stdio MCP processes.

func (*MCPBridge) SetPolicy

func (m *MCPBridge) SetPolicy(pol *policy.Engine)

SetPolicy atomically updates the policy engine used by concurrent callers.

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
}

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 a dedicated process-local ring so concurrent 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 in-memory auto-spills in the store.

func (*StateStore) Delete

func (s *StateStore) Delete(key string) bool

Delete removes a key from the store.

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 (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 along with the concrete key it resolved to (for example, "__last_result" resolves to "__result_N" when backed by an auto-spill).

func (*StateStore) Keys

func (s *StateStore) Keys() []string

Keys lists all keys currently readable in the store.

func (*StateStore) SaveAutoSpill

func (s *StateStore) SaveAutoSpill(val any) string

SaveAutoSpill atomically saves an oversized return value into the in-memory spill pool under a unique `__result_N` key and updates the `__last_result` alias in the same lock.

func (*StateStore) Set

func (s *StateStore) Set(key string, val any) error

Set stores a JSON-serializable value under key.

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

type TasksBinder struct {
	Manager   *tasks.Manager
	Policy    *policy.Engine
	SessionID string
}

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.*`.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL