tools

package
v1.8.3 Latest Latest
Warning

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

 Go to latest Published: Apr 5, 2026 License: MIT Imports: 12 Imported by: 0

Documentation

Overview

Package tools provides the unified tool abstraction for Celeste CLI. This file implements StreamingToolExecutor, a state machine that accepts tool calls as they arrive during LLM streaming and dispatches them according to their concurrency safety.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ExecutorResult 

type ExecutorResult struct {
	CallID   string     // The tool call ID from the LLM
	ToolName string     // The tool name
	State    ToolState  // Final state
	Result   ToolResult // Tool output (content and/or error)
	Err      error      // Go error if tool execution returned one
}

ExecutorResult holds the result of a single tool execution, including the call metadata and final state.

type HookResult added in v1.8.0 

type HookResult struct {
	Decision string // "approve" or "block"
	Output   string
}

HookResult is the outcome of a pre/post tool hook.

type HookRunner added in v1.8.0 

type HookRunner interface {
	RunPreToolUse(toolName string, input map[string]any) (*HookResult, error)
	RunPostToolUse(toolName string, input map[string]any) (*HookResult, error)
}

HookRunner is an interface for running pre/post tool hooks. This avoids a circular dependency between tools and hooks packages.

type InterruptBehavior 

type InterruptBehavior int

InterruptBehavior defines how a tool responds to cancellation signals. 

const (
	// InterruptCancel means the tool should be cancelled immediately.
	InterruptCancel InterruptBehavior = iota
	// InterruptBlock means the tool should block until completion.
	InterruptBlock
)

type ProgressEvent 

type ProgressEvent struct {
	ToolName string  `json:"tool_name"`
	Message  string  `json:"message"`
	Percent  float64 `json:"percent"` // -1 for indeterminate
}

ProgressEvent represents a progress update from a running tool.

type Registry 

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

Registry manages the collection of available tools and their mode associations.

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a new empty tool registry.

func (*Registry) Count 

func (r *Registry) Count() int

Count returns the number of registered tools.

func (*Registry) Execute 

func (r *Registry) Execute(ctx context.Context, name string, input map[string]any) (ToolResult, error)

Execute runs a tool by name with input validation.

func (*Registry) ExecuteWithProgress 

func (r *Registry) ExecuteWithProgress(ctx context.Context, name string, input map[string]any, progress chan<- ProgressEvent) (ToolResult, error)

ExecuteWithProgress runs a tool by name with input validation and a progress channel.

func (*Registry) Get 

func (r *Registry) Get(name string) (Tool, bool)

Get returns a tool by name.

func (*Registry) GetAll 

func (r *Registry) GetAll() []Tool

GetAll returns all registered tools sorted by name.

func (*Registry) GetToolDefinitions 

func (r *Registry) GetToolDefinitions() []map[string]any

GetToolDefinitions returns all tools in OpenAI function-calling format.

func (*Registry) GetToolDefinitionsForMode 

func (r *Registry) GetToolDefinitionsForMode(mode RuntimeMode) []map[string]any

GetToolDefinitionsForMode returns tools for the given mode in OpenAI function-calling format.

func (*Registry) GetTools 

func (r *Registry) GetTools(mode RuntimeMode) []Tool

GetTools returns tools available for the given mode, sorted by name.

func (*Registry) LoadCustomTools 

func (r *Registry) LoadCustomTools(dir string) error

