codingtools

README

contrib/codingtools

contrib/codingtools provides reusable read, edit, and write tool contracts on top of github.com/ewhauser/gbash/fs.FileSystem.

It is a public helper module, not a shell-command bundle:

• not part of gbash.DefaultRegistry()
• not registered by contrib/extras
• intended for embedders that want provider-neutral file tools over a gbash-owned filesystem abstraction

What It Includes

• provider-neutral tool metadata via ToolDefinition
• request parsers for provider payloads
• structured text and image responses
• upstream-style truncation and exact-text edit semantics
• path resolution that stays agnostic to in-memory vs host-backed filesystems
• per-toolset mutation serialization for edit and write

Quick Start

package main

import (
	"context"
	"encoding/json"
	"fmt"

	gbfs "github.com/ewhauser/gbash/fs"
	"github.com/ewhauser/gbash/contrib/codingtools"
)

func main() {
	fsys := gbfs.NewMemory()
	tools := codingtools.New(codingtools.Config{
		FS:         fsys,
		WorkingDir: "/workspace",
	})

	_, _ = tools.Write(context.Background(), codingtools.WriteRequest{
		Path:    "note.txt",
		Content: "hello from codingtools\n",
	})

	resp, _ := tools.Read(context.Background(), codingtools.ReadRequest{
		Path: "note.txt",
	})

	payload, _ := json.MarshalIndent(resp, "", "  ")
	fmt.Println(string(payload))
}

Attribution

This package is a gbash-owned Go port of the read, edit, and write tools from badlogic/pi-mono, adapted to run against gbash's public filesystem interface instead of Node's host filesystem APIs.

Documentation

Overview

Package codingtools exposes reusable read, edit, and write tool contracts for LLM integrations on top of gbash-owned filesystem abstractions.

It ports the upstream pi-mono coding-agent tool semantics onto github.com/ewhauser/gbash/fs.FileSystem so embedders can run the same tool surface against in-memory, overlay, session, and host-backed filesystems without changing the tool contract.

Index

• Constants
• func FormatSize(bytes int) string
• type Config
• type ContentBlock
• type EditDetails
• type EditRequest
  • func ParseEditRequest(input map[string]any) (EditRequest, error)
• type EditResponse
• type ReadDetails
• type ReadRequest
  • func ParseReadRequest(input map[string]any) (ReadRequest, error)
• type ReadResponse
• type ToolDefinition
• type Toolset
  • func New(cfg Config) *Toolset
  • func (t *Toolset) Edit(ctx context.Context, req EditRequest) (EditResponse, error)
  • func (t *Toolset) EditToolDefinition() ToolDefinition
  • func (t *Toolset) Read(ctx context.Context, req ReadRequest) (ReadResponse, error)
  • func (t *Toolset) ReadToolDefinition() ToolDefinition
  • func (t *Toolset) ToolDefinitions() []ToolDefinition
  • func (t *Toolset) Write(ctx context.Context, req WriteRequest) (WriteResponse, error)
  • func (t *Toolset) WriteToolDefinition() ToolDefinition
• type TruncationOptions
• type TruncationResult
  • func TruncateHead(content string, options TruncationOptions) TruncationResult
• type WriteRequest
  • func ParseWriteRequest(input map[string]any) (WriteRequest, error)
• type WriteResponse

Constants

const (
	// DefaultMaxLines is the default line limit for read output.
	DefaultMaxLines = 2000
	// DefaultMaxBytes is the default byte limit for read output.
	DefaultMaxBytes = 50 * 1024
)

Functions

func FormatSize

func FormatSize(bytes int) string

FormatSize formats a byte count for user-facing messages.

Types

type Config

type Config struct {
	FS         gbfs.FileSystem
	WorkingDir string
	HomeDir    string
	Truncation TruncationOptions
}

Config configures the coding toolset.

type ContentBlock

type ContentBlock struct {
	Type     string `json:"type"`
	Text     string `json:"text,omitempty"`
	Data     string `json:"data,omitempty"`
	MIMEType string `json:"mime_type,omitempty"`
}

ContentBlock is one structured tool-response item.

type EditDetails

type EditDetails struct {
	Diff             string `json:"diff"`
	FirstChangedLine int    `json:"first_changed_line,omitempty"`
}

EditDetails carries extra edit metadata.

type EditRequest

type EditRequest struct {
	Path    string `json:"path"`
	OldText string `json:"oldText"`
	NewText string `json:"newText"`
}

EditRequest is the edit tool input contract.

func ParseEditRequest

func ParseEditRequest(input map[string]any) (EditRequest, error)

ParseEditRequest decodes a provider tool-call payload.

type EditResponse

type EditResponse struct {
	Content []ContentBlock `json:"content"`
	Details *EditDetails   `json:"details,omitempty"`
}

EditResponse is the edit tool result contract.

type ReadDetails

type ReadDetails struct {
	Truncation *TruncationResult `json:"truncation,omitempty"`
}

ReadDetails carries extra read metadata.

type ReadRequest

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

ReadRequest is the read tool input contract.

func ParseReadRequest

func ParseReadRequest(input map[string]any) (ReadRequest, error)

ParseReadRequest decodes a provider tool-call payload.

type ReadResponse

type ReadResponse struct {
	Content []ContentBlock `json:"content"`
	Details *ReadDetails   `json:"details,omitempty"`
}

ReadResponse is the read tool result contract.

type ToolDefinition

type ToolDefinition struct {
	Name        string         `json:"name"`
	Description string         `json:"description"`
	InputSchema map[string]any `json:"input_schema"`
}

ToolDefinition is a provider-neutral function tool definition.

type Toolset

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

Toolset owns the coding tools for a specific filesystem view.

func New

func New(cfg Config) *Toolset

New constructs a read/edit/write toolset.

func (*Toolset) Edit

func (t *Toolset) Edit(ctx context.Context, req EditRequest) (EditResponse, error)

Edit runs the edit tool.

func (*Toolset) EditToolDefinition

func (t *Toolset) EditToolDefinition() ToolDefinition

EditToolDefinition returns the edit tool definition.

func (*Toolset) Read

func (t *Toolset) Read(ctx context.Context, req ReadRequest) (ReadResponse, error)

Read runs the read tool.

func (*Toolset) ReadToolDefinition

func (t *Toolset) ReadToolDefinition() ToolDefinition

ReadToolDefinition returns the read tool definition.

func (*Toolset) ToolDefinitions

func (t *Toolset) ToolDefinitions() []ToolDefinition

ToolDefinitions returns the provider-neutral tool definitions in upstream order.

func (*Toolset) Write

func (t *Toolset) Write(ctx context.Context, req WriteRequest) (WriteResponse, error)

Write runs the write tool.

func (*Toolset) WriteToolDefinition

func (t *Toolset) WriteToolDefinition() ToolDefinition

WriteToolDefinition returns the write tool definition.

type TruncationOptions

type TruncationOptions struct {
	MaxLines int `json:"max_lines,omitempty"`
	MaxBytes int `json:"max_bytes,omitempty"`
}

TruncationOptions configures read truncation.

type TruncationResult

type TruncationResult struct {
	Content               string `json:"content"`
	Truncated             bool   `json:"truncated"`
	TruncatedBy           string `json:"truncated_by,omitempty"`
	TotalLines            int    `json:"total_lines"`
	TotalBytes            int    `json:"total_bytes"`
	OutputLines           int    `json:"output_lines"`
	OutputBytes           int    `json:"output_bytes"`
	LastLinePartial       bool   `json:"last_line_partial"`
	FirstLineExceedsLimit bool   `json:"first_line_exceeds_limit"`
	MaxLines              int    `json:"max_lines"`
	MaxBytes              int    `json:"max_bytes"`
}

TruncationResult captures truncation metadata.

func TruncateHead

func TruncateHead(content string, options TruncationOptions) TruncationResult

TruncateHead truncates content from the start without returning partial lines.

type WriteRequest

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

WriteRequest is the write tool input contract.

func ParseWriteRequest

func ParseWriteRequest(input map[string]any) (WriteRequest, error)

ParseWriteRequest decodes a provider tool-call payload.

type WriteResponse

type WriteResponse struct {
	Content []ContentBlock `json:"content"`
}

WriteResponse is the write tool result contract.