tool

package
v0.32.59 Latest Latest
Warning

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

 Go to latest Published: May 14, 2026 License: MIT Imports: 34 Imported by: 0

Documentation

Index

Constants

View Source 
const (
	StreamStdout = "stdout"
	StreamStderr = "stderr"
)

Variables

This section is empty.

Functions

func CanonicalToolName 

func CanonicalToolName(name string) string

func ExpandToolGroups added in v0.20.0 

func ExpandToolGroups(groupNames []string, known map[string]struct{}) (validGroups []string, expandedTools []string, unknownGroups []string)

ExpandToolGroups expands group names into tool names using known tools.

func ExpandToolPatterns added in v0.20.0 

func ExpandToolPatterns(patterns []string, known map[string]struct{}) (validPatterns []string, matchedTools []string, invalidPatterns []string)

ExpandToolPatterns matches regex patterns against known tool names.

func IsExecToolName 

func IsExecToolName(name string) bool

func IsHighRiskToolName added in v0.31.144 

func IsHighRiskToolName(name string) bool

IsHighRiskToolName reports whether a tool's failure or invocation has non-trivial side effects (mutating, executing, or reaching outside the workspace). Used both at chat policy enforcement and by pulse auto-resume to refuse retrying a failed turn whose last action could have already mutated state — re-running it could double-apply.

func KnownToolGroupNames added in v0.25.0 

func KnownToolGroupNames() []string

func KnownToolGroups added in v0.20.0 

func KnownToolGroups(known map[string]struct{}) map[string][]string

KnownToolGroups categorizes known tool names into predefined groups.

func NormalizeToolGroupName added in v0.25.0 

func NormalizeToolGroupName(name string) string

func ToolGroupForName added in v0.25.0 

func ToolGroupForName(name string) string

func ToolNameAliases 

func ToolNameAliases() map[string]string

func WithCurrentSessionID added in v0.23.0 

func WithCurrentSessionID(ctx context.Context, sessionID string) context.Context

WithCurrentSessionID exposes the active chat session id to automation tools that need to resolve special aliases such as "current".

func WithCurrentSessionInfo added in v0.24.0 

func WithCurrentSessionInfo(ctx context.Context, sessionID string, sessionKind string) context.Context

func WithCurrentSessionKind added in v0.24.0 

func WithCurrentSessionKind(ctx context.Context, sessionKind string) context.Context

func WithCurrentTelegramTarget added in v0.24.0 

func WithCurrentTelegramTarget(ctx context.Context, chatID string, threadID string, botID string) context.Context

func WithLineEmitter added in v0.32.21 

func WithLineEmitter(ctx context.Context, emitter LineEmitter) context.Context

func WithToolOutputStreamer added in v0.32.21 

func WithToolOutputStreamer(ctx context.Context, streamer ToolOutputStreamer) context.Context

Types

type BlockedToolError added in v0.25.0 

type BlockedToolError struct {
	Tool   string `json:"tool"`
	Rule   string `json:"rule"`
	Group  string `json:"group,omitempty"`
	Source string `json:"source"`
}

func ParseBlockedToolError added in v0.25.0 

func ParseBlockedToolError(err error) (BlockedToolError, bool)

func (BlockedToolError) Error added in v0.25.0 

func (e BlockedToolError) Error() string

type ContentBlock 

type ContentBlock struct {
	Type string `json:"type"`
	Text string `json:"text"`
}

type ExecToolOptions added in v0.32.21 

type ExecToolOptions struct {
	// MaxTimeoutMS caps the per-call timeout for synchronous (foreground)
	// exec calls. 0 → defaultExecMaxTimeoutMS (5 minutes).
	MaxTimeoutMS int
	// MaxBackgroundTimeoutMS caps the per-call timeout for async
	// (background:true) calls dispatched through the ProcessManager. 0 →
	// defaultProcessMaxTimeoutMS (30 minutes). Watchers like
	// `gh pr checks --watch` and long builds run here, so this cap is
	// independently larger than MaxTimeoutMS.
	MaxBackgroundTimeoutMS int
}

ExecToolOptions tunes the exec tool factory. The zero value picks safe defaults so callers (especially tests) can omit fields they don't care about.

type LineEmitter added in v0.32.21 

type LineEmitter interface {
	EmitToolLine(toolCallID, stream, text string)
}

