Documentation
¶
Index ¶
- Constants
- func DecodeInput(args map[string]any, dst any, required []string) error
- func DecodeInputStrict(args map[string]any, dst any, required []string) error
- func DecodeMap(src map[string]any, dst any) error
- func DetectImageMime(data []byte) string
- func ExecuteToolContent(ctx context.Context, t Tool, args map[string]any) ([]ai.ContentBlock, error)
- func IsBinary(data string) bool
- func MarshalResult(v any) (string, error)
- func MustInputSchema(data string) map[string]any
- func OffsetToken(offset int) string
- func OutputByteLimit() int
- func PageRows[T any](rows []T, limit, offset int) ([]T, string)
- func ParentImageCapabilityFromContext(ctx context.Context) ai.ImageCapability
- func ParsePage(pageSize int, pageToken string, defaultSize, maxSize int) (int, int, error)
- func ResolvePath(workDir, path string) (string, error)
- func ResolveProjectPath(projectRoot, path string) (string, error)
- func SplitLines(text string) []string
- func StringArg(args map[string]any, keys ...string) string
- func TruncateText(s string, max int) (string, bool)
- func WithParentImageCapability(ctx context.Context, capability ai.ImageCapability) context.Context
- type ContentTool
- type Definition
- type Registry
- func (r *Registry) BuiltinNames() []string
- func (r *Registry) Close() error
- func (r *Registry) Definitions() []Definition
- func (r *Registry) Execute(ctx context.Context, name string, args map[string]any) (string, error)
- func (r *Registry) ExecuteContent(ctx context.Context, name string, args map[string]any) ([]ai.ContentBlock, error)
- func (r *Registry) Has(name string) bool
- func (r *Registry) Register(t Tool) error
- type SpilledResult
- type Tool
- type TruncatedBy
- type TruncationResult
- type TurnOutputBudgetResult
Constants ¶
const InlineResultBytes = 16 * 1024
InlineResultBytes is the maximum complete external result returned inline. Larger content is projected into the active session's temporary filesystem so the Agent can page it with bash instead of spending its context window at once.
Variables ¶
This section is empty.
Functions ¶
func DecodeInput ¶ added in v0.60.0
func DecodeInputStrict ¶ added in v0.66.0
DecodeInputStrict decodes tool arguments and rejects any field the target struct does not declare. Split tools carry an exact schema (additionalProperties:false), so a field the schema forbids must not be silently dropped here — a typo like "titel" would otherwise cost the model a whole turn to notice. DecodeInput stays lenient for union tools, whose hoisted schema deliberately accepts every action's fields.
func DetectImageMime ¶ added in v0.60.3
DetectImageMime returns the canonical MIME type for image bytes the tool layer can present to a model (png, jpeg, gif, webp), or "" for anything else.
func ExecuteToolContent ¶ added in v0.41.0
func ExecuteToolContent(ctx context.Context, t Tool, args map[string]any) ([]ai.ContentBlock, error)
ExecuteToolContent runs a tool and returns its result as content blocks. Tools implementing ContentTool are called directly; others have their string output wrapped in a single TextContent block. Any partial text is preserved alongside an error so callers can surface it.
func IsBinary ¶
IsBinary reports whether data appears to be binary (non-text) content. It samples up to the first 8KB and checks for a high ratio of non-UTF-8 bytes or null bytes, which are reliable indicators of binary data.
func MarshalResult ¶ added in v0.60.0
func MustInputSchema ¶ added in v0.60.0
func OffsetToken ¶ added in v0.60.0
OffsetToken encodes a resume offset into the same opaque page token PageRows emits, so a caller that owns its own paging (e.g. a PEP that scans past denied rows) can hand back a token clients decode identically.
func OutputByteLimit ¶ added in v0.65.0
func OutputByteLimit() int
OutputByteLimit returns the current per-call byte budget for textual tool output, including an operator override when configured.
func ParentImageCapabilityFromContext ¶ added in v0.66.0
func ParentImageCapabilityFromContext(ctx context.Context) ai.ImageCapability
ParentImageCapabilityFromContext fails closed when no effective model fact was injected. Unknown therefore takes the textual route rather than risking a pixel result that the provider will silently downgrade.
func ResolvePath ¶
ResolvePath resolves path relative to workDir when it is not already absolute.
func ResolveProjectPath ¶
ResolveProjectPath resolves path relative to projectRoot when it is not already absolute. Relative paths require a non-empty project root.
func SplitLines ¶
SplitLines splits text into lines preserving newline suffixes. Trims the trailing empty element that strings.SplitAfter produces.
func WithParentImageCapability ¶ added in v0.66.0
WithParentImageCapability records the effective model's image capability for the current tool execution. The loop injects this after pre-LLM hooks run so routing and provider projection use the same model fact.
Types ¶
type ContentTool ¶ added in v0.41.0
type ContentTool interface {
ExecuteContent(ctx context.Context, args map[string]any) ([]ai.ContentBlock, error)
}
ContentTool is an optional interface for tools whose result may include non-text content (e.g. images). Tools that only emit text need not implement it; ExecuteToolContent wraps their string output automatically.
type Definition ¶
type Definition = ai.ToolDefinition
Definition is a callable tool definition exposed to a model.
type Registry ¶
type Registry struct {
// contains filtered or unexported fields
}
Registry holds named tools and provides lookup + definitions.
func NewRegistry ¶
func NewRegistry() *Registry
NewRegistry creates an empty tool registry. Tools are registered externally via Register().
func (*Registry) BuiltinNames ¶
BuiltinNames returns the names of all currently registered tools.
func (*Registry) Definitions ¶
func (r *Registry) Definitions() []Definition
Definitions returns all tool definitions in stable name order for passing to the LLM.
func (*Registry) ExecuteContent ¶ added in v0.41.0
func (r *Registry) ExecuteContent(ctx context.Context, name string, args map[string]any) ([]ai.ContentBlock, error)
ExecuteContent runs the named tool and returns its result as content blocks, preserving non-text content (e.g. images) from tools that emit it.
func (*Registry) Register ¶
Register adds a tool to the registry. A name already taken is refused rather than overwritten: silently replacing a tool changes which implementation (and which sandbox policy) a model call reaches, and the caller that assembled the registry is the only place that knows which source should win.
type SpilledResult ¶ added in v0.67.0
type SpilledResult struct {
Path string `json:"path"`
TotalBytes int `json:"total_bytes"`
Head string `json:"head"`
Tail string `json:"tail"`
}
SpilledResult is a bounded preview of a larger result and its sandbox-visible temporary path. The projected mode discourages ordinary writes, but commands running as the same sandbox user can still change the file. Head and Tail retain the beginning and end of Content; the middle remains in Path for on-demand reads.
func SpillResult ¶ added in v0.67.0
func SpillResult(files sandbox.FileAccess, category, filename, content string) (*SpilledResult, error)
SpillResult projects content when it exceeds InlineResultBytes. The filename is content-addressed and ProjectTempFiles publishes it no-replace, so retries do not clobber an existing projection. It is a convenience snapshot, not an immutable security boundary against commands in the same sandbox.
type Tool ¶
type Tool interface {
Definition() Definition
Execute(ctx context.Context, args map[string]any) (string, error)
}
Tool is a tool that can be executed by the Go runner.
type TruncatedBy ¶
type TruncatedBy string
const ( TruncatedByNone TruncatedBy = "" TruncatedByLines TruncatedBy = "lines" TruncatedByBytes TruncatedBy = "bytes" )
type TruncationResult ¶
type TruncationResult struct {
Content string
Truncated bool
TruncatedBy TruncatedBy
TotalLines int
TotalBytes int
OutputLines int
OutputBytes int
LastLinePartial bool
FirstLineExceedsLimit bool
MaxLines int
MaxBytes int
}
TruncationResult holds truncated output plus metadata about what happened. Content remains the user-facing string, including truncation headers/footers.
func TruncateHead ¶
func TruncateHead(output string) TruncationResult
TruncateHead keeps the first N lines / bytes (whichever limit is hit first). Suitable for file reads and search results where the beginning matters most. Never returns a partial line.
func TruncateTail ¶
func TruncateTail(output string) TruncationResult
TruncateTail keeps the last N lines / bytes (whichever limit is hit first). Suitable for command output and logs where the end matters most. When the last line alone exceeds the byte limit, it keeps a UTF-8-safe tail slice.
type TurnOutputBudgetResult ¶ added in v0.65.0
type TurnOutputBudgetResult struct {
Content string
Head string
Tail string
Marker string
Truncated bool
OmittedBytes int
}
TurnOutputBudgetResult is one textual tool result after the turn-wide budget has been applied. Content includes the actionable turn-budget marker when truncation was necessary.
func ApplyTurnOutputBudget ¶ added in v0.65.0
func ApplyTurnOutputBudget(outputs []string) []TurnOutputBudgetResult
ApplyTurnOutputBudget distributes the current turn budget across outputs by max-min fairness. Small outputs surrender unused capacity to larger outputs; ties and remainder bytes are resolved by call order for reproducibility. A too-small budget is clamped only enough to keep every required marker whole.
Source Files