harness

type AgentToolPolicy struct {
	AllowedTools               []string // Claude CLI --allowed-tools patterns
	DenyTools                  []string // Tools explicitly denied
	DangerouslySkipPermissions bool     // Whether to pass --dangerously-skip-permissions
}

type ChatCompletionRequest struct {
	Model          string            `json:"model"`
	Messages       []ChatMessage     `json:"messages"`
	Stream         bool              `json:"stream,omitempty"`
	Temperature    *float64          `json:"temperature,omitempty"`
	MaxTokens      *int              `json:"max_tokens,omitempty"`
	ResponseFormat *ResponseFormat   `json:"response_format,omitempty"`
	SystemPrompt   string            `json:"system_prompt,omitempty"` // Extension for explicit system
	TAA            json.RawMessage   `json:"taa,omitempty"`           // TAA context: false/absent=none, true=default, "name"=profile
	Tools          []json.RawMessage `json:"tools,omitempty"`         // OpenAI-format tool definitions
}

type ChatMessage struct {
	Role    string          `json:"role"`
	Content json.RawMessage `json:"content"` // Can be string or array
}

type ClaudeContent struct {
	Type      string          `json:"type"`
	Text      string          `json:"text,omitempty"`
	ID        string          `json:"id,omitempty"`          // For tool_use blocks
	Name      string          `json:"name,omitempty"`        // For tool_use blocks
	Input     json.RawMessage `json:"input,omitempty"`       // For tool_use blocks
	ToolUseID string          `json:"tool_use_id,omitempty"` // For tool_result blocks
	Content   string          `json:"content,omitempty"`     // For tool_result blocks
	IsError   bool            `json:"is_error,omitempty"`    // For tool_result blocks
}

type ClaudeMessage struct {
	Content    []ClaudeContent `json:"content,omitempty"`
	StopReason string          `json:"stop_reason,omitempty"`
	Usage      *ClaudeUsage    `json:"usage,omitempty"`
}

type ClaudeStreamMessage struct {
	Type             string           `json:"type"`
	Subtype          string           `json:"subtype,omitempty"`
	Message          *ClaudeMessage   `json:"message,omitempty"`
	Result           string           `json:"result,omitempty"`
	StructuredOutput json.RawMessage  `json:"structured_output,omitempty"`
	Usage            *ClaudeUsage     `json:"usage,omitempty"`
	ToolUseResult    *ToolUseResultEx `json:"tool_use_result,omitempty"`
}

type ClaudeUsage struct {
	InputTokens       int     `json:"input_tokens,omitempty"`
	OutputTokens      int     `json:"output_tokens,omitempty"`
	CacheReadTokens   int     `json:"cache_read_input_tokens,omitempty"`
	CacheCreateTokens int     `json:"cache_creation_input_tokens,omitempty"`
	CostUSD           float64 `json:"cost_usd,omitempty"`
}

type ContextMetrics struct {
	TotalTokens     int            `json:"total_tokens"`
	TierBreakdown   map[string]int `json:"tier_breakdown"`
	CoherenceScore  float64        `json:"coherence_score"`
	CompressionUsed bool           `json:"compression_used"`
}

type ContextState struct {
	// Tier 1: Identity (stable, ~1/3 of budget)
	Tier1Identity *ContextTier `json:"tier1_identity,omitempty"`

	// Tier 2: Temporal (session state, signals, history)
	Tier2Temporal *ContextTier `json:"tier2_temporal,omitempty"`

	// Tier 3: Present (current message context)
	Tier3Present *ContextTier `json:"tier3_present,omitempty"`

	// Tier 4: Semantic (constellation knowledge graph)
	Tier4Semantic *ContextTier `json:"tier4_semantic,omitempty"`

	// Model selection (optional override)
	Model string `json:"model,omitempty"`

	// Metadata
	TotalTokens    int     `json:"total_tokens,omitempty"`
	CoherenceScore float64 `json:"coherence_score,omitempty"`
	ShouldRefresh  bool    `json:"should_refresh,omitempty"`

	// TAA signals (from Tier 2 temporal analysis)
	Anchor string `json:"anchor,omitempty"` // Current conversation topic
	Goal   string `json:"goal,omitempty"`   // Detected user intent
}

type ContextTier struct {
	Content string `json:"content"`
	Tokens  int    `json:"tokens"`
	Source  string `json:"source,omitempty"`
}

