tools

package
v0.5.1 Latest Latest
Warning

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

Go to latest
Published: Oct 19, 2026 License: MIT Imports: 24 Imported by: 0

Documentation

Overview

Package tools is the coding tools of pi-durable: read, write, edit and bash over an execution environment. Nothing installs them automatically.

Ports packages/durable/src/tools/index.ts.

Index

Constants

This section is empty.

Variables

View Source
var CodingTools = CreateCodingTools(nil)

CodingTools is CreateCodingTools without an image processor.

View Source
var DEFAULT_IMAGE_LIMITS = ImageLimits{MaxWidth: 2000, MaxHeight: 2000, MaxBytes: 4.5 * 1024 * 1024}

DEFAULT_IMAGE_LIMITS are the limits the coding agent keeps.

View Source
var INLINE_IMAGE_TYPES = map[string]bool{"image/png": true, "image/jpeg": true, "image/gif": true, "image/webp": true}

INLINE_IMAGE_TYPES are the formats every provider takes inline; others, such as BMP, need converting.

Functions

func Base64Length

func Base64Length(byteLength int64) int64

Base64Length is the length of the base64 of byteLength bytes.

func CreateBashTool

func CreateBashTool(options *BashToolOptions) *durable.ToolRegistration

CreateBashTool creates the bash tool. It runs a command through the environment's shell. Its output streams to api.Output, where the Harness keeps the tail within the default limits; the result content is that retained output. The retained window goes to the environment, which may omit output outside it and report how much it omitted, so dropped counts stay exact. Output beyond the limits is spilled to a file whose path is reported as a diagnostic. A nonzero exit or timeout returns an error, which makes an error result that still carries the output and diagnostics.

func CreateCodingTools

func CreateCodingTools(options *ReadToolOptions) *durable.Extension

CreateCodingTools is the coding-tools extension: read, write, edit, and bash; nothing installs it automatically. CreatePowerShellTool adds powershell. options.Images prepares the images read returns (see ReadToolOptions).

func CreateEditTool

func CreateEditTool() *durable.ToolRegistration

CreateEditTool creates the edit tool: exact-text replacement in one file.

func CreatePowerShellTool

func CreatePowerShellTool(options *PowerShellToolOptions) *durable.ToolRegistration

CreatePowerShellTool creates the powershell tool. It runs a PowerShell command like the bash tool, but through PowerShell instead of the environment's shell: pwsh (PowerShell 7), else Windows PowerShell, started directly with the command as an argument, so no other shell parses it.

Ports packages/durable/src/tools/bash.ts (createPowerShellTool).

func CreateReadTool

func CreateReadTool(options *ReadToolOptions) *durable.ToolRegistration

CreateReadTool creates the read tool. It reads text files and images. Remarks about truncation, continuation, and images are diagnostics; the content is only file text, or one image, which programs get as its ImageContent. Without an image processor, supported images within the model's limits pass through as they are.

func CreateWriteTool

func CreateWriteTool() *durable.ToolRegistration

CreateWriteTool creates the write tool: it writes a file, creating it and its parent directories.

func GenerateDiffString

func GenerateDiffString(oldContent, newContent string) (diff string, firstChangedLine int)

GenerateDiffString returns the line-numbered display diff and the first changed line number in the new file, byte-identical to upstream generateDiffString with the default 4 lines of context. A returned firstChangedLine of 0 means there was no change (upstream `undefined`).

func GenerateUnifiedPatch

func GenerateUnifiedPatch(path, oldStr, newStr string) string

GenerateUnifiedPatch returns a unified diff for path byte-identical to upstream's generateUnifiedPatch with the default 4 lines of context.

func ToBase64

func ToBase64(bytes []byte) string

ToBase64 is the standard base64 of bytes.

Types

type BashExecution

type BashExecution struct {
	Command    string
	Cwd        string
	Env        map[string]string
	InheritEnv bool
}

BashExecution is the command a bash call is about to run; BashPrepare may change any of it.

type BashPrepare

type BashPrepare func(ctx context.Context, execution *BashExecution, api durable.ToolExecutionApi) error

BashPrepare adjusts a bash execution before it runs, with the call's api. An error fails the call.

type BashToolInput

type BashToolInput struct {
	Command string `json:"command"`
	// Timeout is in seconds; nil has no timeout.
	Timeout *float64 `json:"timeout,omitempty"`
}

BashToolInput is the arguments of the bash tool.

type BashToolOptions

type BashToolOptions struct {
	// CommandPrefix is prepended, with a newline, to every command.
	CommandPrefix string
	Prepare       BashPrepare
}