LineEmitter is the chat-handler-side sink that receives streaming output lines emitted by tools (e.g. exec stdout/stderr). Implementations route them onward — typically to SSE as `tool_output_line` events keyed by tool_call_id.

func LineEmitterFromContext added in v0.32.21 

func LineEmitterFromContext(ctx context.Context) LineEmitter

type PathPolicy added in v0.22.0 

type PathPolicy struct {
	PrimaryDir  string   // base for relative path resolution
	AllowedDirs []string // all directories the tool can access (absolute paths)
}

PathPolicy controls which directories file I/O tools can access.

func NewPathPolicy added in v0.22.0 

func NewPathPolicy(workspaceDir string, workDirs []string, currentDir string) PathPolicy

NewPathPolicy builds a PathPolicy. When currentDir is set, it becomes PrimaryDir; otherwise workspaceDir is used. AllowedDirs includes workspaceDir and all workDirs.

func SingleDirPolicy added in v0.22.0 

func SingleDirPolicy(workspaceDir string) PathPolicy

SingleDirPolicy creates a PathPolicy equivalent to the old single-workspaceDir behavior.

type Policy added in v0.25.0 

type Policy struct {
	AllowTools     []string
	DenyTools      []string
	AllowGroups    []string
	DenyGroups     []string
	UseAllowTools  bool
	UseAllowGroups bool
}

func (Policy) Resolve added in v0.25.0 

func (p Policy) Resolve(all []string, source string) PolicyResolution

type PolicyResolution added in v0.25.0 

type PolicyResolution struct {
	Allowed []string
	Blocked map[string]BlockedToolError
}

type ProcessManager 

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

func NewProcessManager 

func NewProcessManager() *ProcessManager

func (*ProcessManager) ClearDone 

func (m *ProcessManager) ClearDone() int

func (*ProcessManager) Kill 

func (m *ProcessManager) Kill(sessionID string) (ProcessSnapshot, error)

func (*ProcessManager) List 

func (m *ProcessManager) List() []ProcessSnapshot

func (*ProcessManager) Log 

func (m *ProcessManager) Log(sessionID string) (ProcessSnapshot, error)

func (*ProcessManager) Poll 

func (m *ProcessManager) Poll(sessionID string) (ProcessSnapshot, error)

func (*ProcessManager) Remove 

func (m *ProcessManager) Remove(sessionID string) error

func (*ProcessManager) Start 

func (m *ProcessManager) Start(ctx context.Context, workspaceDir, commandLine string, timeoutMS int) (ProcessSnapshot, error)

func (*ProcessManager) Wait added in v0.32.22 

func (m *ProcessManager) Wait(ctx context.Context, sessionID string, timeoutMS int) (ProcessSnapshot, bool, error)

Wait blocks until the named process finishes, the per-call timeout elapses, or ctx is cancelled. The returned bool reports whether the wait timed out (process is still running). This is the cheap alternative to having the LLM repeatedly call Poll, which would burn agent loop iterations for every check.

func (*ProcessManager) Write 

func (m *ProcessManager) Write(sessionID string, chars string) (ProcessSnapshot, error)

type ProcessSnapshot 

type ProcessSnapshot struct {
	SessionID   string `json:"session_id"`
	Command     string `json:"command"`
	Running     bool   `json:"running"`
	Done        bool   `json:"done"`
	ExitCode    int    `json:"exit_code,omitempty"`
	StartedAt   string `json:"started_at,omitempty"`
	CompletedAt string `json:"completed_at,omitempty"`
	Stdout      string `json:"stdout,omitempty"`
	Stderr      string `json:"stderr,omitempty"`
	Message     string `json:"message,omitempty"`
	// WaitTimedOut signals that a process wait call returned before the
	// process exited because the wait_timeout_ms elapsed.
	WaitTimedOut bool `json:"wait_timed_out,omitempty"`
}

type Registry 

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

func NewRegistry 

func NewRegistry() *Registry

NewRegistry creates a registry with RegistryScopeAny (no isolation). Prefer NewRegistryWithScope for user/pulse/reflection surfaces.

func NewRegistryWithScope added in v0.25.0 

func NewRegistryWithScope(scope RegistryScope) *Registry

NewRegistryWithScope creates a registry bound to the given scope. Any Register() call whose tool name starts with a forbidden prefix for that scope will panic — this is a compile-time-style guarantee enforced at wiring time to prevent cross-surface tool leakage.

func (*Registry) All 

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

