toolcall

type Definition struct {
	Name        string
	Description string
	Parameters  []Parameter

	// Annotations describes behavioral hints about this tool. When non-nil,
	// these are forwarded to MCP clients that support tool annotations.
	Annotations *ToolAnnotations

	// OutputSchema is an optional JSON Schema describing the tool's response.
	// Used by MCP's Tool.OutputSchema field.
	OutputSchema *Schema

	// InputSchemaDefs holds the "$defs" map from the top-level input schema.
	// Real-world MCP servers (e.g. Google Cloud Run, GKE) use "$defs" and
	// "$ref" to express shared sub-schemas; this field preserves them so they
	// survive a round-trip through extractParameters → mcpTool.
	InputSchemaDefs map[string]*Schema

	// InputSchemaDescription is the "description" field on the top-level input
	// schema object. It is distinct from Description (the tool's own description)
	// and typically contains the proto message description.
	InputSchemaDescription string

	// InputSchemaExtensions holds any top-level input schema keywords that are
	// not otherwise modelled (e.g. "$schema" meta-schema declaration used by
	// Linear and other non-Google MCP servers).
	InputSchemaExtensions map[string]any
}

type EmptyTools struct{}

type FindingTools[T any] struct {
	callbacks.FindingCallbacks
	// contains filtered or unexported fields
}

type HistoryTools[T any] struct {
	callbacks.HistoryCallbacks
	// contains filtered or unexported fields
}

type Parameter struct {
	Name        string
	Type        string // "string"|"integer"|"boolean"|"number"|"array"|"object"|"null"
	Description string
	Required    bool

	// Items is the element schema for array-type parameters (Type=="array").
	Items *Schema
	// Properties defines named sub-schemas for object-type parameters (Type=="object").
	Properties map[string]*Schema
	// PropertyRequired lists property names that are required within an
	// object-type parameter. Distinct from Required, which controls whether
	// the parameter itself must be present in the tool call.
	PropertyRequired []string
	// AdditionalProperties constrains extra properties on an object parameter.
	// Use FalseSchema() to disallow all additional properties.
	AdditionalProperties *Schema
	// Enum restricts the parameter to a fixed set of allowed values.
	Enum []any

	// Numeric constraints.
	Minimum          *float64
	Maximum          *float64
	ExclusiveMinimum *float64
	ExclusiveMaximum *float64
	MultipleOf       *float64

	// String constraints.
	MinLength *int
	MaxLength *int
	Pattern   string

	// Schema metadata.
	Title      string
	Default    any
	Deprecated bool
	Format     string

	// Schema composition.
	OneOf []*Schema
	AnyOf []*Schema
	AllOf []*Schema
	Not   *Schema

	// Ref is a JSON Schema "$ref" value (e.g. "#/$defs/MyType"). When set,
	// other fields may still be present alongside it (JSON Schema allows
	// sibling keywords next to $ref in draft 2019-09+).
	Ref string

	// ReadOnly marks the parameter as read-only (JSON Schema "readOnly").
	ReadOnly bool
	// WriteOnly marks the parameter as write-only (JSON Schema "writeOnly").
	WriteOnly bool

	// Extensions holds vendor-specific extension keywords (e.g. "x-google-identifier").
	// Keys should begin with "x-" per JSON Schema convention.
	Extensions map[string]any
}

type Schema struct {
	Type        string
	Description string
	Title       string
	Format      string

	// Object fields.
	Properties           map[string]*Schema
	Required             []string // required property names within this object schema
	AdditionalProperties *Schema  // use FalseSchema() to disallow additional properties
	// Defs holds "$defs" named sub-schemas. Typically used at the top level of
	// an input schema to define reusable types referenced via $ref.
	Defs map[string]*Schema

	// Array fields.
	Items *Schema

	// Enum restricts values to a fixed set.
	Enum []any

	// Numeric constraints.
	Minimum          *float64
	Maximum          *float64
	ExclusiveMinimum *float64
	ExclusiveMaximum *float64
	MultipleOf       *float64

	// String constraints.
	MinLength *int
	MaxLength *int
	Pattern   string

	// Schema metadata.
	Default    any
	Deprecated bool
	ReadOnly   bool
	WriteOnly  bool

	// Ref is a JSON Schema "$ref" value (e.g. "#/$defs/MyType").
	Ref string

	// Extensions holds vendor-specific extension keywords (e.g. "x-google-identifier").
	Extensions map[string]any

	// Schema composition.
	OneOf []*Schema
	AnyOf []*Schema
	AllOf []*Schema
	Not   *Schema

	// False represents the JSON Schema boolean false schema (matches nothing).
	// Use FalseSchema() rather than setting this field directly. It is used
	// primarily for AdditionalProperties to disallow any extra properties.
	False bool
}

type Tool[Resp any] struct {
	Def     Definition
	Handler func(ctx context.Context, call ToolCall, trace *agenttrace.Trace[Resp], result *Resp) map[string]any
}

type ToolAnnotations struct {
	// ReadOnly indicates the tool does not modify any state. Defaults to false.
	ReadOnly bool
	// Destructive indicates the tool may cause irreversible changes (e.g. delete).
	// Nil means unset; the MCP default is true (assume destructive unless stated).
	Destructive *bool
	// Idempotent indicates repeated calls with the same arguments have the same
	// effect as a single call. Defaults to false.
	Idempotent bool
	// OpenWorld indicates the tool may interact with external systems beyond
	// the immediate context (e.g. web searches, external APIs).
	// Nil means unset; the MCP default is true (assume open-world unless stated).
	OpenWorld *bool
}

type ToolCall struct {
	ID   string
	Name string
	Args map[string]any
}

type ToolProvider[Resp, CB any] interface {
	// Tools returns unified tool definitions that work with any provider.
	Tools(ctx context.Context, cb CB) (map[string]Tool[Resp], error)
}

type WorktreeTools[T any] struct {
	callbacks.WorktreeCallbacks
	// contains filtered or unexported fields
}