api

type CIContext struct {
	Provider string
	Pipeline string
	RunID    string
	SHA      string
	Ref      string
	Matrix   map[string]string
	Metadata map[string]string
}

type CLIContext struct {
	User      string
	Workspace string
	Args      []string
	Flags     map[string]string
}

type CommandExecution struct {
	Definition commands.Definition
	Result     commands.Result
	Err        error
}

type CommandRegistration struct {
	Definition commands.Definition
	Handler    commands.Handler
}

type CompactConfig struct {
	Enabled       bool    `json:"enabled"`
	Threshold     float64 `json:"threshold"`      // trigger ratio (default 0.8)
	PreserveCount int     `json:"preserve_count"` // keep latest N messages (default 5)
	SummaryModel  string  `json:"summary_model"`  // model tier/name used for summary

	PreserveInitial  bool `json:"preserve_initial"`   // keep initial messages when compacting
	InitialCount     int  `json:"initial_count"`      // keep first N messages from the compacted prefix
	PreserveUserText bool `json:"preserve_user_text"` // keep recent user messages from the compacted prefix
	UserTextTokens   int  `json:"user_text_tokens"`   // token budget for preserved user messages

	MaxRetries    int           `json:"max_retries"`
	RetryDelay    time.Duration `json:"retry_delay"`
	FallbackModel string        `json:"fallback_model"`

	// RolloutDir enables compact event persistence when non-empty.
	// The directory is resolved relative to Options.ProjectRoot unless absolute.
	RolloutDir string `json:"rollout_dir"`
}

type CompactEvent struct {
	SessionID             string    `json:"session_id"`
	Timestamp             time.Time `json:"timestamp"`
	Summary               string    `json:"summary"`
	OriginalMessages      int       `json:"original_messages"`
	PreservedMessages     int       `json:"preserved_messages"`
	EstimatedTokensBefore int       `json:"estimated_tokens_before"`
	EstimatedTokensAfter  int       `json:"estimated_tokens_after"`
}

type ContentBlock struct {
	Type  string          `json:"type,omitempty"`  // Type is "text" or "tool_use".
	Text  string          `json:"text,omitempty"`  // Text contains streamed text when Type == "text".
	ID    string          `json:"id,omitempty"`    // ID uniquely names the content block.
	Name  string          `json:"name,omitempty"`  // Name describes the tool/function when Type == "tool_use".
	Input json.RawMessage `json:"input,omitempty"` // Input stores raw JSON arguments supplied to the tool.
}

type Delta struct {
	Type        string          `json:"type,omitempty"`         // Type is "text_delta" or "input_json_delta".
	Text        string          `json:"text,omitempty"`         // Text contains the appended text fragment when Type == "text_delta".
	PartialJSON json.RawMessage `json:"partial_json,omitempty"` // PartialJSON carries incremental JSON payload slices for tools.
	StopReason  string          `json:"stop_reason,omitempty"`  // StopReason explains why a message terminated.
}

type EntryPoint string

type HookRecorder interface {
	Record(coreevents.Event)
	Drain() []coreevents.Event
}

type Message struct {
	ID    string `json:"id,omitempty"`    // ID uniquely identifies the message on the Anthropic service.
	Type  string `json:"type,omitempty"`  // Type is typically "message".
	Role  string `json:"role,omitempty"`  // Role is "user", "assistant", etc.
	Model string `json:"model,omitempty"` // Model states which Anthropic model generated the content.
	Usage *Usage `json:"usage,omitempty"` // Usage accumulates total tokens for the message lifecycle.
}

type ModeContext struct {
	EntryPoint EntryPoint
	CLI        *CLIContext
	CI         *CIContext
	Platform   *PlatformContext
}

type ModelFactory interface {
	Model(ctx context.Context) (model.Model, error)
}

type ModelFactoryFunc func(context.Context) (model.Model, error)

