local

package
v0.4.0 Latest Latest
Warning

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

Go to latest
Published: Feb 2, 2026 License: MIT Imports: 14 Imported by: 0

Documentation

Overview

Package local provides an embedded local mode for running agents in-process with filesystem access. This enables CLI assistants like Gemini CLI and Codex that lack native sub-agents to leverage multi-agent orchestration via MCP.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type AgentConfig

type AgentConfig struct {
	// Name is the unique identifier for the agent.
	Name string `yaml:"name" json:"name"`

	// Description explains when to use this agent.
	Description string `yaml:"description" json:"description"`

	// Instructions is the system prompt or path to a markdown file.
	Instructions string `yaml:"instructions" json:"instructions"`

	// Tools lists the tools available to this agent.
	// Available: read, write, glob, grep, shell
	Tools []string `yaml:"tools" json:"tools"`

	// Model overrides the default LLM model for this agent.
	Model string `yaml:"model,omitempty" json:"model,omitempty"`

	// MaxTokens limits the response length.
	MaxTokens int `yaml:"max_tokens,omitempty" json:"max_tokens,omitempty"`
}

AgentConfig defines a single agent.

type AgentInfo

type AgentInfo struct {
	Name        string `json:"name"`
	Description string `json:"description"`
}

AgentInfo holds basic information about an agent.

type AgentResult

type AgentResult struct {
	Agent   string `json:"agent"`
	Input   string `json:"input"`
	Output  string `json:"output"`
	Success bool   `json:"success"`
	Error   string `json:"error,omitempty"`
}

AgentResult holds the result of an agent invocation.

type AgentTask

type AgentTask struct {
	Agent string `json:"agent"`
	Input string `json:"input"`
}

AgentTask represents a task to be executed by an agent.

type CommandResult

type CommandResult struct {
	Command  string   `json:"command"`
	Args     []string `json:"args,omitempty"`
	Stdout   string   `json:"stdout"`
	Stderr   string   `json:"stderr"`
	ExitCode int      `json:"exit_code"`
}

CommandResult holds the result of a command execution.

func (*CommandResult) Success

func (r *CommandResult) Success() bool

Success returns true if the command exited successfully.

type CompletionResponse

type CompletionResponse struct {
	Content   string     `json:"content"`
	ToolCalls []ToolCall `json:"tool_calls,omitempty"`
	Done      bool       `json:"done"`
}

CompletionResponse holds the LLM response.

type Config

type Config struct {
	// Mode should be "local" for embedded mode.
	Mode string `yaml:"mode" json:"mode"`

	// Workspace is the root directory for filesystem access.
	// Defaults to current working directory.
	Workspace string `yaml:"workspace" json:"workspace"`

	// Agents defines the available agents.
	Agents []AgentConfig `yaml:"agents" json:"agents"`

	// MCP configures the MCP server interface.
	MCP MCPConfig `yaml:"mcp" json:"mcp"`

	// LLM configures the language model.
	LLM LLMConfig `yaml:"llm" json:"llm"`

	// Timeouts for various operations.
	Timeouts TimeoutConfig `yaml:"timeouts" json:"timeouts"`
}

Config holds configuration for local embedded mode.

func DefaultConfig

func DefaultConfig() Config

DefaultConfig returns a configuration with sensible defaults.

func LoadConfig

func LoadConfig(path string) (*Config, error)

LoadConfig loads configuration from a JSON or YAML file. The format is detected by file extension (.json, .yaml, .yml).

func LoadConfigFromBytes

func LoadConfigFromBytes(data []byte, format ConfigFormat) (*Config, error)

LoadConfigFromBytes loads configuration from bytes with explicit format.

func (*Config) GetAgentConfig

func (c *Config) GetAgentConfig(name string) (*AgentConfig, error)

GetAgentConfig returns the configuration for a specific agent.

func (*Config) ListAgentNames

func (c *Config) ListAgentNames() []string

ListAgentNames returns the names of all configured agents.

func (*Config) Validate