type ContinuationState struct {
	SessionID          string `json:"session_id"`
	Timestamp          string `json:"timestamp"`
	Trigger            string `json:"trigger"`
	Focus              string `json:"focus"`
	ContinuationPrompt string `json:"continuation_prompt"`
}

type ErrorDetail struct {
	Message string `json:"message"`
	Type    string `json:"type"`
	Code    string `json:"code,omitempty"`
}

type ErrorResponse struct {
	Error ErrorDetail `json:"error"`
}

type ErrorType int

type Harness struct {

	// Debug mode
	DebugMode bool
	// contains filtered or unexported fields
}

type HookResult struct {
	Decision          string `json:"decision"`                    // "allow" or "block"
	Reason            string `json:"reason,omitempty"`            // Why blocked
	Message           string `json:"message,omitempty"`           // Human-readable message
	Fallback          bool   `json:"fallback,omitempty"`          // Used default behavior
	AdditionalContext string `json:"additionalContext,omitempty"` // Context to inject (for PreInference)
}

type InferenceConfig struct {
	DefaultProvider string                     `yaml:"default_provider,omitempty"`
	Providers       map[string]*ProviderConfig `yaml:"providers,omitempty"`
}

type InferenceRequest struct {
	ID           string          // Unique request ID (auto-generated if empty)
	Prompt       string          // User prompt
	SystemPrompt string          // Optional system prompt
	Model        string          // Model to use (empty = default)
	Schema       json.RawMessage // Optional JSON schema for structured output
	MaxTokens    *int            // Optional max tokens
	Origin       string          // Where request came from: "cli", "http", "hook", "fleet"
	Stream       bool            // Whether to stream
	Context      context.Context // For cancellation

	// Context pipeline
	ContextState *ContextState // Four-tier context for context-aware invocation

	// Tool definitions
	//
	// Tools is the full set of OpenAI-format tool definitions from the
	// client. The harness classifies each tool as internal or external via
	// ClassifyTool/PartitionTools; internal tools are executed by Claude
	// CLI or the CogOS kernel, external tools are forwarded to the client
	// as `tool_calls` on the response.
	//
	// ExternalTools, when non-nil, is a pre-partitioned list of
	// client-owned tools (equivalent to the `external` return of
	// PartitionTools(Tools)). Callers that have already partitioned can
	// populate this directly; otherwise the harness partitions Tools on
	// its own. This is the plumbing BrowserOS uses to register
	// `browser_*` tools it will execute itself.
	Tools           []json.RawMessage // OpenAI-format tool definitions from client
	ExternalTools   []json.RawMessage // Client-owned tool definitions (subset of Tools)
	AllowedTools    []string          // Claude CLI --allowed-tools patterns (e.g. "Bash", "Bash(git:*)")
	SkipPermissions bool              // Pass --dangerously-skip-permissions to Claude CLI

	// Workspace override — when set, Claude CLI runs in this directory
	// instead of the kernel's workspace.
	WorkspaceRoot string

	// MCP bridge configuration
	MCPConfig     string // Path to generated --mcp-config JSON file
	OpenClawURL   string // OpenClaw gateway URL for bridge proxy
	OpenClawToken string // Auth token for OpenClaw
	SessionID     string // Session context for tool execution

	// Claude CLI session continuity
	// When set, the harness passes --resume <ClaudeSessionID> instead of
	// starting a new session. Claude Code loads the prior conversation from
	// disk and continues where it left off.
	ClaudeSessionID string

	// Retry configuration
	MaxRetries int           // Max retry attempts (0 = use default)
	Timeout    time.Duration // Request timeout (0 = use default)
}

type InferenceResponse struct {
	ID               string `json:"id"`
	Content          string `json:"content"`
	PromptTokens     int    `json:"prompt_tokens"`
	CompletionTokens int    `json:"completion_tokens"`
	FinishReason     string `json:"finish_reason"`
	Error            error  `json:"-"`
	ErrorMessage     string `json:"error,omitempty"`

	// Anthropic cache metrics (zero for non-Claude providers)
	CacheReadTokens   int     `json:"cache_read_input_tokens,omitempty"`
	CacheCreateTokens int     `json:"cache_creation_input_tokens,omitempty"`
	CostUSD           float64 `json:"cost_usd,omitempty"`

	// Context metrics (from context pipeline)
	ContextMetrics *ContextMetrics `json:"context_metrics,omitempty"`

	// Error classification (for smart recovery)
	ErrorType ErrorType `json:"error_type,omitempty"`

	// Claude CLI session ID returned by the process. Callers should store
	// this and pass it back as ClaudeSessionID on the next request to
	// enable --resume continuity.
	ClaudeSessionID string `json:"claude_session_id,omitempty"`

	// ToolCalls lists client-owned tool invocations the model asked for
	// but the harness did not execute. The caller (typically an HTTP
	// handler) is expected to surface these as `tool_calls` on the
	// assistant message so a BrowserOS-style client can execute them and
	// send back the result on the next turn. FinishReason is set to
	// "tool_calls" when this slice is non-empty.
	ToolCalls []ToolCallData `json:"tool_calls,omitempty"`
}