type ModelStats struct {
	InputTokens   int64 `json:"input_tokens"`
	OutputTokens  int64 `json:"output_tokens"`
	TotalTokens   int64 `json:"total_tokens"`
	CacheCreation int64 `json:"cache_creation_input_tokens,omitempty"`
	CacheRead     int64 `json:"cache_read_input_tokens,omitempty"`
	RequestCount  int   `json:"request_count"`
}

type ModelTier string

type OTELConfig struct {
	// Enabled activates OpenTelemetry tracing.
	Enabled bool `json:"enabled"`

	// ServiceName identifies this service in traces. Defaults to "agentsdk-go".
	ServiceName string `json:"service_name,omitempty"`

	// Endpoint is the OTLP endpoint URL (e.g., "http://localhost:4318").
	Endpoint string `json:"endpoint,omitempty"`

	// Headers are additional HTTP headers sent with OTLP requests.
	Headers map[string]string `json:"headers,omitempty"`

	// SampleRate controls the sampling ratio (0.0-1.0). Defaults to 1.0 (100%).
	SampleRate float64 `json:"sample_rate,omitempty"`

	// Insecure allows non-TLS connections to the endpoint.
	Insecure bool `json:"insecure,omitempty"`
}

type Options struct {
	EntryPoint  EntryPoint
	Mode        ModeContext
	ProjectRoot string
	// ConfigRoot is the directory containing declarative runtime files.
	// Defaults to "<ProjectRoot>/.claude" when unset.
	ConfigRoot string
	// EmbedFS 可选的嵌入文件系统，用于支持将 .claude 目录打包到二进制
	// 当设置时，文件加载优先级为：OS 文件系统 > 嵌入 FS
	// 这允许运行时通过创建本地文件来覆盖嵌入的默认配置
	EmbedFS           fs.FS
	SettingsPath      string
	SettingsOverrides *config.Settings
	SettingsLoader    *config.SettingsLoader

	Model        model.Model
	ModelFactory ModelFactory

	// ModelPool maps tiers to model instances for cost optimization.
	// Use ModelTier constants (ModelTierLow, ModelTierMid, ModelTierHigh) as keys.
	ModelPool map[ModelTier]model.Model
	// SubagentModelMapping maps subagent type names to model tiers.
	// Keys should be lowercase subagent types: "general-purpose", "explore", "plan".
	// Subagents not in this map use the default Model.
	SubagentModelMapping map[string]ModelTier

	// DefaultEnableCache sets the default prompt caching behavior for all requests.
	// Individual requests can override this via Request.EnablePromptCache.
	// Prompt caching reduces costs for repeated context (system prompts, conversation history).
	DefaultEnableCache bool

	SystemPrompt string
	RulesEnabled *bool // nil = 默认启用，false = 禁用

	Middleware        []middleware.Middleware
	MiddlewareTimeout time.Duration
	MaxIterations     int
	Timeout           time.Duration
	TokenLimit        int
	MaxSessions       int

	Tools []tool.Tool

	// TaskStore overrides the default in-memory task store used by task_* built-ins.
	// When nil, runtime creates and owns a fresh in-memory store.
	// When provided, ownership remains with the caller.
	TaskStore tasks.Store

	// EnabledBuiltinTools controls which built-in tools are registered when Options.Tools is empty.
	// - nil (default): register all built-ins to preserve current behaviour
	// - empty slice: disable all built-in tools
	// - non-empty: enable only the listed built-ins (case-insensitive).
	// If Tools is non-empty, this whitelist is ignored in favour of the legacy Tools override.
	// Available built-in names include: bash, file_read, file_write, grep, glob.
	EnabledBuiltinTools []string

	// DisallowedTools is a blacklist of tool names (case-insensitive) that will not be registered.
	DisallowedTools []string

	// CustomTools appends caller-supplied tool.Tool implementations to the selected built-ins
	// when Tools is empty. Ignored when Tools is non-empty (legacy override takes priority).
	CustomTools []tool.Tool
	MCPServers  []string

	TypedHooks     []corehooks.ShellHook
	HookMiddleware []coremw.Middleware
	HookTimeout    time.Duration

	Skills    []SkillRegistration
	Commands  []CommandRegistration
	Subagents []SubagentRegistration
	// SkillsDirs overrides skill discovery roots. Paths may be absolute, or
	// relative to ProjectRoot. When empty, defaults to "<ConfigRoot>/skills".
	SkillsDirs []string
	// SkillsRecursive controls recursive SKILL.md discovery. Nil defaults to true.
	SkillsRecursive *bool

	Sandbox SandboxOptions

	// TokenTracking enables token usage statistics collection.
	// When true, the runtime tracks input/output tokens per session and model.
	TokenTracking bool
	// TokenCallback is called synchronously after token usage is recorded.
	// Only called when TokenTracking is true. The callback should be lightweight
	// and non-blocking to avoid delaying the agent execution. If you need async
	// processing, spawn a goroutine inside the callback.
	TokenCallback TokenCallback

	// PermissionRequestHandler handles sandbox PermissionAsk decisions. Returning
	// PermissionAllow continues tool execution; PermissionDeny rejects it; PermissionAsk
	// leaves the request pending.
	PermissionRequestHandler PermissionRequestHandler
	// ApprovalQueue optionally persists permission decisions and supports session whitelists.
	ApprovalQueue *security.ApprovalQueue
	// ApprovalApprover labels approvals/denials stored in ApprovalQueue.
	ApprovalApprover string
	// ApprovalWhitelistTTL controls session whitelist duration for approvals.
	ApprovalWhitelistTTL time.Duration
	// ApprovalWait blocks tool execution until a pending approval is resolved.
	ApprovalWait bool

	// AutoCompact enables automatic context compaction for long sessions.
	AutoCompact CompactConfig

	// OTEL configures OpenTelemetry distributed tracing.
	// Requires build tag 'otel' for actual instrumentation; otherwise no-op.
	OTEL OTELConfig
	// contains filtered or unexported fields
}

