localtools

package
v0.0.2 Latest Latest
Warning

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

 Go to latest Published: Sep 9, 2026 License: Apache-2.0 Imports: 23 Imported by: 0

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInvalidRoot      = errors.New("localtools: invalid workspace root")
	ErrPathOutsideRoot  = errors.New("localtools: path outside workspace root")
	ErrOldTextNotFound  = errors.New("localtools: old text not found")
	ErrOldTextNotUnique = errors.New("localtools: old text occurs more than once")
	ErrInvalidPatch     = errors.New("localtools: invalid patch")
	ErrPatchUnsupported = errors.New("localtools: patch delegation is not supported")
	ErrCommandFailed    = errors.New("localtools: command failed")
	ErrExternalAPIKey   = errors.New("localtools: real external api key is not allowed")
	ErrInvalidFile      = errors.New("localtools: invalid file")
)

Functions

This section is empty.

Types

type CommandResult 

type CommandResult struct {
	ExitCode        int
	Output          string
	OutputBytes     int
	OutputTruncated bool
	PID             int
	// Archive is the retained output for the recovery archive: up to
	// ArchiveLimit bytes as head+tail windows separated by a gap marker. Empty
	// when nothing was truncated or ArchiveLimit was <=0. It is a superset of
	// Output, not a replacement — callers write it to durable storage and hand
	// the model a read-back reference.
	Archive string
}

type CommandSpec 

type CommandSpec struct {
	Name      string
	Args      []string
	CWD       string
	Env       []string
	Timeout   time.Duration
	MaxOutput int
	// ArchiveLimit bounds the bytes retained BEYOND MaxOutput for the recovery
	// archive, so output the model never sees can still be written somewhere it
	// can read back. <=0 retains nothing (Archive stays empty). When the command
	// produces more than this, the retained text keeps a head and a tail window
	// with an explicit middle-gap marker — a build's error is usually at the end,
	// so a head-only archive would drop the one part worth keeping.
	ArchiveLimit int
}

type DirEntry 

type DirEntry struct {
	Name  string
	IsDir bool
}

type EvictionSink 

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

EvictionSink adapts a Workspace to compaction.EvictionSink: it writes evicted tool-result/text content under a workspace subdir and returns the workspace-relative path the model reads back via read_file. It structurally satisfies compaction.EvictionSink (a Put method), so localtools needn't import compaction.

func NewEvictionSink 

func NewEvictionSink(ws *Workspace, dir string) *EvictionSink

NewEvictionSink returns a Workspace-backed eviction sink writing under dir (workspace-relative; "" -> defaultEvictionDir).

func (*EvictionSink) Put 

func (s *EvictionSink) Put(ctx context.Context, key string, content []byte) (string, error)

Put writes content under the sink dir keyed by a filename-safe form of key and returns the workspace-relative ref. Compaction hands the ref to the model as a read_file pointer, so it must stay inside the workspace.

type ExaClient 

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

func NewExaClient 

func NewExaClient(endpoint string, auth string, allowDirect bool, client *http.Client) (*ExaClient, error)

NewExaClient builds the Exa web_search client. By default the auth value must be a sidecar placeholder (the sidecar rewrites it with the real key); allowDirect permits a real EXA_API_KEY for sidecar-less testing, in which case requests hit Exa directly.

func (*ExaClient) Search 

func (c *ExaClient) Search(ctx context.Context, query string) (ExaSearchResult, error)

type ExaSearchResult 

type ExaSearchResult struct {
	Body string
}

type FileInfo 

type FileInfo struct {
	Path      string `json:"path"`
	URI       string `json:"uri"`
	Kind      string `json:"kind"`
	MediaType string `json:"media_type"`
	SizeBytes int64  `json:"size_bytes"`
	SHA256    string `json:"sha256"`
	Width     int    `json:"width,omitempty"`
	Height    int    `json:"height,omitempty"`
}

type NativePatchOperation added in v0.0.2 

type NativePatchOperation struct {
	Type string `json:"type"`
	Path string `json:"path"`
	Diff string `json:"diff,omitempty"`
}

