config

type AIConfig struct {
	// Providers is the provider registry available to the runtime and UI.
	//
	// Notes:
	// - Providers own their allowed model list (provider + model are always configured together).
	Providers []AIProvider `json:"providers,omitempty"`

	// CurrentModelID points to the model used by default for new chats.
	//
	// Format: <provider_id>/<model_name>
	CurrentModelID string `json:"current_model_id"`

	// Mode controls the AI runtime behavior.
	//
	// Supported values:
	// - "act": full tool execution flow (default)
	// - "plan": planning-first mode with strict readonly execution (mutating actions are blocked)
	Mode string `json:"mode,omitempty"`

	// ToolRecoveryEnabled controls runtime-level recovery orchestration.
	//
	// When enabled, the Go runtime can continue attempts after recoverable tool failures
	// instead of ending the turn immediately.
	ToolRecoveryEnabled *bool `json:"tool_recovery_enabled,omitempty"`

	// ToolRecoveryMaxSteps limits how many recovery continuations can happen in one run.
	//
	// Defaults to 3.
	ToolRecoveryMaxSteps *int `json:"tool_recovery_max_steps,omitempty"`

	// ToolRecoveryAllowPathRewrite controls deterministic path normalization/rewrite strategies.
	ToolRecoveryAllowPathRewrite *bool `json:"tool_recovery_allow_path_rewrite,omitempty"`

	// ToolRecoveryAllowProbeTools is reserved for strategy diversification retries in runtime recovery.
	ToolRecoveryAllowProbeTools *bool `json:"tool_recovery_allow_probe_tools,omitempty"`

	// ToolRecoveryFailOnRepeatedSignature controls fail-fast behavior when the same failure signature
	// repeats across recovery attempts.
	ToolRecoveryFailOnRepeatedSignature *bool `json:"tool_recovery_fail_on_repeated_signature,omitempty"`

	// ExecutionPolicy controls runtime execution guardrails.
	//
	// Defaults are intentionally permissive:
	// - no user approval requirement
	// - no dangerous-command hard block
	ExecutionPolicy *AIExecutionPolicy `json:"execution_policy,omitempty"`

	// TerminalExecPolicy controls the bounded execution policy for terminal.exec.
	//
	// The built-in defaults intentionally mimic Claude-style shell behavior:
	// - default timeout: 2 minutes
	// - maximum timeout cap: 10 minutes
	TerminalExecPolicy *AITerminalExecPolicy `json:"terminal_exec_policy,omitempty"`
}

type AIExecutionPolicy struct {
	// RequireUserApproval controls whether mutating tool invocations require user approval.
	RequireUserApproval bool `json:"require_user_approval"`

	// BlockDangerousCommands controls whether dangerous terminal commands are hard-blocked.
	BlockDangerousCommands bool `json:"block_dangerous_commands"`
}

type AIProvider struct {
	// ID is a stable internal id (primary key). It must not change once used for secrets/model routing.
	ID string `json:"id"`

	// Name is a human-friendly display name (safe to rename at any time).
	Name string `json:"name,omitempty"`

	// Type is one of:
	// - "openai"
	// - "anthropic"
	// - "moonshot"
	// - "chatglm"
	// - "deepseek"
	// - "qwen"
	// - "openai_compatible"
	Type string `json:"type"`

	// BaseURL overrides the provider endpoint (example: "https://api.openai.com/v1").
	// When empty, provider defaults apply.
	//
	// Required provider types:
	// - moonshot
	// - chatglm
	// - deepseek
	// - qwen
	// - openai_compatible
	BaseURL string `json:"base_url,omitempty"`

	// StrictToolSchema overrides provider tool schema strictness.
	//
	// When unset, runtime falls back to built-in policy:
	// - openai official endpoints: strict
	// - openai custom gateways: non-strict
	// - openai_compatible: non-strict
	// - moonshot/chatglm/deepseek/qwen: non-strict
	StrictToolSchema *bool `json:"strict_tool_schema,omitempty"`

	// WebSearch configures optional web search behavior for generic OpenAI-compatible providers.
	//
	// Native providers (OpenAI, Moonshot, ChatGLM/GLM, DeepSeek, and Qwen) derive their web-search
	// behavior from the provider type and explicit model allow-list, so this field is ignored for them.
	WebSearch *AIProviderWebSearch `json:"web_search,omitempty"`

	// Models is the allowed model list for this provider (shown in the Chat UI).
	Models []AIProviderModel `json:"models,omitempty"`
}

type AIProviderModel struct {
	ModelName                     string `json:"model_name"`
	ContextWindow                 int    `json:"context_window,omitempty"`
	MaxOutputTokens               int    `json:"max_output_tokens,omitempty"`
	EffectiveContextWindowPercent int    `json:"effective_context_window_percent,omitempty"`
}