type PermissionRequest struct {
	ToolName   string
	ToolParams map[string]any
	SessionID  string
	Rule       string
	Target     string
	Reason     string
	Approval   *security.ApprovalRecord
}

type PermissionRequestHandler func(context.Context, PermissionRequest) (coreevents.PermissionDecisionType, error)

type PlatformContext struct {
	Organization string
	Project      string
	Environment  string
	Labels       map[string]string
}

type Request struct {
	Prompt            string
	ContentBlocks     []model.ContentBlock // Multimodal content; when non-empty, used alongside Prompt
	Mode              ModeContext
	SessionID         string
	RequestID         string    `json:"request_id,omitempty"` // Auto-generated UUID or user-provided
	Model             ModelTier // Optional: override model tier for this request
	EnablePromptCache *bool     // Optional: enable prompt caching (nil uses global default)
	Traits            []string
	Tags              map[string]string
	Channels          []string
	Metadata          map[string]any
	TargetSubagent    string
	ToolWhitelist     []string
	ForceSkills       []string
}

type Response struct {
	Mode           ModeContext
	RequestID      string `json:"request_id,omitempty"` // UUID for distributed tracing
	Result         *Result
	SkillResults   []SkillExecution
	CommandResults []CommandExecution
	Subagent       *subagents.Result
	HookEvents     []coreevents.Event
	// Deprecated: Use Settings instead. Kept for backward compatibility.
	ProjectConfig   *config.Settings
	Settings        *config.Settings
	SandboxSnapshot SandboxReport
	Tags            map[string]string
}

type Result struct {
	Output     string
	StopReason string
	Usage      model.Usage
	ToolCalls  []model.ToolCall
}

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

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

type SandboxOptions struct {
	Root          string
	AllowedPaths  []string
	NetworkAllow  []string
	ResourceLimit sandbox.ResourceLimits
}

type SandboxReport struct {
	Roots          []string
	AllowedPaths   []string
	AllowedDomains []string
	ResourceLimits sandbox.ResourceLimits
}