func (c *Config) Validate() error

Validate checks that the configuration is valid.

type ConfigFormat

type ConfigFormat string

ConfigFormat specifies the configuration file format.

const (
	// FormatJSON indicates JSON format.
	FormatJSON ConfigFormat = "json"
	// FormatYAML indicates YAML format.
	FormatYAML ConfigFormat = "yaml"
)

type Duration

type Duration time.Duration

Duration is a time.Duration that supports human-readable strings in JSON/YAML. Examples: "5m", "30s", "2h30m", "100ms"

func (Duration) Duration

func (d Duration) Duration() time.Duration

Duration returns the time.Duration value.

func (Duration) MarshalJSON

func (d Duration) MarshalJSON() ([]byte, error)

MarshalJSON implements json.Marshaler for Duration.

func (*Duration) UnmarshalJSON

func (d *Duration) UnmarshalJSON(b []byte) error

UnmarshalJSON implements json.Unmarshaler for Duration.

func (*Duration) UnmarshalYAML

func (d *Duration) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler for Duration.

type EmbeddedAgent

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

EmbeddedAgent is a lightweight agent that runs in-process.

func NewEmbeddedAgent

func NewEmbeddedAgent(cfg AgentConfig, toolSet *ToolSet, llm LLMClient) (*EmbeddedAgent, error)

NewEmbeddedAgent creates a new embedded agent.

func (*EmbeddedAgent) Description

func (a *EmbeddedAgent) Description() string

Description returns the agent's description.

func (*EmbeddedAgent) Invoke

func (a *EmbeddedAgent) Invoke(ctx context.Context, input string) (*AgentResult, error)

Invoke runs the agent with the given input and returns the result.

func (*EmbeddedAgent) Name

func (a *EmbeddedAgent) Name() string

Name returns the agent's name.

type FileInfo

type FileInfo struct {
	Name  string `json:"name"`
	IsDir bool   `json:"is_dir"`
	Size  int64  `json:"size"`
}

FileInfo holds basic file information.

type GlobTool

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

GlobTool wraps GlobFiles as a Tool interface.

func (*GlobTool) Description

func (t *GlobTool) Description() string

func (*GlobTool) Execute

func (t *GlobTool) Execute(ctx context.Context, args map[string]any) (any, error)

func (*GlobTool) Name

func (t *GlobTool) Name() string

type GrepMatch

type GrepMatch struct {
	File    string `json:"file"`
	Line    int    `json:"line"`
	Content string `json:"content"`
}

GrepMatch represents a single grep match.

type GrepTool

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

GrepTool wraps GrepFiles as a Tool interface.

func (*GrepTool) Description

func (t *GrepTool) Description() string

func (*GrepTool) Execute

func (t *GrepTool) Execute(ctx context.Context, args map[string]any) (any, error)

func (*GrepTool) Name

func (t *GrepTool) Name() string

type LLMClient

type LLMClient interface {
	// Complete generates a completion for the given messages.
	Complete(ctx context.Context, messages []Message, tools []ToolDefinition) (*CompletionResponse, error)
}

LLMClient defines the interface for language model interactions.

type LLMConfig

type LLMConfig struct {
	// Provider is the LLM provider: "openai", "anthropic", "gemini", "ollama".
	Provider string `yaml:"provider" json:"provider"`

	// Model is the default model to use.
	Model string `yaml:"model" json:"model"`

	// APIKey is the API key (can use env var reference like ${OPENAI_API_KEY}).
	APIKey string `yaml:"api_key,omitempty" json:"api_key,omitempty"`

	// BaseURL overrides the API base URL.
	BaseURL string `yaml:"base_url,omitempty" json:"base_url,omitempty"`

	// Temperature controls randomness (0.0-1.0).
	Temperature float64 `yaml:"temperature,omitempty" json:"temperature,omitempty"`
}

LLMConfig configures the language model provider.

type MCPConfig