LoadCustomTools loads JSON tool definitions from a directory. This provides backwards compatibility with ~/.celeste/skills/*.json files.

func (*Registry) Register 

func (r *Registry) Register(tool Tool)

Register adds a tool that is available in all modes.

func (*Registry) RegisterWithModes 

func (r *Registry) RegisterWithModes(tool Tool, modes ...RuntimeMode)

RegisterWithModes adds a tool that is only available in the specified modes.

func (*Registry) SetHookRunner added in v1.8.0 

func (r *Registry) SetHookRunner(runner HookRunner)

SetHookRunner sets the hook runner used for pre/post tool hooks. If runner is nil, no hooks are executed (default behavior).

func (*Registry) SetPermissionChecker 

func (r *Registry) SetPermissionChecker(checker *permissions.Checker)

SetPermissionChecker sets the permission checker used to gate tool execution. If checker is nil, all tools are allowed (default behavior).

type RuntimeMode 

type RuntimeMode int

RuntimeMode represents the execution mode of the CLI. 

const (
	ModeChat RuntimeMode = iota
	ModeClaw
	ModeAgent
	ModeOrchestrator
)

type StreamingToolExecutor 

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

StreamingToolExecutor accepts tool calls as they arrive during LLM streaming and dispatches them for execution. Concurrency-safe tools run in parallel goroutines; non-concurrent tools are queued and executed serially. Results are buffered and returned in original call order when Wait() is called.

func NewStreamingToolExecutor 

func NewStreamingToolExecutor(registry *Registry) *StreamingToolExecutor

NewStreamingToolExecutor creates a new executor bound to the given registry. The executor uses a background context; cancel it to abort all running tools.

func NewStreamingToolExecutorWithContext 

func NewStreamingToolExecutorWithContext(ctx context.Context, registry *Registry) *StreamingToolExecutor

NewStreamingToolExecutorWithContext creates a new executor with a parent context. Cancelling the parent context will abort all running tools.

func (*StreamingToolExecutor) AddTool 

func (e *StreamingToolExecutor) AddTool(callID, toolName, inputJSON string)

AddTool submits a tool call for execution. This method is non-blocking. It parses the input JSON, looks up the tool in the registry, determines concurrency safety, and either launches a goroutine or enqueues for serial execution. If the tool is not found, the entry is immediately marked Failed.

inputJSON is the raw JSON arguments string from the LLM.

func (*StreamingToolExecutor) Cancel 

func (e *StreamingToolExecutor) Cancel()

Cancel aborts all running and queued tools.

func (*StreamingToolExecutor) Done 

func (e *StreamingToolExecutor) Done()

Done signals that no more tool calls will be added. Must be called before Wait() will return.

func (*StreamingToolExecutor) OnProgress 

func (e *StreamingToolExecutor) OnProgress(fn func(ProgressEvent))

OnProgress registers a callback for tool progress events. Must be called before AddTool. Not safe to call concurrently with AddTool.

func (*StreamingToolExecutor) SetCascadeOnFailure 

func (e *StreamingToolExecutor) SetCascadeOnFailure(enabled bool)

SetCascadeOnFailure enables cascading failure mode. When enabled, if any tool fails, all queued and executing sibling tools are cancelled via context cancellation.

func (*StreamingToolExecutor) States 

func (e *StreamingToolExecutor) States() map[string]ToolState

States returns a snapshot of current tool states.

func (*StreamingToolExecutor) Wait 

func (e *StreamingToolExecutor) Wait() []ExecutorResult

Wait blocks until all tool calls have completed and returns results in the original call order. Callers must call Done() before or concurrently with Wait(), otherwise Wait() will block forever.

type Tool 

type Tool interface {
	Name() string
	Description() string
	Parameters() json.RawMessage
	IsConcurrencySafe(input map[string]any) bool
	IsReadOnly() bool
	ValidateInput(input map[string]any) error
	Execute(ctx context.Context, input map[string]any, progress chan<- ProgressEvent) (ToolResult, error)
	InterruptBehavior() InterruptBehavior
}

Tool defines the interface that all tools must implement.

type ToolResult 

type ToolResult struct {
	Content  string         `json:"content"`
	Error    bool           `json:"error,omitempty"`
	Metadata map[string]any `json:"metadata,omitempty"`
}

ToolResult represents the output of a tool execution.

type ToolState 

type ToolState int

ToolState represents the lifecycle state of a tool execution. 

const (
	// ToolStateQueued means the tool is waiting to be executed.
	ToolStateQueued ToolState = iota
	// ToolStateExecuting means the tool is currently running.
	ToolStateExecuting
	// ToolStateCompleted means the tool finished successfully.
	ToolStateCompleted
	// ToolStateFailed means the tool finished with an error.
	ToolStateFailed
	// ToolStateAborted means the tool was cancelled (cascading failure or interrupt).
	ToolStateAborted
)

func (ToolState) String 

func (s ToolState) String() string

String returns a human-readable name for the tool state.

Source Files

View all Source files

Directories

Path Synopsis
Package builtin provides Alchemy blockchain API handler implementation
 Package builtin provides Alchemy blockchain API handler implementation
cmd/celeste/tools/mcp/adapter.go
 cmd/celeste/tools/mcp/adapter.go

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.