BashToolOptions configure the bash tool.

type Edit

type Edit struct {
	OldText string `json:"oldText"`
	NewText string `json:"newText"`
}

Edit is one replacement of an edit call: OldText must match one region of the original file.

type EditToolDetails

type EditToolDetails struct {
	Diff             string `json:"diff"`
	Patch            string `json:"patch"`
	FirstChangedLine int    `json:"firstChangedLine,omitempty"`
}

EditToolDetails are the details of an edit result: the display diff, the unified patch, and the first changed line in the new file.

type EditToolInput

type EditToolInput struct {
	Path  string `json:"path"`
	Edits []Edit `json:"edits"`
}

EditToolInput is the arguments of the edit tool.

type ImageLimits

type ImageLimits struct {
	// MaxWidth is pixels. Default 2000.
	MaxWidth int
	// MaxHeight is pixels. Default 2000.
	MaxHeight int
	// MaxBytes is bytes of base64. Default 4.5 MiB, below Anthropic's 5 MB.
	MaxBytes int
}

ImageLimits are the limits an image the model sees must keep; the defaults below are the coding agent's.

type ImageProcessor

type ImageProcessor interface {
	// Prepare returns the image, prepared to fit limits, or nil when it cannot be decoded or made to fit. An error is a
	// failed or cancelled preparation, not an image that cannot be prepared.
	Prepare(ctx context.Context, bytes []byte, mimeType string, limits ImageLimits) (*PreparedImage, error)
}

ImageProcessor decodes, orients, resizes, and re-encodes images so the model can take them. read uses one when given; without one, it passes supported images within the byte limit through as they are. durable/images provides one.

type ImageResize

type ImageResize struct {
	From, To ImageSize
}

ImageResize is how a prepared image was resized: its size before and after, for the model to map coordinates back.

type ImageSize

type ImageSize struct {
	Width, Height int
}

ImageSize is a size in pixels.

type PowerShellToolInput

type PowerShellToolInput = BashToolInput

PowerShellToolInput is the arguments of the powershell tool.

type PowerShellToolOptions

type PowerShellToolOptions struct {
	// CommandPrefix is prepended, with a newline, to every command.
	CommandPrefix string
	Prepare       BashPrepare
	// Programs are the PowerShell programs to try in order; the default is pwsh, then powershell. A program that cannot
	// start is skipped.
	Programs []string
}

PowerShellToolOptions configure the powershell tool.

type PreparedImage

type PreparedImage struct {
	Data     string
	MimeType string
	// Resized is set when the image was resized.
	Resized *ImageResize
	// ConvertedFrom is the original format, set when it differs from MimeType: BMP becomes PNG, a large PNG may become JPEG.
	ConvertedFrom string
}

PreparedImage is an image the model can take: a supported format, within the limits, as base64.

type ReadToolDetails

type ReadToolDetails struct {
	Truncation *ReadTruncation `json:"truncation,omitempty"`
}

ReadToolDetails are the details of a read result that was truncated.

type ReadToolInput

type ReadToolInput struct {
	Path   string   `json:"path"`
	Offset *float64 `json:"offset,omitempty"`
	Limit  *float64 `json:"limit,omitempty"`
}

ReadToolInput is the arguments of the read tool. Offset and Limit are JSON numbers, which need not be whole.

type ReadToolOptions

type ReadToolOptions struct {
	// Images resizes and converts images; without one, images within DEFAULT_IMAGE_LIMITS.MaxBytes pass through as they are.
	Images ImageProcessor
}

ReadToolOptions configures the read tool.

type ReadTruncation

type ReadTruncation struct {
	Truncated             bool                `json:"truncated"`
	TruncatedBy           durable.TruncatedBy `json:"truncatedBy"`
	TotalLines            int                 `json:"totalLines"`
	TotalBytes            int                 `json:"totalBytes"`
	OutputLines           int                 `json:"outputLines"`
	OutputBytes           int                 `json:"outputBytes"`
	LastLinePartial       bool                `json:"lastLinePartial"`
	FirstLineExceedsLimit bool                `json:"firstLineExceedsLimit"`
	MaxLines              int                 `json:"maxLines"`
	MaxBytes              int                 `json:"maxBytes"`
}

ReadTruncation is how the shown text was cut; the text itself is the result content. It is a TruncationResult without its Content.

type WriteToolInput

type WriteToolInput struct {
	Path    string `json:"path"`
	Content string `json:"content"`
}

WriteToolInput is the arguments of the write tool.

Jump to

Keyboard shortcuts

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