type AIProviderWebSearch struct {
	// Mode is only honored for openai_compatible providers.
	//
	// Supported values:
	// - "disabled": do not expose any web-search capability
	// - "openai_builtin": attach OpenAI Responses-style hosted web search
	// - "brave": expose Flower's external Brave-backed web.search tool
	Mode string `json:"mode,omitempty"`
}

type AITerminalExecPolicy struct {
	// DefaultTimeoutMS is the timeout applied when terminal.exec does not specify timeout_ms.
	DefaultTimeoutMS *int `json:"default_timeout_ms,omitempty"`

	// MaxTimeoutMS is the hard upper cap for any terminal.exec timeout_ms request.
	MaxTimeoutMS *int `json:"max_timeout_ms,omitempty"`
}

type BootstrapArgs struct {
	ControlplaneBaseURL    string
	ControlplaneProviderID string
	EnvironmentID          string
	BootstrapTicket        string
	RuntimeVersion         string

	StateRoot string

	AgentHomeDir string
	Shell        string
	LogFormat    string
	LogLevel     string

	// PermissionPolicyPreset is an optional preset used to write permission_policy into the config.
	// If empty, bootstrap preserves the existing permission_policy when possible, otherwise uses defaults.
	PermissionPolicyPreset string
}

type Config struct {
	ControlplaneBaseURL      string                      `json:"controlplane_base_url"`
	ControlplaneProviderID   string                      `json:"controlplane_provider_id,omitempty"`
	EnvironmentID            string                      `json:"environment_id"`
	LocalEnvironmentPublicID string                      `json:"local_environment_public_id"`
	BindingGeneration        int64                       `json:"binding_generation,omitempty"`
	AgentInstanceID          string                      `json:"agent_instance_id"`
	Direct                   *directv1.DirectConnectInfo `json:"direct"`

	// AI config controls optional native AI assistant features.
	AI *AIConfig `json:"ai,omitempty"`

	// PermissionPolicy is the local permission cap applied on the endpoint.
	// It is designed to limit the effective permissions even if the control-plane grants more.
	PermissionPolicy *PermissionPolicy `json:"permission_policy,omitempty"`

	// AgentHomeDir is the configured filesystem scope for user-facing features.
	// If empty, the runtime picks a safe default (the current user home dir).
	AgentHomeDir string `json:"agent_home_dir,omitempty"`

	// Shell is the shell command used for terminal sessions.
	// If empty, the runtime picks a default (SHELL or /bin/bash).
	Shell string `json:"shell,omitempty"`

	// LogFormat is "json" or "text".
	LogFormat string `json:"log_format,omitempty"`
	// LogLevel is "debug|info|warn|error".
	LogLevel string `json:"log_level,omitempty"`

	// CodeServerPortMin/Max configures the dynamic port range used for code-server processes.
	// If unset/invalid, the runtime uses a safe default range.
	CodeServerPortMin int `json:"code_server_port_min,omitempty"`
	CodeServerPortMax int `json:"code_server_port_max,omitempty"`
}

type LocalEnvironmentBinding struct {
	LocalEnvironmentPublicID string `json:"local_environment_public_id"`
	UserPublicID             string `json:"user_public_id,omitempty"`
	EnvPublicID              string `json:"env_public_id"`
	Generation               int64  `json:"generation"`
	Hostname                 string `json:"hostname,omitempty"`
	OS                       string `json:"os,omitempty"`
	Arch                     string `json:"arch,omitempty"`
	RuntimeVersion           string `json:"runtime_version,omitempty"`
	LastSeenAtUnixMS         int64  `json:"last_seen_at_unix_ms,omitempty"`
}

type PermissionPolicy struct {
	SchemaVersion int `json:"schema_version"`

	// LocalMax is the global cap. It must be present for schema_version=1.
	LocalMax *PermissionSet `json:"local_max"`

	// ByUser and ByApp are optional additional caps. They can only further reduce LocalMax.
	ByUser map[string]*PermissionSet `json:"by_user,omitempty"`
	ByApp  map[string]*PermissionSet `json:"by_app,omitempty"`
}

type PermissionSet struct {
	Read    bool `json:"read"`
	Write   bool `json:"write"`
	Execute bool `json:"execute"`
}

type StateLayout struct {
	StateRoot        string
	ConfigPath       string
	SecretsPath      string
	LockPath         string
	StateDir         string
	RuntimeStatePath string
	DiagnosticsDir   string
	AuditDir         string
	AppsDir          string
	GatewayDir       string
}