types.go

package copilot

import (
	"context"
	"encoding/json"
	"time"

	"github.com/github/copilot-sdk/go/rpc"
)

// connectionState is the internal client connection state.
type connectionState string

const (
	stateDisconnected connectionState = "disconnected"
	stateConnecting   connectionState = "connecting"
	stateConnected    connectionState = "connected"
	stateError        connectionState = "error"
)

// RuntimeConnection describes how a [Client] connects to the Copilot runtime.
//
// Construct one with a [StdioConnection], [TcpConnection], or [UriConnection]
// literal and pass it via [ClientOptions.Connection]. When [ClientOptions.Connection]
// is nil, the default is an empty [StdioConnection] (the SDK spawns the bundled
// runtime and communicates over stdin/stdout).
type RuntimeConnection interface {
	runtimeConnection()
}

// StdioConnection spawns a runtime child process and communicates over its
// stdin/stdout pipes. This is the default when no connection is configured.
type StdioConnection struct {
	// Path is the runtime executable. When empty, the bundled runtime is used.
	Path string
	// Args are extra command-line arguments inserted before SDK-managed args.
	Args []string
}

func (StdioConnection) runtimeConnection() {}

// TcpConnection spawns a runtime child process that listens on a TCP socket
// and connects to it.
type TcpConnection struct {
	// Port is the TCP port the runtime listens on. 0 (the default) lets the
	// runtime pick a free port; the chosen port is then available via
	// [Client.RuntimePort] after [Client.Start] returns.
	Port int
	// ConnectionToken is an optional shared secret sent in the `connect`
	// handshake. When empty, a UUID is generated automatically so the
	// loopback listener is safe by default.
	ConnectionToken string
	// Path is the runtime executable. When empty, the bundled runtime is used.
	Path string
	// Args are extra command-line arguments inserted before SDK-managed args.
	Args []string
}

func (TcpConnection) runtimeConnection() {}

// UriConnection connects to an already-running runtime at the given URL.
// The SDK does not spawn a process in this mode.
type UriConnection struct {
	// URL of the runtime. Accepts "port", "host:port", or a full URL such
	// as "http://host:port".
	URL string
	// ConnectionToken authenticates the connection; must match what the
	// remote runtime expects.
	ConnectionToken string
}

func (UriConnection) runtimeConnection() {}

// ClientOptions configures the [Client].
type ClientOptions struct {
	// Connection describes how to connect to the Copilot runtime. When nil,
	// defaults to an empty [StdioConnection] (spawn the bundled runtime over
	// stdio).
	Connection RuntimeConnection
	// WorkingDirectory is the working directory for the runtime process.
	// If empty, inherits the current process's working directory.
	WorkingDirectory string
	// BaseDirectory is the base directory for Copilot data (session state,
	// config, etc.). Sets the COPILOT_HOME environment variable on the
	// spawned runtime. When empty, the runtime defaults to ~/.copilot.
	// This does not affect where the Go SDK extracts the embedded CLI
	// binary; use embeddedcli.Config.Dir to control that install/cache
	// location.
	// Ignored when connecting to an existing runtime via [UriConnection].
	BaseDirectory string
	// LogLevel for the runtime. When empty (the default), the runtime
	// uses its own default level; the SDK does not pass --log-level.
	// Recognized values: "none", "error", "warning", "info", "debug", "all".
	LogLevel string
	// Env are the environment variables for the runtime process (default:
	// inherits from current process). Each entry is of the form "KEY=VALUE".
	// If Env contains duplicate keys, only the last value for each key is used.
	Env []string
	// GitHubToken is the GitHub token to use for authentication.
	// When provided, the token is passed to the runtime via environment
	// variable. This takes priority over other authentication methods.
	GitHubToken string
	// UseLoggedInUser controls whether to use the logged-in user for
	// authentication. When true, the runtime attempts to use stored OAuth
	// tokens or gh CLI auth. When false, only explicit tokens (GitHubToken
	// or environment variables) are used.
	// Default: true (but defaults to false when GitHubToken is provided).
	UseLoggedInUser *bool
	// OnListModels is a custom handler for listing available models.
	// When provided, [Client.ListModels] calls this handler instead of
	// querying the runtime. Useful in BYOK mode to return models available
	// from your custom provider.
	OnListModels func(ctx context.Context) ([]ModelInfo, error)
	// SessionFs configures a custom session filesystem provider.
	// When provided, the client registers as the session filesystem provider
	// on connection, routing session-scoped file I/O through per-session
	// handlers.
	SessionFs *SessionFsConfig
	// Telemetry configures OpenTelemetry integration for the runtime.
	// When non-nil, COPILOT_OTEL_ENABLED=true is set and any populated
	// fields are mapped to the corresponding environment variables.
	Telemetry *TelemetryConfig
	// SessionIdleTimeoutSeconds configures the server-wide session idle
	// timeout in seconds. Sessions without activity for this duration are
	// automatically cleaned up. Set to 0 or leave unset to disable.
	// Ignored when connecting to an existing runtime via [UriConnection].
	SessionIdleTimeoutSeconds int
	// EnableRemoteSessions enables remote session support (Mission Control
	// integration). When true, sessions in a GitHub repository working
	// directory are accessible from GitHub web and mobile.
	// Ignored when connecting to an existing runtime via [UriConnection].
	EnableRemoteSessions bool
}

// CloudSessionRepository is GitHub repository metadata associated with a cloud session.
type CloudSessionRepository struct {
	Owner  string `json:"owner"`
	Name   string `json:"name"`
	Branch string `json:"branch,omitempty"`
}

// CloudSessionOptions configures creation of a remote session in the cloud.
type CloudSessionOptions struct {
	Repository *CloudSessionRepository `json:"repository,omitempty"`
}

// TelemetryConfig configures OpenTelemetry integration for the Copilot CLI process.
type TelemetryConfig struct {
	// OTLPEndpoint is the OTLP HTTP endpoint URL for trace/metric export.
	// Sets OTEL_EXPORTER_OTLP_ENDPOINT.
	OTLPEndpoint string

	// FilePath is the file path for JSON-lines trace output.
	// Sets COPILOT_OTEL_FILE_EXPORTER_PATH.
	FilePath string

	// ExporterType is the exporter backend type: "otlp-http" or "file".
	// Sets COPILOT_OTEL_EXPORTER_TYPE.
	ExporterType string

	// SourceName is the instrumentation scope name.
	// Sets COPILOT_OTEL_SOURCE_NAME.
	SourceName string

	// CaptureContent controls whether to capture message content (prompts, responses).
	// Sets OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT.
	CaptureContent *bool
}

// Bool returns a pointer to the given bool value.
// Use for option fields such as AutoStart, AutoRestart, or LogOptions.Ephemeral:
//
//	AutoStart: Bool(false)
//	Ephemeral: Bool(true)
func Bool(v bool) *bool {
	return &v
}

// String returns a pointer to the given string value.
// Use for setting optional string parameters in RPC calls.
func String(v string) *string {
	return &v
}

// Float64 returns a pointer to the given float64 value.
// Use for setting thresholds: BackgroundCompactionThreshold: Float64(0.80)
func Float64(v float64) *float64 {
	return &v
}

// Int returns a pointer to the given int value.
// Use for setting optional int parameters: MinLength: Int(1)
func Int(v int) *int {
	return &v
}

// Known system message section identifiers for the "customize" mode.
const (
	// SectionIdentity is the agent identity preamble and mode statement.
	SectionIdentity = "identity"
	// SectionTone covers response style, conciseness rules, and output formatting preferences.
	SectionTone = "tone"
	// SectionToolEfficiency covers tool usage patterns, parallel calling, and batching guidelines.
	SectionToolEfficiency = "tool_efficiency"
	// SectionEnvironmentContext covers CWD, OS, git root, directory listing, and available tools.
	SectionEnvironmentContext = "environment_context"
	// SectionCodeChangeRules covers coding rules, linting/testing, ecosystem tools, and style.
	SectionCodeChangeRules = "code_change_rules"
	// SectionGuidelines covers tips, behavioral best practices, and behavioral guidelines.
	SectionGuidelines = "guidelines"
	// SectionSafety covers environment limitations, prohibited actions, and security policies.
	SectionSafety = "safety"
	// SectionToolInstructions covers per-tool usage instructions.
	SectionToolInstructions = "tool_instructions"
	// SectionCustomInstructions covers repository and organization custom instructions.
	SectionCustomInstructions = "custom_instructions"
	// SectionRuntimeInstructions targets runtime-provided context and instructions
	// (e.g. system notifications, memories, workspace context, mode-specific instructions,
	// content-exclusion policy).
	SectionRuntimeInstructions = "runtime_instructions"
	// SectionLastInstructions covers end-of-prompt instructions: parallel tool calling,
	// persistence, and task completion.
	SectionLastInstructions = "last_instructions"
)

// SectionOverrideAction represents the action to perform on a system message section.
type SectionOverrideAction string

const (
	// SectionActionReplace replaces section content entirely.
	SectionActionReplace SectionOverrideAction = "replace"
	// SectionActionRemove removes the section.
	SectionActionRemove SectionOverrideAction = "remove"
	// SectionActionAppend appends to existing section content.
	SectionActionAppend SectionOverrideAction = "append"
	// SectionActionPrepend prepends to existing section content.
	SectionActionPrepend SectionOverrideAction = "prepend"
)