type SessionTokenStats struct {
	SessionID    string                 `json:"session_id"`
	TotalInput   int64                  `json:"total_input"`
	TotalOutput  int64                  `json:"total_output"`
	TotalTokens  int64                  `json:"total_tokens"`
	CacheCreated int64                  `json:"cache_created,omitempty"`
	CacheRead    int64                  `json:"cache_read,omitempty"`
	ByModel      map[string]*ModelStats `json:"by_model,omitempty"`
	RequestCount int                    `json:"request_count"`
	FirstRequest time.Time              `json:"first_request"`
	LastRequest  time.Time              `json:"last_request"`
}

type SkillExecution struct {
	Definition skills.Definition
	Result     skills.Result
	Err        error
}

type SkillRegistration struct {
	Definition skills.Definition
	Handler    skills.Handler
}

type SpanContext interface {
	// TraceID returns the trace identifier.
	TraceID() string

	// SpanID returns the span identifier.
	SpanID() string

	// IsRecording returns true if the span is being recorded.
	IsRecording() bool
}

type StreamEvent struct {
	Type string `json:"type"` // Type identifies the concrete SSE event kind.

	// Anthropic-compatible payloads.
	Message      *Message      `json:"message,omitempty"`       // Message holds the envelope for message_* events.
	Index        *int          `json:"index,omitempty"`         // Index orders content blocks/deltas within the message.
	ContentBlock *ContentBlock `json:"content_block,omitempty"` // ContentBlock contains partial or full block data.
	Delta        *Delta        `json:"delta,omitempty"`         // Delta carries incremental text/tool updates.
	Usage        *Usage        `json:"usage,omitempty"`         // Usage records token consumption snapshots.

	// Agent-specific extensions.
	ToolUseID string      `json:"tool_use_id,omitempty"`      // ToolUseID associates tool events with tool execution records.
	Name      string      `json:"name,omitempty"`             // Name describes the agent, tool, or block responsible for the event.
	Output    interface{} `json:"output,omitempty"`           // Output captures arbitrary structured payloads (e.g., tool stdout).
	IsStderr  *bool       `json:"is_stderr,omitempty"`        // IsStderr marks whether the output originated from stderr (not necessarily an error).
	IsError   *bool       `json:"is_error,omitempty"`         // IsError flags a genuine execution failure surfaced by the runtime/toolchain.
	SessionID string      `json:"session_id,omitempty"`       // SessionID ties events to a long-lived agent session.
	Iteration *int        `json:"iteration,omitempty"`        // Iteration indicates the current agent iteration, if applicable.
	TotalIter *int        `json:"total_iterations,omitempty"` // TotalIter reports the planned maximum iteration count.
}

type SubagentRegistration struct {
	Definition subagents.Definition
	Handler    subagents.Handler
}

type TokenCallback func(stats TokenStats)

type TokenStats struct {
	InputTokens   int64     `json:"input_tokens"`
	OutputTokens  int64     `json:"output_tokens"`
	TotalTokens   int64     `json:"total_tokens"`
	CacheCreation int64     `json:"cache_creation_input_tokens,omitempty"`
	CacheRead     int64     `json:"cache_read_input_tokens,omitempty"`
	Model         string    `json:"model"`
	SessionID     string    `json:"session_id"`
	RequestID     string    `json:"request_id"`
	Timestamp     time.Time `json:"timestamp"`
}

type Tracer interface {
	// StartAgentSpan creates a span for an agent run.
	StartAgentSpan(sessionID, requestID string, iteration int) SpanContext

	// StartModelSpan creates a child span for model generation.
	StartModelSpan(parent SpanContext, modelName string) SpanContext

	// StartToolSpan creates a child span for tool execution.
	StartToolSpan(parent SpanContext, toolName string) SpanContext

	// EndSpan completes a span with optional attributes.
	EndSpan(span SpanContext, attrs map[string]any, err error)

	// Shutdown gracefully closes the tracer and flushes pending spans.
	Shutdown() error
}

type Usage struct {
	InputTokens  int `json:"input_tokens,omitempty"`  // InputTokens counts tokens provided in the prompt.
	OutputTokens int `json:"output_tokens,omitempty"` // OutputTokens counts tokens produced by the model/toolchain.
}