api

type Attachment struct {
	Type     string // "image" or "file"
	FilePath string // Local file path
	MimeType string // e.g., "image/jpeg", "image/png"
}

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 ContextReport struct {
	SystemChars int                 `json:"systemChars"`
	SkillsChars int                 `json:"skillsChars"`
	Tools       ContextToolsReport  `json:"tools"`
	EstTokens   ContextTokensReport `json:"estTokens"`
}

type ContextTokensReport struct {
	System int `json:"system"`
	Skills int `json:"skills"`
	Tools  int `json:"tools"`
	Total  int `json:"total"`
}

type ContextToolEntry struct {
	Name         string `json:"name"`
	SummaryChars int    `json:"summaryChars"`
	SchemaChars  int    `json:"schemaChars"`
}

type ContextToolsReport struct {
	Count       int                `json:"count"`
	ListChars   int                `json:"listChars"`
	SchemaChars int                `json:"schemaChars"`
	Entries     []ContextToolEntry `json:"entries"`
}

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 MemoryFlushConfig struct {
	// Enabled turns memory flush on or off. Default false.
	Enabled bool

	// ReserveTokensFloor is the number of tokens reserved for model output during the flush turn.
	// This is separate from ContextWindowHardMinTokens (which is the hard reject threshold).
	// 0 defaults to 20000 (same as openclaw's DEFAULT_PI_COMPACTION_RESERVE_TOKENS_FLOOR).
	ReserveTokensFloor int

	// SoftThresholdTokens is the additional early-trigger buffer before ReserveTokensFloor.
	// 0 defaults to 4000 (same as openclaw).
	SoftThresholdTokens int

	// Prompt is the synthetic user message injected for the flush turn.
	// Empty uses the default openclaw-style prompt.
	Prompt string
}

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
	// 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
	// PromptGuardEnabled blocks user attempts to request/rewrite/reveal
	// system or hidden instructions. nil defaults to true.
	PromptGuardEnabled *bool
	// PromptGuardModelFactory provides a dedicated classifier model for
	// multilingual prompt-exfiltration detection. When nil, input guard falls
	// back to fail-open (output guard still applies).
	PromptGuardModelFactory ModelFactory
	// OutputGuardEnabled redacts assistant outputs that appear to disclose
	// system prompt content. nil defaults to true.
	OutputGuardEnabled *bool
	RulesEnabled       *bool // nil = 默认启用，false = 禁用

	Middleware        []middleware.Middleware
	MiddlewareTimeout time.Duration
	MaxIterations     int
	Timeout           time.Duration
	TokenLimit        int
	MaxSessions       int
	// HistoryLimit caps the number of user turns loaded from persisted history
	// into the active session context. 0 means no limit (all history loaded).
	// Keeping this small reduces token usage and encourages use of memory tools.
	HistoryLimit int

	// Real-time event callback for progress updates during execution.
	// Triggered synchronously every ProgressInterval tool calls.
	// Default behavior (if nil): no real-time events, only post-execution events in Response.HookEvents.
	RealtimeEventCallback func(event RealtimeEvent)

	// ProgressInterval controls how often progress log messages are sent (every N tool calls).
	// 0 means use the default (5). Only effective when RealtimeEventCallback is set.
	ProgressInterval int

	// AutoRecall enables automatic memory injection before each agent turn.
	// When true, the runtime searches MEMORY.md + memory/*.md using the user's
	// prompt and prepends the top results as <relevant-memories> context.
	// This ensures the agent always has relevant past context without needing
	// to decide whether to call MemorySearch itself.
	AutoRecall bool

	// AutoRecallMaxResults controls how many memory snippets are injected.
	// 0 means use the default (3).
	AutoRecallMaxResults int

	Tools []tool.Tool

	// 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

	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

	// ContextWindowTokens is the total context window size in tokens for the configured model.
	// When set to > 0, enables the Context Window Guard which warns when approaching the limit
	// and emits pressure signals when estimated remaining tokens fall below ContextWindowHardMinTokens.
	// Must be configured manually when using self-hosted proxies that don't advertise context size.
	// Common values: 200000 (Claude 3.5/3.7 Sonnet), 128000 (GPT-4o), 32000 (smaller models).
	ContextWindowTokens int

	// ContextWindowWarnRatio is the fraction of ContextWindowTokens at which a warning is emitted.
	// 0 or unset defaults to 0.8 (warn when more than 80% of context window is estimated used).
	ContextWindowWarnRatio float64

	// ContextWindowHardMinTokens is the minimum estimated remaining tokens below which the runtime
	// raises an internal pressure signal (no user-facing reset instructions).
	// 0 or unset defaults to 2000.
	ContextWindowHardMinTokens int

	// MemoryFlush controls automatic memory flush before context window exhaustion.
	// When enabled, the runtime runs a hidden agent turn to persist important memories
	// to disk (memory/YYYY-MM-DD.md) when input tokens approach the configured limit.
	// This mirrors openclaw's pre-compaction memory flush behaviour.
	// Requires ContextWindowTokens to be set.
	MemoryFlush MemoryFlushConfig

	// 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

	// Logger 自定义日志记录器。如果为 nil，使用默认的控制台 logger。
	// 调用方可以注入自己的 logger.Logger 来控制日志输出和格式。
	Logger logger.Logger
	// 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 RealtimeEvent struct {
	Type      RealtimeEventType // Event type
	Message   string            // Human-readable message
	Count     int               // Tool count (for progress) or error count (for error guard)
	LastTool  string            // Name of the most recent tool
	Timestamp time.Time         // When the event occurred
	SessionID string            // Optional session identifier
	Metadata  map[string]any    // Optional structured payload

	// Recent tool calls with details (for progress updates)
	RecentCalls []ToolCallSummary
}

type RealtimeEventType string

type Request struct {
	Prompt            string
	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
	Attachments       []Attachment // Optional: images or files for multimodal requests
}

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
	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 ToolCallSummary struct {
	Name   string // Tool name
	Params string // Summarized params (truncated to 100 chars)
	Output string // Summarized output (truncated to 200 chars)
}

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.
}