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 ¶
- Variables
- func Base64Length(byteLength int64) int64
- func CreateBashTool(options *BashToolOptions) *durable.ToolRegistration
- func CreateCodingTools(options *ReadToolOptions) *durable.Extension
- func CreateEditTool() *durable.ToolRegistration
- func CreatePowerShellTool(options *PowerShellToolOptions) *durable.ToolRegistration
- func CreateReadTool(options *ReadToolOptions) *durable.ToolRegistration
- func CreateWriteTool() *durable.ToolRegistration
- func GenerateDiffString(oldContent, newContent string) (diff string, firstChangedLine int)
- func GenerateUnifiedPatch(path, oldStr, newStr string) string
- func ToBase64(bytes []byte) string
- type BashExecution
- type BashPrepare
- type BashToolInput
- type BashToolOptions
- type Edit
- type EditToolDetails
- type EditToolInput
- type ImageLimits
- type ImageProcessor
- type ImageResize
- type ImageSize
- type PowerShellToolInput
- type PowerShellToolOptions
- type PreparedImage
- type ReadToolDetails
- type ReadToolInput
- type ReadToolOptions
- type ReadTruncation
- type WriteToolInput
Constants ¶
This section is empty.
Variables ¶
var CodingTools = CreateCodingTools(nil)
CodingTools is CreateCodingTools without an image processor.
var DEFAULT_IMAGE_LIMITS = ImageLimits{MaxWidth: 2000, MaxHeight: 2000, MaxBytes: 4.5 * 1024 * 1024}
DEFAULT_IMAGE_LIMITS are the limits the coding agent keeps.
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 ¶
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 ¶
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 ¶
GenerateUnifiedPatch returns a unified diff for path byte-identical to upstream's generateUnifiedPatch with the default 4 lines of context.
Types ¶
type BashExecution ¶
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 ¶
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 ¶
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 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 ¶
WriteToolInput is the arguments of the write tool.