types

type AgentEvent struct {
	Type      AgentEventType         `json:"type"`
	AgentName string                 `json:"agent_name,omitempty"`
	Content   string                 `json:"content,omitempty"`
	ToolCall  *ToolCallEvent         `json:"tool_call,omitempty"`
	Approval  *ApprovalEvent         `json:"approval,omitempty"` // for AgentEventApproval
	Error     error                  `json:"error,omitempty"`
	Metadata  map[string]interface{} `json:"metadata,omitempty"`
	// Usage is set on AgentEventComplete for the root agent: aggregated token usage for the run.
	Usage      *LLMUsage `json:"usage,omitempty"`
	Timestamp  time.Time `json:"timestamp"`
	WorkflowID string    `json:"workflow_id,omitempty"` // optional run identifier for correlation (implementation-defined)
}

type AgentEventType string

type AgentMode string

type AgentResponse struct {
	Content   string         `json:"content"`
	AgentName string         `json:"agent_name"`
	Model     string         `json:"model"`
	Metadata  map[string]any `json:"metadata"`
	// Usage is the sum of token usage across all LLM calls in this run (when reported by the provider).
	Usage *LLMUsage `json:"usage,omitempty"`
}

type ApprovalEvent struct {
	ToolCallID    string         `json:"tool_call_id,omitempty"`
	ToolName      string         `json:"tool_name"`
	Args          map[string]any `json:"args,omitempty"`
	ApprovalToken string         `json:"approval_token,omitempty"`
	// Kind is tool vs sub-agent delegation; use for UI copy.
	Kind ToolApprovalKind `json:"kind,omitempty"`
	// DelegateToName is set when Kind is delegation: display name of the target sub-agent.
	SubAgentName string `json:"sub_agent_name,omitempty"`
}

type ApprovalHandler func(ctx context.Context, req *ApprovalRequest)

type ApprovalRequest struct {
	ToolName string         `json:"tool_name"`
	Args     map[string]any `json:"args"`
	Respond  ApprovalSender `json:"-"`
	// Kind matches ApprovalEvent: distinguish normal tools from sub-agent delegation.
	Kind ToolApprovalKind `json:"kind,omitempty"`
	// AgentName is the agent that requested approval for the current run.
	AgentName string `json:"agent_name,omitempty"`
	// SubAgentName is set for delegation: human-friendly target specialist name.
	SubAgentName string `json:"sub_agent_name,omitempty"`
}

type ApprovalSender func(status ApprovalStatus) error

type ApprovalStatus string

type JSONSchema map[string]any

type LLMReasoning struct {
	// Enabled requests reasoning/thinking where the provider supports it.
	// Anthropic: if true and BudgetTokens is 0, uses the minimum extended-thinking budget (1024 tokens).
	// OpenAI: does not infer reasoning_effort from Enabled alone (standard models reject that param).
	// Gemini: contributes to turning on thought output with IncludeThoughts.
	Enabled bool

	// Effort is a generic reasoning intensity: "none", "minimal", "low", "medium", "high", "xhigh".
	// OpenAI: sent as reasoning_effort only when non-empty; use only with reasoning-capable models.
	// Gemini: mapped to ThinkingLevel when recognized (low/medium/high/minimal), unless BudgetTokens > 0.
	// Anthropic: not used (use Enabled and BudgetTokens for extended thinking).
	Effort string

	// BudgetTokens is the token budget for internal reasoning / extended thinking.
	// Anthropic: extended thinking; must be >= 1024 when non-zero (values below are clamped).
	// Gemini: ThinkingBudget. If non-zero, Effort is not mapped to ThinkingLevel (API allows only one).
	// OpenAI: not used.
	BudgetTokens int
}

type LLMSampling struct {
	Temperature *float64 // 0-2 OpenAI, 0-1 Anthropic; also Gemini
	MaxTokens   int      // 0 = provider default
	TopP        *float64 // 0-1; OpenAI and Gemini (not Anthropic)
	TopK        *int     // Anthropic only
	// Reasoning: optional generic reasoning/thinking; mapped per provider.
	Reasoning *LLMReasoning
}

type LLMUsage struct {
	PromptTokens       int64 `json:"prompt_tokens,omitempty"`
	CompletionTokens   int64 `json:"completion_tokens,omitempty"`
	TotalTokens        int64 `json:"total_tokens,omitempty"`
	CachedPromptTokens int64 `json:"cached_prompt_tokens,omitempty"`
	ReasoningTokens    int64 `json:"reasoning_tokens,omitempty"`
}

type MCPLoopback struct {
	Transport any
}

type MCPStdio struct {
	Command string
	Args    []string
	Env     map[string]string
}

type MCPStreamableHTTP struct {
	URL string
	// Token is a static bearer token when OAuthClientCreds is not used for auth.
	Token string
	// OAuthClientCreds configures OAuth2 client-credentials; when any OAuth field is set, Token must be empty and id/secret/token_url are required together.
	OAuthClientCreds *clientcredentials.Config
	Headers          map[string]string
	SkipTLSVerify    bool
}

type MCPToolFilter struct {
	AllowTools []string
	BlockTools []string
}

type MCPTransportConfig interface {
	// Kind returns a stable transport id ("stdio", "streamable_http") for logging and routing.
	Kind() MCPTransportType
	// Validate checks the transport is usable before connect (the default MCP client calls this from NewClient).
	Validate() error
}

type MCPTransportType string

type RunAsyncResult struct {
	Response *AgentResponse
	Err      error
}

type SubAgentRoute struct {
	Name             string                   `json:"name"`
	TaskQueue        string                   `json:"task_queue"`
	ChildRoutes      map[string]SubAgentRoute `json:"child_routes,omitempty"`
	AgentFingerprint string                   `json:"agent_fingerprint,omitempty"`
}

type ToolApprovalKind string

type ToolCallEvent struct {
	ToolCallID string         `json:"tool_call_id,omitempty"`
	ToolName   string         `json:"tool_name"`
	Args       map[string]any `json:"args,omitempty"`
	Result     any            `json:"result,omitempty"`
	Status     ToolCallStatus `json:"status"`
}

type ToolCallStatus string

type ToolSpec struct {
	Name        string     `json:"name"`
	Description string     `json:"description"`
	Parameters  JSONSchema `json:"parameters"`
}