type KernelServices interface {
	// WorkspaceRoot returns the resolved workspace root path.
	// Used for MCP config generation and default working directory.
	WorkspaceRoot() string

	// DispatchHook dispatches a lifecycle hook event (e.g., "PreInference",
	// "PostInference"). Returns nil if no hook matched or the hook allowed
	// the action. A "block" decision aborts inference.
	DispatchHook(event string, data map[string]any) *HookResult

	// EmitEvent writes a timestamped event to .cog/run/events/.
	// Event types: INFERENCE_START, INFERENCE_COMPLETE, INFERENCE_ERROR.
	EmitEvent(eventType string, data map[string]any) error

	// ReadContinuationState reads .cog/run/continuation.json for eigenfield
	// persistence across context compaction. Returns (nil, err) if no state.
	ReadContinuationState() (*ContinuationState, error)

	// DepositSignal places a signal in the signal field at the given location.
	// Used to mark inference as active (location="inference", type="active").
	DepositSignal(location, signalType, agentID string, halfLife float64, meta map[string]any) error

	// RemoveSignal removes a signal. Used to clear the inference-active signal
	// when a request completes.
	RemoveSignal(location, signalType string) error

	// ResolveWorkDir determines the working directory for Claude CLI execution.
	// Priority: requestWorkspace → DEFAULT_CLIENT_WORKSPACE env → kernel workspace.
	ResolveWorkDir(requestWorkspace string) string

	// ConvertOpenAIToolsToMCP converts OpenAI-format tool definitions to MCP
	// format for the bridge subprocess. Delegates to mcp.go in the kernel.
	ConvertOpenAIToolsToMCP(tools []json.RawMessage) []MCPTool

	// GetAgentToolPolicy returns the tool policy for an agent from its CRD.
	// Returns nil if no CRD is found (backward-compatible — no restriction).
	// Used by the inference path to enforce agent-specific tool restrictions.
	GetAgentToolPolicy(agentID string) (*AgentToolPolicy, error)
}

type MCPTool struct {
	Name        string                 `json:"name"`
	Description string                 `json:"description,omitempty"`
	InputSchema map[string]interface{} `json:"inputSchema,omitempty"`
}

type ModelInfo struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	Created int64  `json:"created"`
	OwnedBy string `json:"owned_by"`
}

type ModelListResponse struct {
	Object string      `json:"object"`
	Data   []ModelInfo `json:"data"`
}

type OpenAIChatMessage struct {
	Role    string `json:"role"`
	Content string `json:"content"`
}

type OpenAIChatRequest struct {
	Model         string              `json:"model"`
	Messages      []OpenAIChatMessage `json:"messages"`
	MaxTokens     *int                `json:"max_tokens,omitempty"`
	Temperature   *float64            `json:"temperature,omitempty"`
	Stream        bool                `json:"stream"`
	StreamOptions *StreamOptions      `json:"stream_options,omitempty"`
}

type OpenAIChatResponse struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	Created int64  `json:"created"`
	Model   string `json:"model"`
	Choices []struct {
		Index   int `json:"index"`
		Message struct {
			Role    string `json:"role"`
			Content string `json:"content"`
		} `json:"message"`
		FinishReason string `json:"finish_reason"`
	} `json:"choices"`
	Usage struct {
		PromptTokens     int `json:"prompt_tokens"`
		CompletionTokens int `json:"completion_tokens"`
		TotalTokens      int `json:"total_tokens"`
	} `json:"usage"`
}

type OpenAIStreamChunk struct {
	ID      string `json:"id"`
	Object  string `json:"object"`
	Created int64  `json:"created"`
	Model   string `json:"model"`
	Choices []struct {
		Index int `json:"index"`
		Delta struct {
			Role    string `json:"role,omitempty"`
			Content string `json:"content,omitempty"`
		} `json:"delta"`
		FinishReason string `json:"finish_reason,omitempty"`
	} `json:"choices"`
	Usage *OpenAIUsage `json:"usage,omitempty"`
}