// SectionTransformFn is a callback that receives the current content of a system message section
// and returns the transformed content. Used with the "transform" action to read-then-write
// modify sections at runtime.
type SectionTransformFn func(currentContent string) (string, error)

// SectionOverride defines an override operation for a single system message section.
type SectionOverride struct {
	// Action is the operation to perform: "replace", "remove", "append", "prepend", or "transform".
	Action SectionOverrideAction `json:"action,omitempty"`
	// Content for the override. Optional for all actions. Ignored for "remove".
	Content string `json:"content,omitempty"`
	// Transform is a callback invoked when Action is "transform".
	// The runtime calls this with the current section content and uses the returned string.
	// Excluded from JSON serialization; the SDK registers it as an RPC callback internally.
	Transform SectionTransformFn `json:"-"`
}

// SystemMessageAppendConfig is append mode: use CLI foundation with optional appended content.
type SystemMessageAppendConfig struct {
	// Mode is optional, defaults to "append"
	Mode string `json:"mode,omitempty"`
	// Content provides additional instructions appended after SDK-managed sections
	Content string `json:"content,omitempty"`
}

// SystemMessageReplaceConfig is replace mode: use caller-provided system message entirely.
// Removes all SDK guardrails including security restrictions.
type SystemMessageReplaceConfig struct {
	// Mode must be "replace"
	Mode string `json:"mode"`
	// Content is the complete system message (required)
	Content string `json:"content"`
}

// SystemMessageConfig represents system message configuration for session creation.
//   - Append mode (default): SDK foundation + optional custom content
//   - Replace mode: Full control, caller provides entire system message
//   - Customize mode: Section-level overrides with graceful fallback
//
// In Go, use one struct and set fields appropriate for the desired mode.
type SystemMessageConfig struct {
	Mode     string                     `json:"mode,omitempty"`
	Content  string                     `json:"content,omitempty"`
	Sections map[string]SectionOverride `json:"sections,omitempty"`
}

// PermissionHandlerFunc executes a permission request.
// The handler should return a [rpc.PermissionDecision]. Returning an error
// causes the SDK to respond with [rpc.PermissionDecisionUserNotAvailable].
//
// Use the variant types directly:
//
//	&rpc.PermissionDecisionApproveOnce{}
//	&rpc.PermissionDecisionReject{Feedback: &feedback}
//	&rpc.PermissionDecisionUserNotAvailable{}
//	&rpc.PermissionDecisionNoResult{}  // decline to respond; another client may answer
type PermissionHandlerFunc func(request PermissionRequest, invocation PermissionInvocation) (rpc.PermissionDecision, error)

// PermissionInvocation provides context about a permission request
type PermissionInvocation struct {
	SessionID string
}

// UserInputRequest represents a request for user input from the agent
type UserInputRequest struct {
	Question      string
	Choices       []string
	AllowFreeform *bool
}

// UserInputResponse represents the user's response to an input request
type UserInputResponse struct {
	Answer      string
	WasFreeform bool
}

// UserInputHandler handles user input requests from the agent
// The handler should return a UserInputResponse. Returning an error fails the request.
type UserInputHandler func(request UserInputRequest, invocation UserInputInvocation) (UserInputResponse, error)

// UserInputInvocation provides context about a user input request
type UserInputInvocation struct {
	SessionID string
}

// ExitPlanModeRequest represents a request to exit plan mode and continue with a selected action.
type ExitPlanModeRequest struct {
	Summary           string   `json:"summary"`
	PlanContent       string   `json:"planContent,omitempty"`
	Actions           []string `json:"actions"`
	RecommendedAction string   `json:"recommendedAction"`
}

// ExitPlanModeResult is the response to an exit-plan-mode request.
type ExitPlanModeResult struct {
	Approved       bool   `json:"approved"`
	SelectedAction string `json:"selectedAction,omitempty"`
	Feedback       string `json:"feedback,omitempty"`
}

// ExitPlanModeInvocation provides context about an exit-plan-mode request.
type ExitPlanModeInvocation struct {
	SessionID string
}

// ExitPlanModeRequestHandler handles exit-plan-mode requests from the agent.
type ExitPlanModeRequestHandler func(request ExitPlanModeRequest, invocation ExitPlanModeInvocation) (ExitPlanModeResult, error)

// AutoModeSwitchRequest represents a request to switch to auto mode after an eligible rate limit.
type AutoModeSwitchRequest struct {
	ErrorCode         *string  `json:"errorCode,omitempty"`
	RetryAfterSeconds *float64 `json:"retryAfterSeconds,omitempty"`
}

// AutoModeSwitchInvocation provides context about an auto-mode-switch request.
type AutoModeSwitchInvocation struct {
	SessionID string
}

// AutoModeSwitchRequestHandler handles auto-mode-switch requests from the agent.
type AutoModeSwitchRequestHandler func(request AutoModeSwitchRequest, invocation AutoModeSwitchInvocation) (AutoModeSwitchResponse, error)

// PreToolUseHookInput is the input for a pre-tool-use hook
type PreToolUseHookInput struct {
	SessionID        string    `json:"sessionId"`
	Timestamp        time.Time `json:"-"`
	WorkingDirectory string    `json:"cwd"`
	ToolName         string    `json:"toolName"`
	ToolArgs         any       `json:"toolArgs"`
}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.
func (h PreToolUseHookInput) MarshalJSON() ([]byte, error) {
	type alias PreToolUseHookInput
	return json.Marshal(&struct {
		Timestamp int64 `json:"timestamp"`
		alias
	}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})
}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.
func (h *PreToolUseHookInput) UnmarshalJSON(data []byte) error {
	type alias PreToolUseHookInput
	aux := &struct {
		Timestamp int64 `json:"timestamp"`
		*alias
	}{alias: (*alias)(h)}
	if err := json.Unmarshal(data, aux); err != nil {
		return err
	}
	h.Timestamp = time.UnixMilli(aux.Timestamp)
	return nil
}

// PreToolUseHookOutput is the output for a pre-tool-use hook
type PreToolUseHookOutput struct {
	PermissionDecision       string `json:"permissionDecision,omitempty"` // "allow", "deny", "ask"
	PermissionDecisionReason string `json:"permissionDecisionReason,omitempty"`
	ModifiedArgs             any    `json:"modifiedArgs,omitempty"`
	AdditionalContext        string `json:"additionalContext,omitempty"`
	SuppressOutput           bool   `json:"suppressOutput,omitempty"`
}

// PreToolUseHandler handles pre-tool-use hook invocations
type PreToolUseHandler func(input PreToolUseHookInput, invocation HookInvocation) (*PreToolUseHookOutput, error)

// PostToolUseHookInput is the input for a post-tool-use hook
type PostToolUseHookInput struct {
	SessionID        string    `json:"sessionId"`
	Timestamp        time.Time `json:"-"`
	WorkingDirectory string    `json:"cwd"`
	ToolName         string    `json:"toolName"`
	ToolArgs         any       `json:"toolArgs"`
	ToolResult       any       `json:"toolResult"`
}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.
func (h PostToolUseHookInput) MarshalJSON() ([]byte, error) {
	type alias PostToolUseHookInput
	return json.Marshal(&struct {
		Timestamp int64 `json:"timestamp"`
		alias
	}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})
}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.
func (h *PostToolUseHookInput) UnmarshalJSON(data []byte) error {
	type alias PostToolUseHookInput
	aux := &struct {
		Timestamp int64 `json:"timestamp"`
		*alias
	}{alias: (*alias)(h)}
	if err := json.Unmarshal(data, aux); err != nil {
		return err
	}
	h.Timestamp = time.UnixMilli(aux.Timestamp)
	return nil
}

// PostToolUseHookOutput is the output for a post-tool-use hook
type PostToolUseHookOutput struct {
	ModifiedResult    any    `json:"modifiedResult,omitempty"`
	AdditionalContext string `json:"additionalContext,omitempty"`
	SuppressOutput    bool   `json:"suppressOutput,omitempty"`
}

// PostToolUseHandler handles post-tool-use hook invocations
type PostToolUseHandler func(input PostToolUseHookInput, invocation HookInvocation) (*PostToolUseHookOutput, error)

// PostToolUseFailureHookInput is the input for a post-tool-use-failure hook.
//
// Fires after a tool execution whose result was "failure". The CLI extracts
// the failure message from the tool result and passes it as the Error field
// (rather than passing the full result object).
type PostToolUseFailureHookInput struct {
	SessionID        string    `json:"sessionId"`
	Timestamp        time.Time `json:"-"`
	WorkingDirectory string    `json:"cwd"`
	ToolName         string    `json:"toolName"`
	ToolArgs         any       `json:"toolArgs"`
	// Error is the failure message from the tool's result.
	Error string `json:"error"`
}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.
func (h PostToolUseFailureHookInput) MarshalJSON() ([]byte, error) {
	type alias PostToolUseFailureHookInput
	return json.Marshal(&struct {
		Timestamp int64 `json:"timestamp"`
		alias
	}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})
}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.
func (h *PostToolUseFailureHookInput) UnmarshalJSON(data []byte) error {
	type alias PostToolUseFailureHookInput
	aux := &struct {
		Timestamp int64 `json:"timestamp"`
		*alias
	}{alias: (*alias)(h)}
	if err := json.Unmarshal(data, aux); err != nil {
		return err
	}
	h.Timestamp = time.UnixMilli(aux.Timestamp)
	return nil
}

// PostToolUseFailureHookOutput is the output for a post-tool-use-failure hook.
//
// Only AdditionalContext is consumed by the host CLI — it is appended as
// hidden guidance to the model alongside the failed tool result.
type PostToolUseFailureHookOutput struct {
	AdditionalContext string `json:"additionalContext,omitempty"`
}

// PostToolUseFailureHandler handles post-tool-use-failure hook invocations.
type PostToolUseFailureHandler func(input PostToolUseFailureHookInput, invocation HookInvocation) (*PostToolUseFailureHookOutput, error)

// UserPromptSubmittedHookInput is the input for a user-prompt-submitted hook
type UserPromptSubmittedHookInput struct {
	SessionID        string    `json:"sessionId"`
	Timestamp        time.Time `json:"-"`
	WorkingDirectory string    `json:"cwd"`
	Prompt           string    `json:"prompt"`
}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.
func (h UserPromptSubmittedHookInput) MarshalJSON() ([]byte, error) {
	type alias UserPromptSubmittedHookInput
	return json.Marshal(&struct {
		Timestamp int64 `json:"timestamp"`
		alias
	}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})
}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.
func (h *UserPromptSubmittedHookInput) UnmarshalJSON(data []byte) error {
	type alias UserPromptSubmittedHookInput
	aux := &struct {
		Timestamp int64 `json:"timestamp"`
		*alias
	}{alias: (*alias)(h)}
	if err := json.Unmarshal(data, aux); err != nil {
		return err
	}
	h.Timestamp = time.UnixMilli(aux.Timestamp)
	return nil
}

// UserPromptSubmittedHookOutput is the output for a user-prompt-submitted hook
type UserPromptSubmittedHookOutput struct {
	ModifiedPrompt    string `json:"modifiedPrompt,omitempty"`
	AdditionalContext string `json:"additionalContext,omitempty"`
	SuppressOutput    bool   `json:"suppressOutput,omitempty"`
}

// UserPromptSubmittedHandler handles user-prompt-submitted hook invocations
type UserPromptSubmittedHandler func(input UserPromptSubmittedHookInput, invocation HookInvocation) (*UserPromptSubmittedHookOutput, error)

// SessionStartHookInput is the input for a session-start hook
type SessionStartHookInput struct {
	SessionID        string    `json:"sessionId"`
	Timestamp        time.Time `json:"-"`
	WorkingDirectory string    `json:"cwd"`
	Source           string    `json:"source"` // "startup", "resume", "new"
	InitialPrompt    string    `json:"initialPrompt,omitempty"`
}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.
func (h SessionStartHookInput) MarshalJSON() ([]byte, error) {
	type alias SessionStartHookInput
	return json.Marshal(&struct {
		Timestamp int64 `json:"timestamp"`
		alias
	}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})
}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.
func (h *SessionStartHookInput) UnmarshalJSON(data []byte) error {
	type alias SessionStartHookInput
	aux := &struct {
		Timestamp int64 `json:"timestamp"`
		*alias
	}{alias: (*alias)(h)}
	if err := json.Unmarshal(data, aux); err != nil {
		return err
	}
	h.Timestamp = time.UnixMilli(aux.Timestamp)
	return nil
}

// SessionStartHookOutput is the output for a session-start hook
type SessionStartHookOutput struct {
	AdditionalContext string         `json:"additionalContext,omitempty"`
	ModifiedConfig    map[string]any `json:"modifiedConfig,omitempty"`
}

// SessionStartHandler handles session-start hook invocations
type SessionStartHandler func(input SessionStartHookInput, invocation HookInvocation) (*SessionStartHookOutput, error)

// SessionEndHookInput is the input for a session-end hook
type SessionEndHookInput struct {
	SessionID        string    `json:"sessionId"`
	Timestamp        time.Time `json:"-"`
	WorkingDirectory string    `json:"cwd"`
	Reason           string    `json:"reason"` // "complete", "error", "abort", "timeout", "user_exit"
	FinalMessage     string    `json:"finalMessage,omitempty"`
	Error            string    `json:"error,omitempty"`
}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.
func (h SessionEndHookInput) MarshalJSON() ([]byte, error) {
	type alias SessionEndHookInput
	return json.Marshal(&struct {
		Timestamp int64 `json:"timestamp"`
		alias
	}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})
}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.
func (h *SessionEndHookInput) UnmarshalJSON(data []byte) error {
	type alias SessionEndHookInput
	aux := &struct {
		Timestamp int64 `json:"timestamp"`
		*alias
	}{alias: (*alias)(h)}
	if err := json.Unmarshal(data, aux); err != nil {
		return err
	}
	h.Timestamp = time.UnixMilli(aux.Timestamp)
	return nil
}

// SessionEndHookOutput is the output for a session-end hook
type SessionEndHookOutput struct {
	SuppressOutput bool     `json:"suppressOutput,omitempty"`
	CleanupActions []string `json:"cleanupActions,omitempty"`
	SessionSummary string   `json:"sessionSummary,omitempty"`
}

// SessionEndHandler handles session-end hook invocations
type SessionEndHandler func(input SessionEndHookInput, invocation HookInvocation) (*SessionEndHookOutput, error)

// ErrorOccurredHookInput is the input for an error-occurred hook
type ErrorOccurredHookInput struct {
	SessionID        string    `json:"sessionId"`
	Timestamp        time.Time `json:"-"`
	WorkingDirectory string    `json:"cwd"`
	Error            string    `json:"error"`
	ErrorContext     string    `json:"errorContext"` // "model_call", "tool_execution", "system", "user_input"
	Recoverable      bool      `json:"recoverable"`
}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.
func (h ErrorOccurredHookInput) MarshalJSON() ([]byte, error) {
	type alias ErrorOccurredHookInput
	return json.Marshal(&struct {
		Timestamp int64 `json:"timestamp"`
		alias
	}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})
}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.
func (h *ErrorOccurredHookInput) UnmarshalJSON(data []byte) error {
	type alias ErrorOccurredHookInput
	aux := &struct {
		Timestamp int64 `json:"timestamp"`
		*alias
	}{alias: (*alias)(h)}
	if err := json.Unmarshal(data, aux); err != nil {
		return err
	}
	h.Timestamp = time.UnixMilli(aux.Timestamp)
	return nil
}

// ErrorOccurredHookOutput is the output for an error-occurred hook
type ErrorOccurredHookOutput struct {
	SuppressOutput   bool   `json:"suppressOutput,omitempty"`
	ErrorHandling    string `json:"errorHandling,omitempty"` // "retry", "skip", "abort"
	RetryCount       int    `json:"retryCount,omitempty"`
	UserNotification string `json:"userNotification,omitempty"`
}

// ErrorOccurredHandler handles error-occurred hook invocations
type ErrorOccurredHandler func(input ErrorOccurredHookInput, invocation HookInvocation) (*ErrorOccurredHookOutput, error)

// PreMcpToolCallHookInput is the input for a pre-mcp-tool-call hook
type PreMcpToolCallHookInput struct {
	SessionID        string    `json:"sessionId"`
	Timestamp        time.Time `json:"-"`
	WorkingDirectory string    `json:"cwd"`
	ServerName       string    `json:"serverName"`
	ToolName         string    `json:"toolName"`
	Arguments        any       `json:"arguments,omitempty"`
	ToolCallID       string    `json:"toolCallId,omitempty"`
	Meta             any       `json:"_meta,omitempty"`
}

// MarshalJSON implements json.Marshaler, emitting Timestamp as Unix milliseconds.
func (h PreMcpToolCallHookInput) MarshalJSON() ([]byte, error) {
	type alias PreMcpToolCallHookInput
	return json.Marshal(&struct {
		Timestamp int64 `json:"timestamp"`
		alias
	}{Timestamp: h.Timestamp.UnixMilli(), alias: alias(h)})
}

// UnmarshalJSON implements json.Unmarshaler, parsing Timestamp from Unix milliseconds.
func (h *PreMcpToolCallHookInput) UnmarshalJSON(data []byte) error {
	type alias PreMcpToolCallHookInput
	aux := &struct {
		Timestamp int64 `json:"timestamp"`
		*alias
	}{alias: (*alias)(h)}
	if err := json.Unmarshal(data, aux); err != nil {
		return err
	}
	h.Timestamp = time.UnixMilli(aux.Timestamp)
	return nil
}

// PreMcpToolCallHookOutput is the output for a pre-mcp-tool-call hook
type PreMcpToolCallHookOutput struct {
	MetaToUse any `json:"metaToUse"`
}

// PreMcpToolCallHandler handles pre-mcp-tool-call hook invocations
type PreMcpToolCallHandler func(input PreMcpToolCallHookInput, invocation HookInvocation) (*PreMcpToolCallHookOutput, error)

// HookInvocation provides context about a hook invocation
type HookInvocation struct {
	SessionID string
}

// SessionHooks configures hook handlers for a session
type SessionHooks struct {
	OnPreToolUse          PreToolUseHandler
	OnPostToolUse         PostToolUseHandler
	OnPostToolUseFailure  PostToolUseFailureHandler
	OnUserPromptSubmitted UserPromptSubmittedHandler
	OnSessionStart        SessionStartHandler
	OnSessionEnd          SessionEndHandler
	OnErrorOccurred       ErrorOccurredHandler
	OnPreMcpToolCall      PreMcpToolCallHandler
}

// MCPServerConfig is implemented by MCP server configuration types.
// Only MCPStdioServerConfig and MCPHTTPServerConfig implement this interface.
type MCPServerConfig interface {
	mcpServerConfig()
}

// MCPStdioServerConfig configures a local/stdio MCP server.
//
// The Tools field controls which tools from the server are exposed:
//   - nil (omitted from the wire): all tools (CLI default)
//   - &[]string{"*"}: explicit "all tools"
//   - &[]string{}: no tools
//   - &[]string{"foo","bar"}: only those tools
//
// The pointer-to-slice form is required so that a nil pointer (omitted from
// the wire) is distinguishable from a non-nil pointer to an empty slice
// (sent as `"tools": []`).
type MCPStdioServerConfig struct {
	Tools            *[]string         `json:"tools,omitempty"`
	Timeout          int               `json:"timeout,omitempty"`
	Command          string            `json:"command"`
	Args             []string          `json:"args,omitempty"`
	Env              map[string]string `json:"env,omitempty"`
	WorkingDirectory string            `json:"cwd,omitempty"`
}

func (MCPStdioServerConfig) mcpServerConfig() {}

// MarshalJSON implements json.Marshaler, injecting the "type" discriminator.
func (c MCPStdioServerConfig) MarshalJSON() ([]byte, error) {
	type alias MCPStdioServerConfig
	return json.Marshal(struct {
		Type string `json:"type"`
		alias
	}{
		Type:  "stdio",
		alias: alias(c),
	})
}

// MCPHTTPServerConfig configures a remote MCP server (HTTP or SSE).
//
// See [MCPStdioServerConfig] for the semantics of the Tools field.
type MCPHTTPServerConfig struct {
	Tools   *[]string         `json:"tools,omitempty"`
	Timeout int               `json:"timeout,omitempty"`
	URL     string            `json:"url"`
	Headers map[string]string `json:"headers,omitempty"`
}

func (MCPHTTPServerConfig) mcpServerConfig() {}

// MarshalJSON implements json.Marshaler, injecting the "type" discriminator.
func (c MCPHTTPServerConfig) MarshalJSON() ([]byte, error) {
	type alias MCPHTTPServerConfig
	return json.Marshal(struct {
		Type string `json:"type"`
		alias
	}{
		Type:  "http",
		alias: alias(c),
	})
}

// CustomAgentConfig configures a custom agent
type CustomAgentConfig struct {
	// Name is the unique name of the custom agent
	Name string `json:"name"`
	// DisplayName is the display name for UI purposes
	DisplayName string `json:"displayName,omitempty"`
	// Description of what the agent does
	Description string `json:"description,omitempty"`
	// Tools is the list of tool names the agent can use (nil for all tools)
	Tools []string `json:"tools,omitempty"`
	// Prompt is the prompt content for the agent
	Prompt string `json:"prompt"`
	// MCPServers are MCP servers specific to this agent
	MCPServers map[string]MCPServerConfig `json:"mcpServers,omitempty"`
	// Infer indicates whether the agent should be available for model inference
	Infer *bool `json:"infer,omitempty"`
	// Skills is the list of skill names to preload into this agent's context at startup (opt-in; omit for none)
	Skills []string `json:"skills,omitempty"`
	// Model is the model identifier for this agent (e.g. "claude-haiku-4.5").
	// When set, the runtime will attempt to use this model for the agent,
	// falling back to the parent session model if unavailable.
	Model string `json:"model,omitempty"`
}

// DefaultAgentConfig configures the default agent (the built-in agent that handles turns when no custom agent is selected).
// Use ExcludedTools to hide specific tools from the default agent while keeping
// them available to custom sub-agents.
type DefaultAgentConfig struct {
	// ExcludedTools is a list of tool names to exclude from the default agent.
	// These tools remain available to custom sub-agents that reference them in their Tools list.
	ExcludedTools []string `json:"excludedTools,omitempty"`
}

// InfiniteSessionConfig configures infinite sessions with automatic context compaction
// and workspace persistence. When enabled, sessions automatically manage context window
// limits through background compaction and persist state to a workspace directory.
type InfiniteSessionConfig struct {
	// Enabled controls whether infinite sessions are enabled (default: true)
	Enabled *bool `json:"enabled,omitempty"`
	// BackgroundCompactionThreshold is the context utilization (0.0-1.0) at which
	// background compaction starts. Default: 0.80
	BackgroundCompactionThreshold *float64 `json:"backgroundCompactionThreshold,omitempty"`
	// BufferExhaustionThreshold is the context utilization (0.0-1.0) at which
	// the session blocks until compaction completes. Default: 0.95
	BufferExhaustionThreshold *float64 `json:"bufferExhaustionThreshold,omitempty"`
}

// SessionFsCapabilities declares optional provider capabilities.
type SessionFsCapabilities struct {
	// Sqlite indicates whether the provider supports SQLite query/exists operations.
	Sqlite bool
}

// SessionFsConfig configures a custom session filesystem provider.
type SessionFsConfig struct {
	// InitialWorkingDirectory is the initial working directory for sessions.
	InitialWorkingDirectory string
	// SessionStatePath is the path within each session's filesystem where the runtime stores
	// session-scoped files such as events, checkpoints, and temp files.
	SessionStatePath string
	// Conventions identifies the path conventions used by this filesystem provider.
	Conventions rpc.SessionFsSetProviderConventions
	// Capabilities declares optional provider capabilities such as SQLite support.
	Capabilities *SessionFsCapabilities
}

// SessionConfig configures a new session
type SessionConfig struct {
	// SessionID is an optional custom session ID
	SessionID string
	// ClientName identifies the application using the SDK.
	// Included in the User-Agent header for API requests.
	ClientName string
	// Model to use for this session
	Model string
	// ReasoningEffort level for models that support it.
	// Valid values: "low", "medium", "high", "xhigh"
	// Only applies to models where capabilities.supports.reasoningEffort is true.
	ReasoningEffort string
	// ConfigDir overrides the default configuration directory location.
	// When specified, the session will use this directory for storing config and state.
	ConfigDir string
	// EnableConfigDiscovery, when true, automatically discovers MCP server configurations
	// (e.g. .mcp.json, .vscode/mcp.json) and skill directories from the working directory
	// and merges them with any explicitly provided MCPServers and SkillDirectories, with
	// explicit values taking precedence on name collision.
	// Custom instruction files (.github/copilot-instructions.md, AGENTS.md, etc.) are
	// always loaded from the working directory regardless of this setting.
	EnableConfigDiscovery bool
	// Tools exposes caller-implemented tools to the CLI. A Tool with a nil Handler
	// is declaration-only; the consumer must resolve its calls via pending tool RPCs.
	Tools []Tool
	// SystemMessage configures system message customization
	SystemMessage *SystemMessageConfig
	// AvailableTools is a list of tool names to allow. When specified, only these tools will be available.
	// Takes precedence over ExcludedTools.
	AvailableTools []string
	// ExcludedTools is a list of tool names to disable. All other tools remain available.
	// Ignored if AvailableTools is specified.
	ExcludedTools []string
	// OnPermissionRequest is an optional handler for permission requests from the server.
	// When nil, permission requests are surfaced as events and left pending for the
	// consumer to resolve via pending permission RPCs.
	OnPermissionRequest PermissionHandlerFunc
	// OnUserInputRequest is a handler for user input requests from the agent (enables ask_user tool)
	OnUserInputRequest UserInputHandler
	// Hooks configures hook handlers for session lifecycle events
	Hooks *SessionHooks
	// WorkingDirectory is the working directory for the session.
	// Tool operations will be relative to this directory.
	WorkingDirectory string
	// Streaming enables streaming of assistant message and reasoning chunks.
	// When non-nil and true, assistant.message_delta and assistant.reasoning_delta
	// events with deltaContent are sent as the response is generated.
	// When nil, the runtime decides (currently defaults to non-streaming).
	Streaming *bool
	// IncludeSubAgentStreamingEvents includes sub-agent streaming events in the
	// event stream. When true, streaming delta events from sub-agents (e.g.,
	// assistant.message_delta, assistant.reasoning_delta, assistant.streaming_delta
	// with agentId set) are forwarded to this connection. When false, only
	// non-streaming sub-agent events and subagent.* lifecycle events are forwarded;
	// streaming deltas from sub-agents are suppressed. When nil, defaults to true.
	IncludeSubAgentStreamingEvents *bool
	// Provider configures a custom model provider (BYOK)
	Provider *ProviderConfig
	// EnableSessionTelemetry enables or disables internal session telemetry for this session.
	// When false, disables session telemetry. When nil (the default) or true,
	// telemetry is enabled for GitHub-authenticated sessions. When a custom
	// Provider (BYOK) is configured, session telemetry is always disabled
	// regardless of this setting. This is independent of the OpenTelemetry
	// configuration in ClientOptions.Telemetry.
	EnableSessionTelemetry *bool
	// ModelCapabilities overrides individual model capabilities resolved by the runtime.
	// Only non-nil fields are applied over the runtime-resolved capabilities.
	ModelCapabilities *rpc.ModelCapabilitiesOverride
	// MCPServers configures MCP servers for the session
	MCPServers map[string]MCPServerConfig
	// CustomAgents configures custom agents for the session
	CustomAgents []CustomAgentConfig
	// DefaultAgent configures the default agent (the built-in agent that handles turns when no custom agent is selected).
	// Use ExcludedTools to hide tools from the default agent while keeping them available to sub-agents.
	DefaultAgent *DefaultAgentConfig
	// Agent is the name of the custom agent to activate when the session starts.
	// Must match the Name of one of the agents in CustomAgents.
	Agent string
	// SkillDirectories is a list of directories to load skills from
	SkillDirectories []string
	// InstructionDirectories is a list of additional directories to search for custom instruction files
	InstructionDirectories []string
	// DisabledSkills is a list of skill names to disable
	DisabledSkills []string
	// InfiniteSessions configures infinite sessions for persistent workspaces and automatic compaction.
	// When enabled (default), sessions automatically manage context limits and persist state.
	InfiniteSessions *InfiniteSessionConfig
	// OnEvent is an optional event handler that is registered on the session before
	// the session.create RPC is issued. This guarantees that early events emitted
	// by the CLI during session creation (e.g. session.start) are delivered to the
	// handler. Equivalent to calling session.On(handler) immediately after creation,
	// but executes earlier in the lifecycle so no events are missed.
	OnEvent SessionEventHandler
	// CreateSessionFsProvider supplies a handler for session filesystem operations.
	// This takes effect only when ClientOptions.SessionFs is configured.
	CreateSessionFsProvider func(session *Session) SessionFsProvider
	// Commands registers slash-commands for this session. Each command appears as
	// /name in the CLI TUI for the user to invoke. The Handler is called when the
	// command is executed.
	Commands []CommandDefinition
	// OnElicitationRequest is a handler for elicitation requests from the server.
	// When provided, the server may call back to this client for form-based UI dialogs
	// (e.g. from MCP tools). Also enables the elicitation capability on the session.
	OnElicitationRequest ElicitationHandler
	// OnExitPlanModeRequest is a handler for exit-plan-mode requests from the server.
	// When provided, enables exitPlanMode.request callbacks for the session.
	OnExitPlanModeRequest ExitPlanModeRequestHandler
	// OnAutoModeSwitchRequest is a handler for auto-mode-switch requests from the server.
	// When provided, enables autoModeSwitch.request callbacks for the session.
	OnAutoModeSwitchRequest AutoModeSwitchRequestHandler
	// GitHubToken is an optional per-session GitHub token used for authentication.
	// When provided, the session authenticates as the token's owner instead of
	// using the global client-level auth.
	GitHubToken string `json:"-"`
	// RemoteSession controls per-session remote behavior:
	//   - "off" — local only, no remote export (default)
	//   - "export" — export session events to GitHub without enabling remote steering
	//   - "on" — export to GitHub AND enable remote steering
	RemoteSession rpc.RemoteSessionMode
	// Cloud creates a remote session in the cloud instead of a local session.
	// The optional repository is associated with the cloud session.
	Cloud *CloudSessionOptions
	// Canvases declares canvases this session provides. Sent over the wire on
	// `session.create`. CanvasHandler must be set when this is non-empty (the
	// SDK does not enforce this — declarations without a handler will surface
	// canvas RPCs that return a canvas_handler_unset error envelope).
	Canvases []CanvasDeclaration
	// RequestCanvasRenderer asks the host to enable canvas rendering for this session.
	RequestCanvasRenderer *bool
	// RequestExtensions asks the host to surface declared canvases as agent-visible extensions.
	RequestExtensions *bool
	// CanvasHandler receives inbound canvas.open / canvas.close / canvas.invokeAction
	// requests for this session. The SDK does not maintain a per-canvas registry;
	// the handler must dispatch on CanvasProviderOpenRequest.CanvasID itself.
	CanvasHandler CanvasHandler `json:"-"`
	// ExtensionInfo identifies the stable extension providing this session's canvases.
	ExtensionInfo *ExtensionInfo
}
type Tool struct {
	Name                 string         `json:"name"`
	Description          string         `json:"description,omitempty"`
	Parameters           map[string]any `json:"parameters,omitempty"`
	OverridesBuiltInTool bool           `json:"overridesBuiltInTool,omitempty"`
	SkipPermission       bool           `json:"skipPermission,omitempty"`
	// Handler is optional. When nil, the SDK exposes the tool declaration but does
	// not automatically invoke it.
	Handler ToolHandler `json:"-"`
}

// ToolInvocation describes a tool call initiated by Copilot
type ToolInvocation struct {
	SessionID  string
	ToolCallID string
	ToolName   string
	Arguments  any

	// TraceContext carries the W3C Trace Context propagated from the CLI's
	// execute_tool span.  Pass this to OpenTelemetry-aware code so that
	// child spans created inside the handler are parented to the CLI span.
	// When no trace context is available this will be context.Background().
	TraceContext context.Context
}

// ToolHandler executes a tool invocation.
// The handler should return a ToolResult. Returning an error marks the tool execution as a failure.
type ToolHandler func(invocation ToolInvocation) (ToolResult, error)

// ToolResult represents the result of a tool invocation.
type ToolResult struct {
	TextResultForLLM    string             `json:"textResultForLlm"`
	BinaryResultsForLLM []ToolBinaryResult `json:"binaryResultsForLlm,omitempty"`
	ResultType          string             `json:"resultType"`
	Error               string             `json:"error,omitempty"`
	SessionLog          string             `json:"sessionLog,omitempty"`
	ToolTelemetry       map[string]any     `json:"toolTelemetry,omitempty"`
}

// CommandContext provides context about a slash-command invocation.
type CommandContext struct {
	// SessionID is the session where the command was invoked.
	SessionID string
	// Command is the full command text (e.g. "/deploy production").
	Command string
	// CommandName is the command name without the leading / (e.g. "deploy").
	CommandName string
	// Args is the raw argument string after the command name.
	Args string
}

// CommandHandler is invoked when a registered slash-command is executed.
type CommandHandler func(ctx CommandContext) error

// CommandDefinition registers a slash-command. Name is shown in the CLI TUI
// as /name for the user to invoke.
type CommandDefinition struct {
	// Name is the command name (without leading /).
	Name string
	// Description is a human-readable description shown in command completion UI.
	Description string
	// Handler is invoked when the command is executed.
	Handler CommandHandler
}

// SessionCapabilities describes what features the host supports.
type SessionCapabilities struct {
	UI *UICapabilities `json:"ui,omitempty"`
}

// UICapabilities describes host UI feature support.
type UICapabilities struct {
	// Elicitation indicates whether the host supports interactive elicitation dialogs.
	Elicitation bool `json:"elicitation,omitempty"`
}

// ElicitationResult is the user's response to an elicitation dialog.
type ElicitationResult struct {
	// Action is the user response: "accept" (submitted), "decline" (rejected), or "cancel" (dismissed).
	Action string `json:"action"`
	// Content holds form values submitted by the user (present when Action is "accept").
	Content map[string]any `json:"content,omitempty"`
}

// ElicitationContext describes an elicitation request from the server,
// combining the request data with session context. Mirrors the
// single-argument pattern of CommandContext.
type ElicitationContext struct {
	// SessionID is the identifier of the session that triggered the request.
	SessionID string
	// Message describes what information is needed from the user.
	Message string
	// RequestedSchema is a JSON Schema describing the form fields (form mode only).
	RequestedSchema map[string]any
	// Mode is "form" for structured input, "url" for browser redirect.
	Mode string
	// ElicitationSource is the source that initiated the request (e.g. MCP server name).
	ElicitationSource string
	// URL to open in the user's browser (url mode only).
	URL string
}

// ElicitationHandler handles elicitation requests from the server (e.g. from MCP tools).
// It receives an ElicitationContext and must return an ElicitationResult.
// If the handler returns an error the SDK auto-cancels the request.
type ElicitationHandler func(ctx ElicitationContext) (ElicitationResult, error)

// UiInputOptions configures a text input field for the Input convenience method.
type UiInputOptions struct {
	// Title label for the input field.
	Title string
	// Description text shown below the field.
	Description string
	// MinLength is the minimum character length.
	MinLength *int
	// MaxLength is the maximum character length.
	MaxLength *int
	// Format is a semantic format hint: "email", "uri", "date", or "date-time".
	Format string
	// Default is the pre-populated value.
	Default string
}

// SessionUI provides convenience methods for showing elicitation dialogs to the user.
// Obtained via [Session.UI]. Methods error if the host does not support elicitation.
type SessionUI struct {
	session *Session
}

// ResumeSessionConfig configures options when resuming a session
type ResumeSessionConfig struct {
	// ClientName identifies the application using the SDK.
	// Included in the User-Agent header for API requests.
	ClientName string
	// Model to use for this session. Can change the model when resuming.
	Model string
	// Tools exposes caller-implemented tools to the CLI. A Tool with a nil Handler
	// is declaration-only; the consumer must resolve its calls via pending tool RPCs.
	Tools []Tool
	// SystemMessage configures system message customization
	SystemMessage *SystemMessageConfig
	// AvailableTools is a list of tool names to allow. When specified, only these tools will be available.
	// Takes precedence over ExcludedTools.
	AvailableTools []string
	// ExcludedTools is a list of tool names to disable. All other tools remain available.
	// Ignored if AvailableTools is specified.
	ExcludedTools []string
	// Provider configures a custom model provider
	Provider *ProviderConfig
	// EnableSessionTelemetry enables or disables internal session telemetry for this session.
	// When false, disables session telemetry. When nil (the default) or true,
	// telemetry is enabled for GitHub-authenticated sessions. When a custom
	// Provider (BYOK) is configured, session telemetry is always disabled
	// regardless of this setting. This is independent of the OpenTelemetry
	// configuration in ClientOptions.Telemetry.
	EnableSessionTelemetry *bool
	// ModelCapabilities overrides individual model capabilities resolved by the runtime.
	// Only non-nil fields are applied over the runtime-resolved capabilities.
	ModelCapabilities *rpc.ModelCapabilitiesOverride
	// ReasoningEffort level for models that support it.
	// Valid values: "low", "medium", "high", "xhigh"
	ReasoningEffort string
	// OnPermissionRequest is an optional handler for permission requests from the server.
	// When nil, permission requests are surfaced as events and left pending for the
	// consumer to resolve via pending permission RPCs.
	OnPermissionRequest PermissionHandlerFunc
	// OnUserInputRequest is a handler for user input requests from the agent (enables ask_user tool)
	OnUserInputRequest UserInputHandler
	// Hooks configures hook handlers for session lifecycle events
	Hooks *SessionHooks
	// WorkingDirectory is the working directory for the session.
	// Tool operations will be relative to this directory.
	WorkingDirectory string
	// ConfigDir overrides the default configuration directory location.
	ConfigDir string
	// EnableConfigDiscovery, when true, automatically discovers MCP server configurations
	// (e.g. .mcp.json, .vscode/mcp.json) and skill directories from the working directory
	// and merges them with any explicitly provided MCPServers and SkillDirectories, with
	// explicit values taking precedence on name collision.
	// Custom instruction files (.github/copilot-instructions.md, AGENTS.md, etc.) are
	// always loaded from the working directory regardless of this setting.
	EnableConfigDiscovery bool
	// Streaming enables streaming of assistant message and reasoning chunks.
	// When non-nil and true, assistant.message_delta and assistant.reasoning_delta
	// events with deltaContent are sent as the response is generated.
	// When nil, the runtime decides (currently defaults to non-streaming).
	Streaming *bool
	// IncludeSubAgentStreamingEvents includes sub-agent streaming events in the
	// event stream. When true, streaming delta events from sub-agents (e.g.,
	// assistant.message_delta, assistant.reasoning_delta, assistant.streaming_delta
	// with agentId set) are forwarded to this connection. When false, only
	// non-streaming sub-agent events and subagent.* lifecycle events are forwarded;
	// streaming deltas from sub-agents are suppressed. When nil, defaults to true.
	IncludeSubAgentStreamingEvents *bool
	// MCPServers configures MCP servers for the session
	MCPServers map[string]MCPServerConfig
	// CustomAgents configures custom agents for the session
	CustomAgents []CustomAgentConfig
	// DefaultAgent configures the default agent (the built-in agent that handles turns when no custom agent is selected).
	DefaultAgent *DefaultAgentConfig
	// Agent is the name of the custom agent to activate when the session starts.
	// Must match the Name of one of the agents in CustomAgents.
	Agent string
	// SkillDirectories is a list of directories to load skills from
	SkillDirectories []string
	// InstructionDirectories is a list of additional directories to search for custom instruction files
	InstructionDirectories []string
	// DisabledSkills is a list of skill names to disable
	DisabledSkills []string
	// InfiniteSessions configures infinite sessions for persistent workspaces and automatic compaction.
	InfiniteSessions *InfiniteSessionConfig
	// GitHubToken is an optional per-session GitHub token used for authentication.
	// When provided, the session authenticates as the token's owner instead of
	// using the global client-level auth.
	GitHubToken string `json:"-"`
	// RemoteSession controls per-session remote behavior.
	// See SessionConfig.RemoteSession for details.
	RemoteSession rpc.RemoteSessionMode
	// SuppressResumeEvent, when true, skips emitting the session.resume event.
	// Useful for reconnecting to a session without triggering resume-related side effects.
	SuppressResumeEvent bool
	// ContinuePendingWork, when true, instructs the runtime to continue any tool calls
	// or permission prompts that were still pending when the session was last suspended.
	// When false (the default), the runtime treats pending work as interrupted on resume.
	//
	// For permission requests, the runtime re-emits permission.requested so the
	// registered OnPermissionRequest handler can re-prompt; for external tool calls,
	// the consumer is expected to supply the result via the corresponding low-level
	// RPC method.
	ContinuePendingWork bool
	// OnEvent is an optional event handler registered before the session.resume RPC
	// is issued, ensuring early events are delivered. See SessionConfig.OnEvent.
	OnEvent SessionEventHandler
	// CreateSessionFsProvider supplies a handler for session filesystem operations.
	// This takes effect only when ClientOptions.SessionFs is configured.
	CreateSessionFsProvider func(session *Session) SessionFsProvider
	// Commands registers slash-commands for this session. See SessionConfig.Commands.
	Commands []CommandDefinition
	// OnElicitationRequest is a handler for elicitation requests from the server.
	// See SessionConfig.OnElicitationRequest.
	OnElicitationRequest ElicitationHandler
	// OnExitPlanModeRequest is a handler for exit-plan-mode requests from the server.
	// See SessionConfig.OnExitPlanModeRequest.
	OnExitPlanModeRequest ExitPlanModeRequestHandler
	// OnAutoModeSwitchRequest is a handler for auto-mode-switch requests from the server.
	// See SessionConfig.OnAutoModeSwitchRequest.
	OnAutoModeSwitchRequest AutoModeSwitchRequestHandler
	// Canvases declares canvases this session provides. Sent over the wire on
	// `session.resume`. See SessionConfig.Canvases.
	Canvases []CanvasDeclaration
	// OpenCanvases declares canvas instances the caller knows were open before
	// this resume so the runtime can re-attach them. Sent over the wire on
	// `session.resume` as `openCanvases`.
	OpenCanvases []rpc.OpenCanvasInstance
	// RequestCanvasRenderer asks the host to enable canvas rendering for this session.
	RequestCanvasRenderer *bool
	// RequestExtensions asks the host to surface declared canvases as agent-visible extensions.
	RequestExtensions *bool
	// CanvasHandler receives inbound canvas.* requests for this session. See SessionConfig.CanvasHandler.
	CanvasHandler CanvasHandler `json:"-"`
	// ExtensionInfo identifies the stable extension providing this session's canvases.
	ExtensionInfo *ExtensionInfo
}
type ProviderConfig struct {
	// Type is the provider type: "openai", "azure", or "anthropic". Defaults to "openai".
	Type string `json:"type,omitempty"`
	// WireApi is the API format (openai/azure only): "completions" or "responses". Defaults to "completions".
	WireApi string `json:"wireApi,omitempty"`
	// BaseURL is the API endpoint URL
	BaseURL string `json:"baseUrl"`
	// APIKey is the API key. Optional for local providers like Ollama.
	APIKey string `json:"apiKey,omitempty"`
	// BearerToken for authentication. Sets the Authorization header directly.
	// Use this for services requiring bearer token auth instead of API key.
	// Takes precedence over APIKey when both are set.
	BearerToken string `json:"bearerToken,omitempty"`
	// Azure contains Azure-specific options
	Azure *AzureProviderOptions `json:"azure,omitempty"`
	// Headers are custom HTTP headers included in outbound provider requests.
	Headers map[string]string `json:"headers,omitempty"`
	// ModelID is the well-known model name used by the runtime to look up
	// agent configuration (tools, prompts, reasoning behavior) and default
	// token limits. Also used as the wire model when WireModel is not set.
	// Falls back to SessionConfig.Model.
	ModelID string `json:"modelId,omitempty"`
	// WireModel is the model name sent to the provider API for inference. Use
	// this when the provider's model name (e.g. an Azure deployment name or a
	// custom fine-tune name) differs from ModelID.
	// Falls back to ModelID, then SessionConfig.Model.
	WireModel string `json:"wireModel,omitempty"`
	// MaxPromptTokens overrides the resolved model's default max prompt tokens.
	// The runtime triggers conversation compaction before sending a request
	// when the prompt (system message, history, tool definitions, user
	// message) would exceed this limit.
	MaxPromptTokens int `json:"maxPromptTokens,omitempty"`
	// MaxOutputTokens overrides the resolved model's default max output
	// tokens. When hit, the model stops generating and returns a truncated
	// response.
	MaxOutputTokens int `json:"maxOutputTokens,omitempty"`
}

// AzureProviderOptions contains Azure-specific provider configuration
type AzureProviderOptions struct {
	// APIVersion is the Azure API version. Defaults to "2024-10-21".
	APIVersion string `json:"apiVersion,omitempty"`
}

// ToolBinaryResult represents binary payloads returned by tools.
type ToolBinaryResult struct {
	Data        string `json:"data"`
	MimeType    string `json:"mimeType"`
	Type        string `json:"type"`
	Description string `json:"description,omitempty"`
}

// MessageOptions configures a message to send
type MessageOptions struct {
	// Prompt is the message to send
	Prompt string
	// Attachments are file or directory attachments
	Attachments []Attachment
	// Mode is the message delivery mode (default: "enqueue")
	Mode string
	// AgentMode is the UI mode the agent was in when this message was sent
	// (for example "plan" or "autopilot"). Defaults to the session's current
	// mode when empty.
	AgentMode AgentMode
	// RequestHeaders are custom per-turn HTTP headers for outbound model requests.
	RequestHeaders map[string]string
}

// AgentMode is the UI mode the agent is in for a given turn. See
// [MessageOptions.AgentMode].
type AgentMode = rpc.SendAgentMode

// AgentMode values supported by the runtime.
const (
	AgentModeInteractive = rpc.SendAgentModeInteractive
	AgentModePlan        = rpc.SendAgentModePlan
	AgentModeAutopilot   = rpc.SendAgentModeAutopilot
	AgentModeShell       = rpc.SendAgentModeShell
)

// SessionEventHandler is a callback for session events
type SessionEventHandler func(event SessionEvent)

// ModelVisionLimits contains vision-specific limits
type ModelVisionLimits struct {
	SupportedMediaTypes []string `json:"supported_media_types"`
	MaxPromptImages     int      `json:"max_prompt_images"`
	MaxPromptImageSize  int      `json:"max_prompt_image_size"`
}

// ModelLimits contains model limits
type ModelLimits struct {
	MaxPromptTokens        *int               `json:"max_prompt_tokens,omitempty"`
	MaxContextWindowTokens int                `json:"max_context_window_tokens"`
	Vision                 *ModelVisionLimits `json:"vision,omitempty"`
}

// ModelSupports contains model support flags
type ModelSupports struct {
	Vision          bool `json:"vision"`
	ReasoningEffort bool `json:"reasoningEffort"`
}

// ModelCapabilities contains model capabilities and limits
type ModelCapabilities struct {
	Supports ModelSupports `json:"supports"`
	Limits   ModelLimits   `json:"limits"`
}

// Type aliases for model capabilities overrides, re-exported from the rpc
// package for ergonomic use without requiring a separate rpc import.
type (
	ModelCapabilitiesOverride             = rpc.ModelCapabilitiesOverride
	ModelCapabilitiesOverrideSupports     = rpc.ModelCapabilitiesOverrideSupports
	ModelCapabilitiesOverrideLimits       = rpc.ModelCapabilitiesOverrideLimits
	ModelCapabilitiesOverrideLimitsVision = rpc.ModelCapabilitiesOverrideLimitsVision
)

// ModelPolicy contains model policy state
type ModelPolicy struct {
	State string `json:"state"`
	Terms string `json:"terms"`
}

// ModelBilling contains model billing information
type ModelBilling struct {
	Multiplier *float64 `json:"multiplier,omitempty"`
}

// ModelInfo contains information about an available model
type ModelInfo struct {
	ID                        string            `json:"id"`
	Name                      string            `json:"name"`
	Capabilities              ModelCapabilities `json:"capabilities"`
	Policy                    *ModelPolicy      `json:"policy,omitempty"`
	Billing                   *ModelBilling     `json:"billing,omitempty"`
	SupportedReasoningEfforts []string          `json:"supportedReasoningEfforts,omitempty"`
	DefaultReasoningEffort    string            `json:"defaultReasoningEffort,omitempty"`
}

// SessionContext contains working directory context for a session
type SessionContext struct {
	// WorkingDirectory is the working directory where the session was created
	WorkingDirectory string `json:"cwd"`
	// GitRoot is the git repository root (if in a git repo)
	GitRoot string `json:"gitRoot,omitempty"`
	// Repository is the GitHub repository in "owner/repo" format
	Repository string `json:"repository,omitempty"`
	// Branch is the current git branch
	Branch string `json:"branch,omitempty"`
}

// SessionListFilter contains filter options for listing sessions
type SessionListFilter struct {
	// WorkingDirectory filters by exact working directory match
	WorkingDirectory string `json:"cwd,omitempty"`
	// GitRoot filters by git root
	GitRoot string `json:"gitRoot,omitempty"`
	// Repository filters by repository (owner/repo format)
	Repository string `json:"repository,omitempty"`
	// Branch filters by branch
	Branch string `json:"branch,omitempty"`
}

// SessionMetadata contains metadata about a session
type SessionMetadata struct {
	SessionID    string          `json:"sessionId"`
	StartTime    time.Time       `json:"startTime"`
	ModifiedTime time.Time       `json:"modifiedTime"`
	Summary      *string         `json:"summary,omitempty"`
	IsRemote     bool            `json:"isRemote"`
	Context      *SessionContext `json:"context,omitempty"`
}

// SessionLifecycleEventType represents the type of session lifecycle event
type SessionLifecycleEventType string

const (
	SessionLifecycleCreated    SessionLifecycleEventType = "session.created"
	SessionLifecycleDeleted    SessionLifecycleEventType = "session.deleted"
	SessionLifecycleUpdated    SessionLifecycleEventType = "session.updated"
	SessionLifecycleForeground SessionLifecycleEventType = "session.foreground"
	SessionLifecycleBackground SessionLifecycleEventType = "session.background"
)

// SessionLifecycleEvent represents a session lifecycle notification
type SessionLifecycleEvent struct {
	Type      SessionLifecycleEventType      `json:"type"`
	SessionID string                         `json:"sessionId"`
	Metadata  *SessionLifecycleEventMetadata `json:"metadata,omitempty"`
}

// SessionLifecycleEventMetadata contains optional metadata for lifecycle events
type SessionLifecycleEventMetadata struct {
	StartTime    time.Time `json:"startTime"`
	ModifiedTime time.Time `json:"modifiedTime"`
	Summary      *string   `json:"summary,omitempty"`
}

// SessionLifecycleHandler is a callback for session lifecycle events
type SessionLifecycleHandler func(event SessionLifecycleEvent)

// createSessionRequest is the request for session.create
type createSessionRequest struct {
	Model                          string                         `json:"model,omitempty"`
	SessionID                      string                         `json:"sessionId,omitempty"`
	ClientName                     string                         `json:"clientName,omitempty"`
	ReasoningEffort                string                         `json:"reasoningEffort,omitempty"`
	Tools                          []Tool                         `json:"tools,omitempty"`
	SystemMessage                  *SystemMessageConfig           `json:"systemMessage,omitempty"`
	AvailableTools                 []string                       `json:"availableTools"`
	ExcludedTools                  []string                       `json:"excludedTools,omitempty"`
	Provider                       *ProviderConfig                `json:"provider,omitempty"`
	EnableSessionTelemetry         *bool                          `json:"enableSessionTelemetry,omitempty"`
	ModelCapabilities              *rpc.ModelCapabilitiesOverride `json:"modelCapabilities,omitempty"`
	RequestPermission              *bool                          `json:"requestPermission,omitempty"`
	RequestUserInput               *bool                          `json:"requestUserInput,omitempty"`
	RequestExitPlanMode            *bool                          `json:"requestExitPlanMode,omitempty"`
	RequestAutoModeSwitch          *bool                          `json:"requestAutoModeSwitch,omitempty"`
	Hooks                          *bool                          `json:"hooks,omitempty"`
	WorkingDirectory               string                         `json:"workingDirectory,omitempty"`
	Streaming                      *bool                          `json:"streaming,omitempty"`
	IncludeSubAgentStreamingEvents *bool                          `json:"includeSubAgentStreamingEvents,omitempty"`
	MCPServers                     map[string]MCPServerConfig     `json:"mcpServers,omitempty"`
	EnvValueMode                   string                         `json:"envValueMode,omitempty"`
	CustomAgents                   []CustomAgentConfig            `json:"customAgents,omitempty"`
	DefaultAgent                   *DefaultAgentConfig            `json:"defaultAgent,omitempty"`
	Agent                          string                         `json:"agent,omitempty"`
	ConfigDir                      string                         `json:"configDir,omitempty"`
	EnableConfigDiscovery          *bool                          `json:"enableConfigDiscovery,omitempty"`
	SkillDirectories               []string                       `json:"skillDirectories,omitempty"`
	InstructionDirectories         []string                       `json:"instructionDirectories,omitempty"`
	DisabledSkills                 []string                       `json:"disabledSkills,omitempty"`
	InfiniteSessions               *InfiniteSessionConfig         `json:"infiniteSessions,omitempty"`
	Commands                       []wireCommand                  `json:"commands,omitempty"`
	RequestElicitation             *bool                          `json:"requestElicitation,omitempty"`
	GitHubToken                    string                         `json:"gitHubToken,omitempty"`
	RemoteSession                  rpc.RemoteSessionMode          `json:"remoteSession,omitempty"`
	Cloud                          *CloudSessionOptions           `json:"cloud,omitempty"`
	Canvases                       []CanvasDeclaration            `json:"canvases,omitempty"`
	RequestCanvasRenderer          *bool                          `json:"requestCanvasRenderer,omitempty"`
	RequestExtensions              *bool                          `json:"requestExtensions,omitempty"`
	ExtensionInfo                  *ExtensionInfo                 `json:"extensionInfo,omitempty"`
	Traceparent                    string                         `json:"traceparent,omitempty"`
	Tracestate                     string                         `json:"tracestate,omitempty"`
}

// wireCommand is the wire representation of a command (name + description only, no handler).
type wireCommand struct {
	Name        string `json:"name"`
	Description string `json:"description,omitempty"`
}

// createSessionResponse is the response from session.create
type createSessionResponse struct {
	SessionID     string               `json:"sessionId"`
	WorkspacePath string               `json:"workspacePath"`
	Capabilities  *SessionCapabilities `json:"capabilities,omitempty"`
}

// resumeSessionRequest is the request for session.resume
type resumeSessionRequest struct {
	SessionID                      string                         `json:"sessionId"`
	ClientName                     string                         `json:"clientName,omitempty"`
	Model                          string                         `json:"model,omitempty"`
	ReasoningEffort                string                         `json:"reasoningEffort,omitempty"`
	Tools                          []Tool                         `json:"tools,omitempty"`
	SystemMessage                  *SystemMessageConfig           `json:"systemMessage,omitempty"`
	AvailableTools                 []string                       `json:"availableTools"`
	ExcludedTools                  []string                       `json:"excludedTools,omitempty"`
	Provider                       *ProviderConfig                `json:"provider,omitempty"`
	EnableSessionTelemetry         *bool                          `json:"enableSessionTelemetry,omitempty"`
	ModelCapabilities              *rpc.ModelCapabilitiesOverride `json:"modelCapabilities,omitempty"`
	RequestPermission              *bool                          `json:"requestPermission,omitempty"`
	RequestUserInput               *bool                          `json:"requestUserInput,omitempty"`
	RequestExitPlanMode            *bool                          `json:"requestExitPlanMode,omitempty"`
	RequestAutoModeSwitch          *bool                          `json:"requestAutoModeSwitch,omitempty"`
	Hooks                          *bool                          `json:"hooks,omitempty"`
	WorkingDirectory               string                         `json:"workingDirectory,omitempty"`
	ConfigDir                      string                         `json:"configDir,omitempty"`
	EnableConfigDiscovery          *bool                          `json:"enableConfigDiscovery,omitempty"`
	DisableResume                  *bool                          `json:"disableResume,omitempty"`
	ContinuePendingWork            *bool                          `json:"continuePendingWork,omitempty"`
	Streaming                      *bool                          `json:"streaming,omitempty"`
	IncludeSubAgentStreamingEvents *bool                          `json:"includeSubAgentStreamingEvents,omitempty"`
	MCPServers                     map[string]MCPServerConfig     `json:"mcpServers,omitempty"`
	EnvValueMode                   string                         `json:"envValueMode,omitempty"`
	CustomAgents                   []CustomAgentConfig            `json:"customAgents,omitempty"`
	DefaultAgent                   *DefaultAgentConfig            `json:"defaultAgent,omitempty"`
	Agent                          string                         `json:"agent,omitempty"`
	SkillDirectories               []string                       `json:"skillDirectories,omitempty"`
	InstructionDirectories         []string                       `json:"instructionDirectories,omitempty"`
	DisabledSkills                 []string                       `json:"disabledSkills,omitempty"`
	InfiniteSessions               *InfiniteSessionConfig         `json:"infiniteSessions,omitempty"`
	Commands                       []wireCommand                  `json:"commands,omitempty"`
	RequestElicitation             *bool                          `json:"requestElicitation,omitempty"`
	GitHubToken                    string                         `json:"gitHubToken,omitempty"`
	RemoteSession                  rpc.RemoteSessionMode          `json:"remoteSession,omitempty"`
	Canvases                       []CanvasDeclaration            `json:"canvases,omitempty"`
	OpenCanvases                   []rpc.OpenCanvasInstance       `json:"openCanvases,omitempty"`
	RequestCanvasRenderer          *bool                          `json:"requestCanvasRenderer,omitempty"`
	RequestExtensions              *bool                          `json:"requestExtensions,omitempty"`
	ExtensionInfo                  *ExtensionInfo                 `json:"extensionInfo,omitempty"`
	Traceparent                    string                         `json:"traceparent,omitempty"`
	Tracestate                     string                         `json:"tracestate,omitempty"`
}

// resumeSessionResponse is the response from session.resume
type resumeSessionResponse struct {
	SessionID     string                   `json:"sessionId"`
	WorkspacePath string                   `json:"workspacePath"`
	Capabilities  *SessionCapabilities     `json:"capabilities,omitempty"`
	OpenCanvases  []rpc.OpenCanvasInstance `json:"openCanvases,omitempty"`
}

type hooksInvokeRequest struct {
	SessionID string          `json:"sessionId"`
	Type      string          `json:"hookType"`
	Input     json.RawMessage `json:"input"`
}

// listSessionsRequest is the request for session.list
type listSessionsRequest struct {
	Filter *SessionListFilter `json:"filter,omitempty"`
}

// listSessionsResponse is the response from session.list
type listSessionsResponse struct {
	Sessions []SessionMetadata `json:"sessions"`
}

// getSessionMetadataRequest is the request for session.getMetadata
type getSessionMetadataRequest struct {
	SessionID string `json:"sessionId"`
}

// getSessionMetadataResponse is the response from session.getMetadata
type getSessionMetadataResponse struct {
	Session *SessionMetadata `json:"session,omitempty"`
}

// deleteSessionRequest is the request for session.delete
type deleteSessionRequest struct {
	SessionID string `json:"sessionId"`
}

// deleteSessionResponse is the response from session.delete
type deleteSessionResponse struct {
	Success bool    `json:"success"`
	Error   *string `json:"error,omitempty"`
}

// getLastSessionIDRequest is the request for session.getLastId
type getLastSessionIDRequest struct{}

// getLastSessionIDResponse is the response from session.getLastId
type getLastSessionIDResponse struct {
	SessionID *string `json:"sessionId,omitempty"`
}

// getForegroundSessionRequest is the request for session.getForeground
type getForegroundSessionRequest struct{}

// getForegroundSessionResponse is the response from session.getForeground
type getForegroundSessionResponse struct {
	SessionID     *string `json:"sessionId,omitempty"`
	WorkspacePath *string `json:"workspacePath,omitempty"`
}

// setForegroundSessionRequest is the request for session.setForeground
type setForegroundSessionRequest struct {
	SessionID string `json:"sessionId"`
}

// setForegroundSessionResponse is the response from session.setForeground
type setForegroundSessionResponse struct {
	Success bool    `json:"success"`
	Error   *string `json:"error,omitempty"`
}

type pingRequest struct {
	Message string `json:"message,omitempty"`
}

// PingResponse is the response from a ping request
type PingResponse struct {
	Message         string    `json:"message"`
	Timestamp       time.Time `json:"timestamp"`
	ProtocolVersion *int      `json:"protocolVersion,omitempty"`
}

// getStatusRequest is the request for status.get
type getStatusRequest struct{}

// GetStatusResponse is the response from status.get
type GetStatusResponse struct {
	Version         string `json:"version"`
	ProtocolVersion int    `json:"protocolVersion"`
}

// getAuthStatusRequest is the request for auth.getStatus
type getAuthStatusRequest struct{}

// GetAuthStatusResponse is the response from auth.getStatus
type GetAuthStatusResponse struct {
	IsAuthenticated bool    `json:"isAuthenticated"`
	AuthType        *string `json:"authType,omitempty"`
	Host            *string `json:"host,omitempty"`
	Login           *string `json:"login,omitempty"`
	StatusMessage   *string `json:"statusMessage,omitempty"`
}

// listModelsRequest is the request for models.list
type listModelsRequest struct{}

// listModelsResponse is the response from models.list
type listModelsResponse struct {
	Models []ModelInfo `json:"models"`
}

// sessionGetMessagesRequest is the request for session.getMessages
type sessionGetMessagesRequest struct {
	SessionID string `json:"sessionId"`
}

// sessionGetMessagesResponse is the response from session.getMessages
type sessionGetMessagesResponse struct {
	Events []SessionEvent `json:"events"`
}

// sessionDestroyRequest is the request for session.destroy
type sessionDestroyRequest struct {
	SessionID string `json:"sessionId"`
}

// sessionAbortRequest is the request for session.abort
type sessionAbortRequest struct {
	SessionID string `json:"sessionId"`
}

type sessionSendRequest struct {
	SessionID      string            `json:"sessionId"`
	Prompt         string            `json:"prompt"`
	Attachments    []Attachment      `json:"attachments,omitempty"`
	Mode           string            `json:"mode,omitempty"`
	AgentMode      AgentMode         `json:"agentMode,omitempty"`
	Traceparent    string            `json:"traceparent,omitempty"`
	Tracestate     string            `json:"tracestate,omitempty"`
	RequestHeaders map[string]string `json:"requestHeaders,omitempty"`
}

// sessionSendResponse is the response from session.send
type sessionSendResponse struct {
	MessageID string `json:"messageId"`
}

// sessionEventRequest is the request for session event notifications
type sessionEventRequest struct {
	SessionID string       `json:"sessionId"`
	Event     SessionEvent `json:"event"`
}

// userInputRequest represents a request for user input from the agent
type userInputRequest struct {
	SessionID     string   `json:"sessionId"`
	Question      string   `json:"question"`
	Choices       []string `json:"choices,omitempty"`
	AllowFreeform *bool    `json:"allowFreeform,omitempty"`
}

// userInputResponse represents the user's response to an input request
type userInputResponse struct {
	Answer      string `json:"answer"`
	WasFreeform bool   `json:"wasFreeform"`
}

type exitPlanModeRequest struct {
	SessionID         string   `json:"sessionId"`
	Summary           string   `json:"summary"`
	PlanContent       string   `json:"planContent,omitempty"`
	Actions           []string `json:"actions"`
	RecommendedAction string   `json:"recommendedAction"`
}

type autoModeSwitchRequest struct {
	SessionID         string   `json:"sessionId"`
	ErrorCode         *string  `json:"errorCode,omitempty"`
	RetryAfterSeconds *float64 `json:"retryAfterSeconds,omitempty"`
}

type autoModeSwitchResponse struct {
	Response AutoModeSwitchResponse `json:"response"`
}