code

type CodeError struct {
	// Message describes the error.
	Message string

	// Line is the 1-based line number where the error occurred.
	// Zero indicates the line is unknown.
	Line int

	// Column is the 1-based column number where the error occurred.
	// Zero indicates the column is unknown.
	Column int

	// Err is the underlying error, if any.
	Err error
}

type Config struct {
	// Index provides tool discovery and lookup capabilities.
	// Required.
	Index index.Index

	// Docs provides tool documentation.
	// Required.
	Docs tooldoc.Store

	// Run provides tool execution capabilities.
	// Required.
	Run run.Runner

	// Engine is the pluggable code execution engine.
	// Required.
	Engine Engine

	// DefaultTimeout is the default execution timeout when not specified
	// in ExecuteParams. If zero, no default timeout is applied.
	DefaultTimeout time.Duration

	// DefaultLanguage is the default language when not specified in
	// ExecuteParams. Defaults to "go" if empty.
	DefaultLanguage string

	// MaxToolCalls limits the maximum number of tool invocations per
	// execution. Zero means unlimited.
	MaxToolCalls int

	// MaxChainSteps limits the maximum number of steps allowed in a single
	// RunChain call. Zero means unlimited.
	MaxChainSteps int

	// Logger is an optional logger for observability.
	Logger Logger
}

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

type Engine interface {
	// Execute runs a code snippet with access to the tools environment.
	// It returns the execution result including the final value, output,
	// and any errors encountered.
	Execute(ctx context.Context, params ExecuteParams, tools Tools) (ExecuteResult, error)
}

type ExecuteParams struct {
	// Language specifies the programming language of the code snippet.
	// If empty, the executor's default language is used.
	Language string `json:"language"`

	// Code is the source code to execute.
	Code string `json:"code"`

	// Timeout specifies the maximum duration for execution.
	// If zero, the executor's default timeout is used.
	Timeout time.Duration `json:"timeout"`

	// MaxToolCalls limits the number of tool invocations allowed.
	// If zero, the executor's configured limit applies (or unlimited if none).
	MaxToolCalls int `json:"maxToolCalls,omitempty"`
}

type ExecuteResult struct {
	// Value is the final result of the code execution, typically from the
	// __out variable convention.
	Value any `json:"value,omitempty"`

	// Stdout contains any output written via Println or similar.
	Stdout string `json:"stdout,omitempty"`

	// Stderr contains any error output from the execution.
	Stderr string `json:"stderr,omitempty"`

	// ToolCalls records all tool invocations made during execution.
	ToolCalls []ToolCallRecord `json:"toolCalls,omitempty"`

	// DurationMs is the total execution time in milliseconds.
	DurationMs int64 `json:"durationMs"`
}

type Executor interface {
	// ExecuteCode runs a code snippet with the given parameters.
	// It applies configuration defaults, enforces limits, and collects
	// tool call traces and output.
	ExecuteCode(ctx context.Context, params ExecuteParams) (ExecuteResult, error)
}

type Logger interface {
	// Logf logs a formatted message.
	Logf(format string, args ...any)
}

type ToolCallRecord struct {
	// ToolID is the canonical identifier of the tool that was called.
	ToolID string `json:"toolId"`

	// Args contains the arguments passed to the tool.
	Args map[string]any `json:"args,omitempty"`

	// Structured contains the structured result from a successful tool execution.
	Structured any `json:"structured,omitempty"`

	// BackendKind indicates which backend executed the tool (mcp, provider, local).
	BackendKind string `json:"backendKind,omitempty"`

	// Error contains the error message if the tool call failed.
	Error string `json:"error,omitempty"`

	// ErrorOp indicates the operation that failed (e.g., "run", "chain").
	ErrorOp string `json:"errorOp,omitempty"`

	// DurationMs is the execution time in milliseconds.
	DurationMs int64 `json:"durationMs"`
}

type Tools interface {
	// SearchTools searches for tools matching the query, returning up to limit results.
	SearchTools(ctx context.Context, query string, limit int) ([]index.Summary, error)

	// ListNamespaces returns all available tool namespaces.
	ListNamespaces(ctx context.Context) ([]string, error)

	// DescribeTool returns documentation for a tool at the specified detail level.
	DescribeTool(ctx context.Context, id string, level tooldoc.DetailLevel) (tooldoc.ToolDoc, error)

	// ListToolExamples returns up to maxExamples usage examples for a tool.
	ListToolExamples(ctx context.Context, id string, maxExamples int) ([]tooldoc.ToolExample, error)

	// RunTool executes a single tool and returns the result.
	// Each call is recorded in the tool call trace.
	RunTool(ctx context.Context, id string, args map[string]any) (run.RunResult, error)

	// RunChain executes a sequence of tool calls, where each step can
	// optionally use the previous step's result via UsePrevious.
	// Each step is recorded in the tool call trace.
	RunChain(ctx context.Context, steps []run.ChainStep) (run.RunResult, []run.StepResult, error)

	// Println writes output to the captured stdout buffer.
	Println(args ...any)
}