type OpenAIUsage struct {
	PromptTokens     int `json:"prompt_tokens"`
	CompletionTokens int `json:"completion_tokens"`
	TotalTokens      int `json:"total_tokens"`
}

type ProviderConfig struct {
	Type    ProviderType `json:"type"`
	BaseURL string       `json:"base_url"`
	APIKey  string       `json:"api_key"`
	Model   string       `json:"model"` // Default model for this provider
}

type ProviderHealth struct {
	LastCheck *string `json:"last_check"` // ISO8601 timestamp or null
	LatencyMs *int    `json:"latency_ms"` // Latency in ms or null
	Error     *string `json:"error"`      // Error message or null
}

type ProviderInfo struct {
	ID     string               `json:"id"`
	Name   string               `json:"name"`
	Status string               `json:"status"` // "online", "offline", "unknown", "degraded"
	Active bool                 `json:"active"`
	Models []string             `json:"models"`
	Config ProviderPublicConfig `json:"config"`
	Health ProviderHealth       `json:"health"`
}

type ProviderListResponse struct {
	Object        string         `json:"object"`
	Data          []ProviderInfo `json:"data"`
	Active        string         `json:"active"`
	FallbackChain []string       `json:"fallback_chain"`
}

type ProviderPublicConfig struct {
	BaseURL   string `json:"base_url"`
	HasAPIKey bool   `json:"has_api_key"`
}

type ProviderType string

type RequestEntry struct {
	ID      string             `json:"id"`
	Origin  string             `json:"origin"`
	Model   string             `json:"model"`
	Started time.Time          `json:"started"`
	Status  string             `json:"status"` // "running", "completed", "cancelled", "failed"
	Cancel  context.CancelFunc `json:"-"`
	Prompt  string             `json:"prompt,omitempty"` // First 100 chars for display
}

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

type ResponseFormat struct {
	Type       string          `json:"type"`
	JSONSchema json.RawMessage `json:"json_schema,omitempty"`
}

type SessionInfo struct {
	SessionID       string   `json:"session_id"`
	Model           string   `json:"model"`
	Tools           []string `json:"tools,omitempty"`
	ClaudeSessionID string   `json:"claude_session_id,omitempty"` // Claude CLI session for --resume
}

type StreamChunkInference struct {
	ID           string `json:"id"`
	Content      string `json:"content"`
	Done         bool   `json:"done"`
	FinishReason string `json:"finish_reason,omitempty"`
	Error        error  `json:"-"`

	// Rich streaming fields
	EventType   string          `json:"event_type,omitempty"`   // text, tool_use, tool_result
	ToolCall    *ToolCallData   `json:"tool_call,omitempty"`    // Tool call information
	ToolResult  *ToolResultData `json:"tool_result,omitempty"`  // Tool result information
	Usage       *UsageData      `json:"usage,omitempty"`        // Token usage data
	SessionInfo *SessionInfo    `json:"session_info,omitempty"` // Session metadata

	// ExternalToolCalls carries client-owned tool invocations the harness
	// captured from the model's stream but did NOT execute. Populated on
	// the final chunk (Done=true) when the stream contained external tool
	// uses — e.g. BrowserOS's `browser_*` tools. The HTTP layer should
	// emit these as OpenAI-format `tool_calls` delta events and set
	// finish_reason="tool_calls" before terminating the stream.
	ExternalToolCalls []ToolCallData `json:"external_tool_calls,omitempty"`
}

type StreamOptions struct {
	IncludeUsage bool `json:"include_usage"`
}

type ToolCallData struct {
	ID        string          `json:"id"`
	Name      string          `json:"name"`
	Arguments json.RawMessage `json:"arguments"`
}

type ToolOwnership int

type ToolResultData struct {
	ToolCallID string `json:"tool_call_id"`
	Content    string `json:"content"`
	IsError    bool   `json:"is_error"`
}

type ToolUseResultEx struct {
	Stdout      string `json:"stdout,omitempty"`
	Stderr      string `json:"stderr,omitempty"`
	Interrupted bool   `json:"interrupted,omitempty"`
	IsImage     bool   `json:"isImage,omitempty"`
}

type UsageData struct {
	InputTokens       int     `json:"input_tokens"`
	OutputTokens      int     `json:"output_tokens"`
	CacheReadTokens   int     `json:"cache_read_tokens,omitempty"`
	CacheCreateTokens int     `json:"cache_create_tokens,omitempty"`
	CostUSD           float64 `json:"cost_usd,omitempty"`
}