type MCPConfig struct {
	// Enabled determines if the MCP server is active.
	Enabled bool `yaml:"enabled" json:"enabled"`

	// Transport is the MCP transport type: "stdio" or "http".
	Transport string `yaml:"transport" json:"transport"`

	// Port is used when transport is "http".
	Port int `yaml:"port,omitempty" json:"port,omitempty"`

	// ServerName is the name reported in MCP server info.
	ServerName string `yaml:"server_name,omitempty" json:"server_name,omitempty"`

	// ServerVersion is the version reported in MCP server info.
	ServerVersion string `yaml:"server_version,omitempty" json:"server_version,omitempty"`
}

MCPConfig configures the MCP server interface.

type Message

type Message struct {
	Role    string `json:"role"` // "system", "user", "assistant", "tool"
	Content string `json:"content"`
	Name    string `json:"name,omitempty"`    // For tool messages
	ToolID  string `json:"tool_id,omitempty"` // For tool messages
}

Message represents a chat message.

type OrchestratedResult

type OrchestratedResult struct {
	Task    string         `json:"task"`
	Mode    string         `json:"mode"`
	Results []*AgentResult `json:"results"`
}

OrchestratedResult holds the results of an orchestrated task.

func (*OrchestratedResult) AllSuccessful

func (r *OrchestratedResult) AllSuccessful() bool

AllSuccessful returns true if all agent results were successful.

func (*OrchestratedResult) Summary

func (r *OrchestratedResult) Summary() string

Summary returns a summary of all results.

type OrchestratedTask

type OrchestratedTask struct {
	// Name is a descriptive name for the task.
	Name string `json:"name"`

	// Agents lists the agents to involve, in order of execution for sequential,
	// or all at once for parallel.
	Agents []string `json:"agents"`

	// Input is the task description/prompt.
	Input string `json:"input"`

	// Mode is "parallel" or "sequential".
	Mode string `json:"mode"`
}

OrchestratedTask represents a high-level task that may involve multiple agents.

type ReadTool

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

ReadTool wraps ReadFile as a Tool interface.

func (*ReadTool) Description

func (t *ReadTool) Description() string

func (*ReadTool) Execute

func (t *ReadTool) Execute(ctx context.Context, args map[string]any) (any, error)

func (*ReadTool) Name

func (t *ReadTool) Name() string

type Runner

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

Runner orchestrates multiple embedded agents.

func NewRunner

func NewRunner(cfg *Config, llm LLMClient) (*Runner, error)

NewRunner creates a new agent runner.

func (*Runner) Close

func (r *Runner) Close() error

Close cleans up resources.

func (*Runner) ExecuteOrchestrated

func (r *Runner) ExecuteOrchestrated(ctx context.Context, task OrchestratedTask) (*OrchestratedResult, error)

ExecuteOrchestrated runs an orchestrated task involving multiple agents.

func (*Runner) GetAgent

func (r *Runner) GetAgent(name string) (*EmbeddedAgent, bool)

GetAgent returns an agent by name.

func (*Runner) GetAgentInfo

func (r *Runner) GetAgentInfo(name string) (*AgentInfo, error)

GetAgentInfo returns information about an agent.

func (*Runner) Invoke

func (r *Runner) Invoke(ctx context.Context, agentName, input string) (*AgentResult, error)

Invoke runs a single agent synchronously.

func (*Runner) InvokeParallel

func (r *Runner) InvokeParallel(ctx context.Context, tasks []AgentTask) ([]*AgentResult, error)

InvokeParallel runs multiple agents concurrently.

func (*Runner) InvokeSequential

func (r *Runner) InvokeSequential(ctx context.Context, tasks []AgentTask) ([]*AgentResult, error)

InvokeSequential runs multiple agents in sequence, passing context between them.

func (*Runner) ListAgentInfo

func (r *Runner) ListAgentInfo() []AgentInfo

ListAgentInfo returns information about all registered agents.

func (*Runner) ListAgents

func (r *Runner) ListAgents() []string

ListAgents returns the names of all registered agents.

func (*Runner) ToolSet