type PatchChange added in v0.0.2 

type PatchChange struct {
	Path string
	Kind string
}

type PatchChunk added in v0.0.2 

type PatchChunk struct {
	Context string
	Old     []string
	New     []string
	EOF     bool
}

type PatchOperation added in v0.0.2 

type PatchOperation struct {
	Type     PatchOperationType
	Path     string
	MovePath string
	Content  string
	Chunks   []PatchChunk
}

func ParseNativePatchOperation added in v0.0.2 

func ParseNativePatchOperation(op NativePatchOperation) ([]PatchOperation, error)

ParseNativePatchOperation converts the Responses API apply_patch operation object into the same V4A operation representation used by custom tool calls.

func ParsePatch added in v0.0.2 

func ParsePatch(patch string) ([]PatchOperation, error)

ParsePatch parses the V4A patch format used by Codex custom apply_patch calls. It intentionally accepts only explicit file markers and line prefixes; path authorization happens later, before any filesystem mutation.

type PatchOperationType added in v0.0.2 

type PatchOperationType string
const (
	PatchCreate PatchOperationType = "create_file"
	PatchUpdate PatchOperationType = "update_file"
	PatchDelete PatchOperationType = "delete_file"
)

type Workspace 

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

func NewWorkspace 

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

func (*Workspace) AddReadRoots 

func (w *Workspace) AddReadRoots(dirs ...string) error

AddReadRoots registers additional read-only roots (absolute paths) that read-only file ops may read from. Each is resolved to an absolute, symlink-evaluated path; an entry that doesn't exist is skipped (so a deployment with no baked assets is a no-op rather than a startup error). Writes never use these roots.

func (*Workspace) ApplyPatch added in v0.0.2 

func (w *Workspace) ApplyPatch(ctx context.Context, operations []PatchOperation) ([]PatchChange, error)

ApplyPatch validates every operation and computes every resulting file in memory before committing. If a filesystem error occurs during commit, the touched files are restored to their original state.

func (*Workspace) EditFile 

func (w *Workspace) EditFile(ctx context.Context, relPath string, oldText string, newText string) error

func (*Workspace) GrantWorkingDirectory 

func (w *Workspace) GrantWorkingDirectory(dir string) error

GrantWorkingDirectory registers a user-selected directory for read-only file tools and as an allowed cwd for command execution. The structured write/edit APIs remain confined to Root().

func (*Workspace) GrantWorkspaceDirectory added in v0.0.2 

func (w *Workspace) GrantWorkspaceDirectory(dir string) error

GrantWorkspaceDirectory grants a user-selected project to both read and write tools. Callers must expose this only through an explicit workspace selection action such as project-mode /cd.

func (*Workspace) InspectFile 

func (w *Workspace) InspectFile(ctx context.Context, relPath string) (FileInfo, error)

func (*Workspace) ListDir 

func (w *Workspace) ListDir(ctx context.Context, relPath string) ([]DirEntry, error)

func (*Workspace) ReadBytes 

func (w *Workspace) ReadBytes(ctx context.Context, relPath string, maxBytes int64) ([]byte, error)

ReadBytes returns the raw bytes of relPath without coercing to a string, so it is safe for binary artifacts the agent presents (images, PDFs). Unlike ReadFile it errors rather than truncating when the file exceeds maxBytes (<=0 → no cap) — a truncated binary is corrupt.

func (*Workspace) ReadFile 

func (w *Workspace) ReadFile(ctx context.Context, relPath string, maxBytes int64) (string, error)

func (*Workspace) Root 

func (w *Workspace) Root() string

func (*Workspace) RunCommand 

func (w *Workspace) RunCommand(ctx context.Context, spec CommandSpec) (CommandResult, error)

func (*Workspace) RunPython 

func (w *Workspace) RunPython(ctx context.Context, pythonPath string, code string, spec CommandSpec) (CommandResult, error)

func (*Workspace) WriteFile 

func (w *Workspace) WriteFile(ctx context.Context, relPath string, content string) error

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.