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 ¶
- type ExecutorResult
- type InterruptBehavior
- type ProgressEvent
- type Registry
- func (r *Registry) Count() int
- func (r *Registry) Execute(ctx context.Context, name string, input map[string]any) (ToolResult, error)
- func (r *Registry) ExecuteWithProgress(ctx context.Context, name string, input map[string]any, ...) (ToolResult, error)
- func (r *Registry) Get(name string) (Tool, bool)
- func (r *Registry) GetAll() []Tool
- func (r *Registry) GetToolDefinitions() []map[string]any
- func (r *Registry) GetToolDefinitionsForMode(mode RuntimeMode) []map[string]any
- func (r *Registry) GetTools(mode RuntimeMode) []Tool
- func (r *Registry) LoadCustomTools(dir string) error
- func (r *Registry) Register(tool Tool)
- func (r *Registry) RegisterWithModes(tool Tool, modes ...RuntimeMode)
- func (r *Registry) SetPermissionChecker(checker *permissions.Checker)
- type RuntimeMode
- type StreamingToolExecutor
- func (e *StreamingToolExecutor) AddTool(callID, toolName, inputJSON string)
- func (e *StreamingToolExecutor) Cancel()
- func (e *StreamingToolExecutor) Done()
- func (e *StreamingToolExecutor) OnProgress(fn func(ProgressEvent))
- func (e *StreamingToolExecutor) SetCascadeOnFailure(enabled bool)
- func (e *StreamingToolExecutor) States() map[string]ToolState
- func (e *StreamingToolExecutor) Wait() []ExecutorResult
- type Tool
- type ToolResult
- type ToolState
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 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 (*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) GetToolDefinitions ¶
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 ¶
LoadCustomTools loads JSON tool definitions from a directory. This provides backwards compatibility with ~/.celeste/skills/*.json files.
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) 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 )
Source Files
Directories