func (*Registry) Get 

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

func (*Registry) Register 

func (r *Registry) Register(t Tool)

func (*Registry) Schemas 

func (r *Registry) Schemas() []llm.ToolSchema

func (*Registry) SchemasForNames 

func (r *Registry) SchemasForNames(names []string) []llm.ToolSchema

func (*Registry) Scope added in v0.25.0 

func (r *Registry) Scope() RegistryScope

Scope returns the scope this registry was created with.

type RegistryScope added in v0.25.0 

type RegistryScope int

RegistryScope identifies the surface a tool Registry belongs to.

The TARS runtime is split into two surfaces:

  • User surface — chat sessions, agents. Registries use RegistryScopeUser.
  • System surface — pulse (watchdog) and reflection (nightly batch). Pulse uses RegistryScopePulse, reflection uses RegistryScopeReflection.

Each non-Any scope declares prefixes that must NOT be registered in it. This prevents accidental cross-surface tool leakage (e.g. a pulse-only tool ending up in a user chat registry). Violations panic at Register() time — these are programmer errors, not runtime conditions. 

const (
	// RegistryScopeAny is the default scope with no restrictions. It exists
	// for backwards compatibility with NewRegistry() callers and tests that
	// don't care about surface isolation.
	RegistryScopeAny RegistryScope = iota
	// RegistryScopeUser is the user-facing surface (chat, agent).
	RegistryScopeUser
	// RegistryScopePulse is the pulse runtime surface.
	RegistryScopePulse
	// RegistryScopeReflection is the reflection runtime surface.
	RegistryScopeReflection
)

func (RegistryScope) String added in v0.25.0 

func (s RegistryScope) String() string

String returns a human-readable scope name used in panic messages.

type Result 

type Result struct {
	Content []ContentBlock `json:"content"`
	IsError bool           `json:"is_error,omitempty"`
}

func JSONTextResult added in v0.15.0 

func JSONTextResult(value any, isError bool) Result

JSONTextResult marshals a value to JSON text and wraps it in a Result.

func (Result) Text 

func (r Result) Text() string

type SessionStatus 

type SessionStatus struct {
	SessionID       string `json:"session_id"`
	HistoryMessages int    `json:"history_messages"`
}

type SubagentsTaskMirrorConfig added in v0.31.88 

type SubagentsTaskMirrorConfig struct {
	Store        *session.Store
	WorkspaceDir string
	GetSessionID func() string
}

SubagentsTaskMirrorConfig wires subagent planning/orchestration progress into the same per-session tasks file used by the Console Tasks panel.

type TelegramDefaultChatIDResolveFunc 

type TelegramDefaultChatIDResolveFunc func(ctx context.Context) (string, error)

func (TelegramDefaultChatIDResolveFunc) ResolveDefaultChatID 

func (f TelegramDefaultChatIDResolveFunc) ResolveDefaultChatID(ctx context.Context) (string, error)

type TelegramDefaultChatIDResolver 

type TelegramDefaultChatIDResolver interface {
	ResolveDefaultChatID(ctx context.Context) (string, error)
}

type TelegramSendFunc 

type TelegramSendFunc func(ctx context.Context, req TelegramSendRequest) (TelegramSendResult, error)

func (TelegramSendFunc) Send 

func (f TelegramSendFunc) Send(ctx context.Context, req TelegramSendRequest) (TelegramSendResult, error)

type TelegramSendRequest 

type TelegramSendRequest struct {
	BotID     string
	ChatID    string
	Text      string
	ThreadID  string
	ParseMode string
}

type TelegramSendResult 

type TelegramSendResult struct {
	MessageID int64  `json:"message_id"`
	ChatID    string `json:"chat_id"`
	Text      string `json:"text"`
}

type TelegramSender 

type TelegramSender interface {
	Send(ctx context.Context, req TelegramSendRequest) (TelegramSendResult, error)
}

type Tool 

type Tool struct {
	Name        string
	Description string
	Parameters  json.RawMessage
	Execute     func(ctx context.Context, params json.RawMessage) (Result, error)
}

func NewAgentRuntimeTool added in v0.31.5 

func NewAgentRuntimeTool(runtime *agentruntime.Runtime, enabled bool) Tool

func NewAgentSyspromptGetTool added in v0.18.0 

func NewAgentSyspromptGetTool(workspaceDir string) Tool

func NewAgentSyspromptSetTool added in v0.18.0 

func NewAgentSyspromptSetTool(workspaceDir string) Tool

func NewAgentsListTool 

func NewAgentsListTool(runtime *agentruntime.Runtime) Tool

func NewApplyPatchTool 

func NewApplyPatchTool(workspaceDir string, enabled bool) Tool

func NewCronCreateTool 

func NewCronCreateTool(store *cron.Store) Tool

func NewCronDeleteTool 

func NewCronDeleteTool(store *cron.Store) Tool

func NewCronGetTool 

func NewCronGetTool(store *cron.Store) Tool

func NewCronListTool 

func NewCronListTool(store *cron.Store) Tool

func NewCronRunTool 

func NewCronRunTool(store *cron.Store, runJob func(ctx context.Context, job cron.Job) (string, error)) Tool

func NewCronRunsTool 

func NewCronRunsTool(store *cron.Store) Tool

func NewCronTool 

func NewCronTool(store *cron.Store, runJob func(ctx context.Context, job cron.Job) (string, error)) Tool

func NewCronUpdateTool 

func NewCronUpdateTool(store *cron.Store) Tool

func NewEditFileTool 

func NewEditFileTool(workspaceDir string) Tool

func NewEditFileToolWithPolicy added in v0.22.0 

func NewEditFileToolWithPolicy(policy PathPolicy) Tool

func NewEditTool 

func NewEditTool(workspaceDir string) Tool

func NewExecTool 

func NewExecTool(workspaceDir string) Tool

func NewExecToolWithManager 

func NewExecToolWithManager(workspaceDir string, manager *ProcessManager) Tool

func NewExecToolWithOptions added in v0.32.21 

func NewExecToolWithOptions(policy PathPolicy, manager *ProcessManager, opts ExecToolOptions) Tool

NewExecToolWithOptions exposes the timeout knobs so chat handlers can raise per-call caps from runtime config. Foreground and background caps are independent: foreground stays modest (default 5min) while background tolerates long watchers (default 30min).

func NewExecToolWithPolicy added in v0.22.0 

func NewExecToolWithPolicy(policy PathPolicy, manager *ProcessManager) Tool

func NewGlobTool 

func NewGlobTool(workspaceDir string) Tool

func NewGlobToolWithPolicy added in v0.22.0 

func NewGlobToolWithPolicy(policy PathPolicy) Tool

func NewListDirTool 

func NewListDirTool(workspaceDir string) Tool

func NewListDirToolWithPolicy added in v0.22.0 

func NewListDirToolWithPolicy(policy PathPolicy) Tool

func NewMemoryGetTool 

func NewMemoryGetTool(workspaceDir string, backend memory.Backend) Tool

func NewMemorySaveTool 

func NewMemorySaveTool(backend memory.Backend, nowFn func() time.Time) Tool

func NewMemorySearchTool 

func NewMemorySearchTool(workspaceDir string, backend memory.Backend) Tool

func NewMemoryTool added in v0.19.0 

func NewMemoryTool(workspaceDir string, backend memory.Backend, nowFn func() time.Time) Tool

NewMemoryTool creates a single "memory" tool that dispatches to save, search, and get sub-actions. Replaces the individual memory_save, memory_search, and memory_get tools.

func NewMessageTool 

func NewMessageTool(runtime *agentruntime.Runtime, enabled bool) Tool

func NewProcessTool 

func NewProcessTool(manager *ProcessManager) Tool

func NewProjectSkillToolWithPolicy added in v0.31.179 

func NewProjectSkillToolWithPolicy(policy PathPolicy) Tool

func NewReadFileTool 

func NewReadFileTool(workspaceDir string) Tool

func NewReadFileToolWithPolicy added in v0.22.0 

func NewReadFileToolWithPolicy(policy PathPolicy) Tool

func NewReadTool 

func NewReadTool(workspaceDir string) Tool

func NewSessionStatusTool 

func NewSessionStatusTool(getStatus func(ctx context.Context) (SessionStatus, error)) Tool

func NewSessionTool added in v0.19.0 

func NewSessionTool(
	store *session.Store,
	runtime *agentruntime.Runtime,
	getStatus func(ctx context.Context) (SessionStatus, error),
) Tool

NewSessionTool creates a single "session" tool that dispatches to status, list, history, send, spawn, runs, and agents sub-actions. Replaces session_status, sessions_list/history/send/spawn/runs, and agents_list.

func NewSessionsHistoryTool 

func NewSessionsHistoryTool(store *session.Store) Tool

func NewSessionsListTool 

func NewSessionsListTool(store *session.Store) Tool

func NewSessionsRunsTool 

func NewSessionsRunsTool(runtime *agentruntime.Runtime) Tool

func NewSessionsSendTool 

func NewSessionsSendTool(runtime *agentruntime.Runtime) Tool

func NewSessionsSpawnTool 

func NewSessionsSpawnTool(runtime *agentruntime.Runtime) Tool

func NewSubagentsOrchestrateTool added in v0.25.0 

func NewSubagentsOrchestrateTool(runtime *agentruntime.Runtime, mirrorConfig ...SubagentsTaskMirrorConfig) Tool

func NewSubagentsPlanTool added in v0.25.0 

func NewSubagentsPlanTool(runtime *agentruntime.Runtime, router llm.Router, mirrorConfig ...SubagentsTaskMirrorConfig) Tool

func NewSubagentsRunTool added in v0.10.0 

func NewSubagentsRunTool(runtime *agentruntime.Runtime) Tool

func NewTasksTool added in v0.20.0 

func NewTasksTool(store *session.Store, workspaceDir string, getSessionID func() string) Tool

NewTasksTool creates a "tasks" aggregator tool for managing per-session plan and tasks. The plan follows a small state machine (drafting → proposed → executing ↔ paused, terminal: completed/aborted) so the chat UI can offer review/approve and runtime intervention without extra round-trips.

func NewTelegramSendTool 

func NewTelegramSendTool(sender TelegramSender, enabled bool, resolver TelegramDefaultChatIDResolver) Tool

func NewUsageReportTool 

func NewUsageReportTool(tracker *usage.Tracker) Tool

func NewWebFetchTool 

func NewWebFetchTool(enabled bool) Tool

func NewWebFetchToolWithOptions 

func NewWebFetchToolWithOptions(opts WebFetchOptions) Tool

func NewWebSearchTool 

func NewWebSearchTool(enabled bool, apiKey string) Tool

func NewWebSearchToolWithOptions 

func NewWebSearchToolWithOptions(opts WebSearchOptions) Tool

func NewWorkspaceSyspromptGetTool added in v0.18.0 

func NewWorkspaceSyspromptGetTool(workspaceDir string) Tool

func NewWorkspaceSyspromptSetTool added in v0.18.0 

func NewWorkspaceSyspromptSetTool(workspaceDir string) Tool

func NewWorkspaceTool added in v0.19.0 

func NewWorkspaceTool(workspaceDir string) Tool

NewWorkspaceTool creates a single "workspace" tool that manages workspace and agent system-prompt files. Replaces workspace_sysprompt_get/set and agent_sysprompt_get/set.

func NewWriteFileTool 

func NewWriteFileTool(workspaceDir string) Tool

func NewWriteFileToolWithPolicy added in v0.22.0 

func NewWriteFileToolWithPolicy(policy PathPolicy) Tool

func NewWriteTool 

func NewWriteTool(workspaceDir string) Tool

type ToolOutputStreamer added in v0.32.21 

type ToolOutputStreamer interface {
	EmitLine(stream, text string)
}

ToolOutputStreamer is the per-tool-call view that tools see. It binds a tool_call_id once at the agent-loop boundary so tool code can call EmitLine without threading the id through every call site.

func BindLineEmitter added in v0.32.21 

func BindLineEmitter(emitter LineEmitter, toolCallID string) ToolOutputStreamer

BindLineEmitter wraps a chat-level LineEmitter into a per-tool-call ToolOutputStreamer. Returns nil when the parent emitter is nil.

func ToolOutputStreamerFromContext added in v0.32.21 

func ToolOutputStreamerFromContext(ctx context.Context) ToolOutputStreamer

type WebFetchOptions 

type WebFetchOptions struct {
	Enabled              bool
	AllowPrivateHosts    bool
	PrivateHostAllowlist []string
	HTTPClient           *http.Client
}

type WebSearchOptions 

type WebSearchOptions struct {
	Enabled           bool
	Provider          string
	BraveAPIKey       string
	BraveBaseURL      string
	PerplexityAPIKey  string
	PerplexityModel   string
	PerplexityBaseURL string
	CacheTTL          time.Duration
	HTTPClient        *http.Client
}

Source Files

View all Source files

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.