func (r *Runner) ToolSet() *ToolSet

ToolSet returns the tool set.

func (*Runner) Workspace

func (r *Runner) Workspace() string

Workspace returns the workspace path.

type ShellTool

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

ShellTool wraps RunShell as a Tool interface.

func (*ShellTool) Description

func (t *ShellTool) Description() string

func (*ShellTool) Execute

func (t *ShellTool) Execute(ctx context.Context, args map[string]any) (any, error)

func (*ShellTool) Name

func (t *ShellTool) Name() string

type TimeoutConfig

type TimeoutConfig struct {
	// AgentInvoke is the timeout for a single agent invocation.
	AgentInvoke Duration `yaml:"agent_invoke" json:"agent_invoke"`

	// ShellCommand is the timeout for shell command execution.
	ShellCommand Duration `yaml:"shell_command" json:"shell_command"`

	// FileRead is the timeout for file read operations.
	FileRead Duration `yaml:"file_read" json:"file_read"`

	// ParallelTotal is the total timeout for parallel agent execution.
	ParallelTotal Duration `yaml:"parallel_total" json:"parallel_total"`
}

TimeoutConfig defines timeouts for various operations.

type Tool

type Tool interface {
	Name() string
	Description() string
	Execute(ctx context.Context, args map[string]any) (any, error)
}

Tool represents a capability available to agents.

type ToolCall

type ToolCall struct {
	ID        string         `json:"id"`
	Name      string         `json:"name"`
	Arguments map[string]any `json:"arguments"`
}

ToolCall represents an LLM's request to call a tool.

type ToolDefinition

type ToolDefinition struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description"`
	Parameters  map[string]interface{} `json:"parameters"`
}

ToolDefinition defines a tool for the LLM.

type ToolSet

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

ToolSet provides filesystem and shell tools scoped to a workspace.

func NewToolSet

func NewToolSet(workspace string) *ToolSet

NewToolSet creates a new tool set for the given workspace.

func (*ToolSet) CreateTools

func (ts *ToolSet) CreateTools(names []string) ([]Tool, error)

CreateTools creates Tool instances for the specified tool names.

func (*ToolSet) GlobFiles

func (ts *ToolSet) GlobFiles(ctx context.Context, pattern string) ([]string, error)

GlobFiles finds files matching a glob pattern within the workspace.

func (*ToolSet) GrepFiles

func (ts *ToolSet) GrepFiles(ctx context.Context, pattern, filePattern string) ([]GrepMatch, error)

GrepFiles searches for a pattern in files within the workspace.

func (*ToolSet) ListDirectory

func (ts *ToolSet) ListDirectory(ctx context.Context, path string) ([]FileInfo, error)

ListDirectory lists the contents of a directory within the workspace.

func (*ToolSet) ReadFile

func (ts *ToolSet) ReadFile(ctx context.Context, path string) (string, error)

ReadFile reads the contents of a file within the workspace.

func (*ToolSet) RunCommand

func (ts *ToolSet) RunCommand(ctx context.Context, command string, args []string) (*CommandResult, error)

RunCommand executes a shell command within the workspace.

func (*ToolSet) RunShell

func (ts *ToolSet) RunShell(ctx context.Context, shellCmd string) (*CommandResult, error)

RunShell executes a shell command string within the workspace.

func (*ToolSet) SetMaxFileSize

func (ts *ToolSet) SetMaxFileSize(size int64)

SetMaxFileSize sets the maximum file size for read operations.

func (*ToolSet) WriteFile

func (ts *ToolSet) WriteFile(ctx context.Context, path, content string) error

WriteFile writes content to a file within the workspace.

type WriteTool

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

WriteTool wraps WriteFile as a Tool interface.

func (*WriteTool) Description

func (t *WriteTool) Description() string

func (*WriteTool) Execute

func (t *WriteTool) Execute(ctx context.Context, args map[string]any) (any, error)

func (*WriteTool) Name

func (t *WriteTool) Name() string

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL