tool

Documentation

Overview

Package tool provides the clarify tool — ask the user a question and wait for a response. The tool blocks until a response arrives via an injected answer function.

Package tool defines the Tool interface and a thread-safe registry.

Package tool provides the send_message tool — send intermediate messages, files, or interactive prompts to the Telegram chat during an agent run.

Index

• Variables
• func IsReservedCallbackPrefix(data string) bool
• type ClarifyArgs
• type ClarifyTool
  • func NewClarifyTool(answer func(question string) (string, error)) *ClarifyTool
  • func (t *ClarifyTool) Call(argsJSON string) (string, error)
  • func (t *ClarifyTool) Description() string
  • func (t *ClarifyTool) Name() string
  • func (t *ClarifyTool) Schema() any
• type Registry
  • func NewRegistry(tools []Tool) *Registry
  • func (r *Registry) Get(name string) Tool
  • func (r *Registry) Tools() []Tool
• type SendMessageTool
  • func NewSendMessageTool(sender func(text string, file string, buttons [][]map[string]string) error) *SendMessageTool
  • func (t *SendMessageTool) Call(argsJSON string) (string, error)
  • func (t *SendMessageTool) Description() string
  • func (t *SendMessageTool) Name() string
  • func (t *SendMessageTool) Schema() any
• type Tool

Variables

var ReservedCallbackPrefixes = []string{
	"apr:",
	"den:",
	"trs:",
	"clarify:",
	"skill_save:",
	"skill_skip:",
}

ReservedCallbackPrefixes lists callback-data prefixes that are reserved for internal odek UI flows (approval, trust, clarify, skill suggestions). The send_message tool rejects buttons using these prefixes so a compromised agent cannot forge an approval/skill UI.

Functions

func IsReservedCallbackPrefix

func IsReservedCallbackPrefix(data string) bool

IsReservedCallbackPrefix reports whether data starts with a reserved internal callback-data prefix.

Types

type ClarifyArgs

type ClarifyArgs struct {
	Question string `json:"question"` // question to ask the user
}

ClarifyArgs is the JSON schema for clarify tool arguments.

type ClarifyTool

type ClarifyTool struct {
	// Answer is called with the question text. The returned string is the
	// user's response, or an error if no answer was received (timeout,
	// cancellation, etc.). This function blocks until the user responds.
	Answer func(question string) (string, error)
}

ClarifyTool implements the agent tool interface for asking the user questions during a task. The actual delivery and response collection is handled by an injected AnswerFunc (platform-specific).

func NewClarifyTool

func NewClarifyTool(answer func(question string) (string, error)) *ClarifyTool

NewClarifyTool creates a ClarifyTool with the given answer function. The answer function is platform-specific — it delivers the question to the user and returns their response (blocking until available).

func (*ClarifyTool) Call

func (t *ClarifyTool) Call(argsJSON string) (string, error)

Call blocks until the user provides an answer or an error occurs. The question is delivered to the user via the injected Answer function (e.g., via Telegram message, CLI prompt, or web UI).

func (*ClarifyTool) Description

func (t *ClarifyTool) Description() string

func (*ClarifyTool) Name

func (t *ClarifyTool) Name() string

func (*ClarifyTool) Schema

func (t *ClarifyTool) Schema() any

type Registry

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

Registry holds Tools and provides thread-safe lookup.

func NewRegistry

func NewRegistry(tools []Tool) *Registry

NewRegistry creates a Registry from a slice of Tools. Duplicate names cause a panic.

func (*Registry) Get

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

Get returns a Tool by name, or nil if not found.

func (*Registry) Tools

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

Tools returns all registered tools.

type SendMessageTool

type SendMessageTool struct {
	// Sender delivers the message. Called synchronously — returns nil on
	// success or an error if delivery failed. The tool does NOT wait for
	// user response; use clarify for interactive prompts.
	Sender func(text string, file string, buttons [][]map[string]string) error
}

SendMessageTool lets the agent send arbitrary messages to the Telegram chat with optional inline keyboards and file attachments. Unlike the final answer (which flows through the handler's SendResponse), this tool sends messages immediately mid-task.

func NewSendMessageTool

func NewSendMessageTool(sender func(text string, file string, buttons [][]map[string]string) error) *SendMessageTool

NewSendMessageTool creates a SendMessageTool with the given sender function.

func (*SendMessageTool) Call

func (t *SendMessageTool) Call(argsJSON string) (string, error)

Call sends the message via the injected Sender function.

func (*SendMessageTool) Description

func (t *SendMessageTool) Description() string

func (*SendMessageTool) Name

func (t *SendMessageTool) Name() string

func (*SendMessageTool) Schema

func (t *SendMessageTool) Schema() any

type Tool

type Tool interface {
	Name() string
	Description() string
	Schema() any // JSON Schema for tool parameters
	Call(args string) (string, error)
}

Tool is the interface the agent uses to discover and invoke capabilities. It's identical to the top-level odek.Tool — re-exported here for internal use.