YiemAgent/src/harness_types.jl

"""
    harness_types.jl - Extended types for AgentHarness

This module defines the extended types used by the AgentHarness.
"""

module HarnessTypes

using ..Types: *
using ..Session: Session

# ============================================================================
# Result type
# ============================================================================

abstract type Result{TValue, TError} end

struct Ok{TValue, TError} <: Result{TValue, TError}
    value::TValue
end

struct Err{TValue, TError} <: Result{TValue, TError}
    error::TError
end

function ok{TValue, TError}(value::TValue)::Ok{TValue, TError}
    return Ok{TValue, TError}(value)
end

function err{TValue, TError}(error::TError)::Err{TValue, TError}
    return Err{TValue, TError}(error)
end

function getOrThrow{TValue, TError}(result::Result{TValue, TError})::TValue
    if result isa Ok
        return result.value
    else
        throw(result.error)
    end
end

function getOrUndefined{TValue<:AbstractDict, TError}(result::Result{TValue, TError})::Union{TValue, Nothing}
    if result isa Ok
        return result.value
    else
        return nothing
    end
end

function toError(error::Any)::Error
    if error isa Error
        return error
    elseif error isa AbstractString
        return ErrorException(error)
    else
        try
            return ErrorException(string(error))
        catch
            return ErrorException("Unknown error")
        end
    end
end

# ============================================================================
# Skill types
# ============================================================================

mutable struct Skill
    name::String
    description::String
    content::String
    filePath::String
    disableModelInvocation::Bool
end

mutable struct PromptTemplate
    name::String
    description::Union{String, Nothing}
    content::String
end

mutable struct AgentHarnessResources{TSkill<:Skill, TPromptTemplate<:PromptTemplate}
    promptTemplates::Union{Vector{TPromptTemplate}, Nothing}
    skills::Union{Vector{TSkill}, Nothing}
end

# ============================================================================
# Tool types
# ============================================================================

mutable struct AgentHarnessTool{TContext, TParameters, TDetails}
    name::String
    label::String
    description::String
    parameters::TParameters
    execute::Function
    prepareArguments::Union{Function, Nothing}
    executionMode::Union{ToolExecutionMode, Nothing}
end

mutable struct AgentHarnessToolContextSource{TContext}
    context::Union{TContext, Function}
end

# ============================================================================
# Stream options
# ============================================================================

mutable struct AgentHarnessStreamOptions
    transport::Union{String, Nothing}
    timeout_ms::Union{Int64, Nothing}
    max_retries::Union{Int64, Nothing}
    max_retry_delay_ms::Union{Int64, Nothing}
    headers::Union{Dict{String, String}, Nothing}
    metadata::Union{Dict{String, Any}, Nothing}
    cache_retention::Union{String, Nothing}
end

mutable struct AgentHarnessStreamOptionsPatch
    transport::Union{String, Nothing}
    timeout_ms::Union{Int64, Nothing}
    max_retries::Union{Int64, Nothing}
    max_retry_delay_ms::Union{Int64, Nothing}
    cache_retention::Union{String, Nothing}
    headers::Union{Dict{String, String}, Nothing}
    metadata::Union{Dict{String, Any}, Nothing}
end

# ============================================================================
# File system types
# ============================================================================

const FileKind = String
const FILE_KIND_FILE = "file"
const FILE_KIND_DIRECTORY = "directory"
const FILE_KIND_SYMLINK = "symlink"

const FileErrorCode = String
const FILE_ERROR_ABORTED = "aborted"
const FILE_ERROR_NOT_FOUND = "not_found"
const FILE_ERROR_PERMISSION_DENIED = "permission_denied"
const FILE_ERROR_NOT_DIRECTORY = "not_directory"
const FILE_ERROR_IS_DIRECTORY = "is_directory"
const FILE_ERROR_INVALID = "invalid"
const FILE_ERROR_NOT_SUPPORTED = "not_supported"
const FILE_ERROR_UNKNOWN = "unknown"

mutable struct FileError <: Exception
    code::FileErrorCode
    message::String
    path::Union{String, Nothing}
    cause::Union{Exception, Nothing}
end

# ============================================================================
# Execution error types
# ============================================================================

const ExecutionErrorCode = String
const EXECUTION_ERROR_ABORTED = "aborted"
const EXECUTION_ERROR_TIMEOUT = "timeout"
const EXECUTION_ERROR_SHELL_UNAVAILABLE = "shell_unavailable"
const EXECISION_ERROR_SPAWN_ERROR = "spawn_error"
const EXECUTION_ERROR_CALLBACK_ERROR = "callback_error"
const EXECUTION_ERROR_UNKNOWN = "unknown"

mutable struct ExecutionError <: Exception
    code::ExecutionErrorCode
    message::String
    cause::Union{Exception, Nothing}
end

# ============================================================================
# Compaction error types
# ============================================================================

const CompactionErrorCode = String
const COMPACTION_ERROR_ABORTED = "aborted"
const COMPACTION_ERROR_SUMMARIZATION_FAILED = "summarization_failed"
const COMPACTION_ERROR_INVALID_SESSION = "invalid_session"
const COMPACTION_ERROR_UNKNOWN = "unknown"

mutable struct CompactionError <: Exception
    code::CompactionErrorCode
    message::String
    cause::Union{Exception, Nothing}
end

# ============================================================================
# Branch summary error types
# ============================================================================

const BranchSummaryErrorCode = String
const BRANCH_SUMMARY_ERROR_ABORTED = "aborted"
const BRANCH_SUMMARY_ERROR_SUMMARIZATION_FAILED = "summarization_failed"
const BRANCH_SUMMARY_ERROR_INVALID_SESSION = "invalid_session"

mutable struct BranchSummaryError <: Exception
    code::BranchSummaryErrorCode
    message::String
    cause::Union{Exception, Nothing}
end

# ============================================================================
# Session error types
# ============================================================================

const SessionErrorCode = String
const SESSION_ERROR_NOT_FOUND = "not_found"
const SESSION_ERROR_INVALID_SESSION = "invalid_session"
const SESSION_ERROR_INVALID_ENTRY = "invalid_entry"
const SESSION_ERROR_INVALID_FORK_TARGET = "invalid_fork_target"
const SESSION_ERROR_STORAGE = "storage"
const SESSION_ERROR_UNKNOWN = "unknown"

mutable struct SessionError <: Exception
    code::SessionErrorCode
    message::String
    cause::Union{Exception, Nothing}
end

# ============================================================================
# Agent harness error types
# ============================================================================

const AgentHarnessErrorCode = String
const AGENT_HARNESS_ERROR_BUSY = "busy"
const AGENT_HARNESS_ERROR_INVALID_STATE = "invalid_state"
const AGENT_HARNESS_ERROR_INVALID_ARGUMENT = "invalid_argument"
const AGENT_HARNESS_ERROR_SESSION = "session"
const AGENT_HARNESS_ERROR_HOOK = "hook"
const AGENT_HARNESS_ERROR_AUTH = "auth"
const AGENT_HARNESS_ERROR_COMPACTION = "compaction"
const AGENT_HARNESS_ERROR_BRANCH_SUMMARY = "branch_summary"
const AGENT_HARNESS_ERROR_UNKNOWN = "unknown"

mutable struct AgentHarnessError <: Exception
    code::AgentHarnessErrorCode
    message::String
    cause::Union{Exception, Nothing}
end

# ============================================================================
# File system interface
# ============================================================================

abstract type FileSystem end

function absolutePath(fs::FileSystem, path::String, abortSignal::Union{Nothing, Any})::Result{String, FileError}
    return err(FileError("not_supported", "absolutePath not implemented", path, nothing))
end

function joinPath(fs::FileSystem, parts::Vector{String}, abortSignal::Union{Nothing, Any})::Result{String, FileError}
    return err(FileError("not_supported", "joinPath not implemented", nothing, nothing))
end

function readTextFile(fs::FileSystem, path::String, abortSignal::Union{Nothing, Any})::Result{String, FileError}
    return err(FileError("not_supported", "readTextFile not implemented", path, nothing))
end

function readTextLines(
    fs::FileSystem,
    path::String,
    options::Dict{String, Any},
)::Result{Vector{String}, FileError}
    return err(FileError("not_supported", "readTextLines not implemented", path, nothing))
end

function readBinaryFile(fs::FileSystem, path::String, abortSignal::Union{Nothing, Any})::Result{Vector{UInt8}, FileError}
    return err(FileError("not_supported", "readBinaryFile not implemented", path, nothing))
end

function writeFile(fs::FileSystem, path::String, content::Union{String, Vector{UInt8}}, abortSignal::Union{Nothing, Any})::Result{Nothing, FileError}
    return err(FileError("not_supported", "writeFile not implemented", path, nothing))
end

function appendFile(fs::FileSystem, path::String, content::Union{String, Vector{UInt8}}, abortSignal::Union{Nothing, Any})::Result{Nothing, FileError}
    return err(FileError("not_supported", "appendFile not implemented", path, nothing))
end

function fileInfo(fs::FileSystem, path::String, abortSignal::Union{Nothing, Any})::Result{FileInfo, FileError}
    return err(FileError("not_supported", "fileInfo not implemented", path, nothing))
end

function listDir(fs::FileSystem, path::String, abortSignal::Union{Nothing, Any})::Result{Vector{FileInfo}, FileError}
    return err(FileError("not_supported", "listDir not implemented", path, nothing))
end

function canonicalPath(fs::FileSystem, path::String, abortSignal::Union{Nothing, Any})::Result{String, FileError}
    return err(FileError("not_supported", "canonicalPath not implemented", path, nothing))
end

function exists(fs::FileSystem, path::String, abortSignal::Union{Nothing, Any})::Result{Bool, FileError}
    return err(FileError("not_supported", "exists not implemented", path, nothing))
end

function createDir(
    fs::FileSystem,
    path::String,
    options::Dict{String, Any},
)::Result{Nothing, FileError}
    return err(FileError("not_supported", "createDir not implemented", path, nothing))
end

function remove(
    fs::FileSystem,
    path::String,
    options::Dict{String, Any},
)::Result{Nothing, FileError}
    return err(FileError("not_supported", "remove not implemented", path, nothing))
end

function createTempDir(fs::FileSystem, prefix::String="tmp-", abortSignal::Union{Nothing, Any})::Result{String, FileError}
    return err(FileError("not_supported", "createTempDir not implemented", nothing, nothing))
end

function createTempFile(fs::FileSystem, options::Dict{String, Any})::Result{String, FileError}
    return err(FileError("not_supported", "createTempFile not implemented", nothing, nothing))
end

function cleanup(fs::FileSystem)::Nothing
    return nothing
end

# ============================================================================
# Shell interface
# ============================================================================

mutable struct ShellExecOptions
    cwd::Union{String, Nothing}
    env::Union{Dict{String, String}, Nothing}
    inheritEnv::Bool
    timeout::Union{Int64, Nothing}
    abortSignal::Union{Any, Nothing}
    onStdout::Union{Function, Nothing}
    onStderr::Union{Function, Nothing}
end

abstract type Shell end

function exec(shell::Shell, command::String, options::Dict{String, Any})::Result{Dict{String, Any}, ExecutionError}
    return err(ExecutionError("not_supported", "exec not implemented", nothing))
end

function cleanup(shell::Shell)::Nothing
    return nothing
end

# ============================================================================
# Execution environment
# ============================================================================

abstract type ExecutionEnv <: FileSystem, Shell end

# ============================================================================
# Session tree entry types
# ============================================================================

abstract type SessionTreeEntry end

struct MessageEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    message::AgentMessage
end

struct ThinkingLevelChangeEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    thinking_level::String
end

struct ModelChangeEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    provider::String
    model_id::String
end

struct ActiveToolsChangeEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    active_tool_names::Vector{String}
end

struct CompactionEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    summary::String
    first_kept_entry_id::Union{String, Nothing}
    tokens_before::Int64
    retained_tail::Union{Vector{AgentMessage}, Nothing}
    details::Union{Any, Nothing}
    usage::Union{Usage, Nothing}
    from_hook::Bool
end

struct BranchSummaryEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    from_id::String
    summary::String
    details::Union{Any, Nothing}
    usage::Union{Usage, Nothing}
    from_hook::Bool
end

struct CustomEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    custom_type::String
    data::Union{Any, Nothing}
end

struct CustomMessageEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    custom_type::String
    content::String
    details::Union{Any, Nothing}
    display::Bool
end

struct LabelEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    target_id::String
    label::Union{String, Nothing}
end

struct SessionInfoEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    name::Union{String, Nothing}
end

struct LeafEntry <: SessionTreeEntry
    type::String
    id::String
    parent_id::Union{String, Nothing}
    timestamp::String
    target_id::Union{String, Nothing}
end

# ============================================================================
# Session context
# ============================================================================

struct SessionContext
    messages::Vector{AgentMessage}
    thinking_level::String
    model::Union{Dict{String, String}, Nothing}
    active_tool_names::Union{Vector{String}, Nothing}
end

# ============================================================================
# Session stats
# ============================================================================

struct SessionStats
    message_count::Int64
    cached_tokens::Int64
    uncached_tokens::Int64
    total_tokens::Int64
    cost_total::Float64
end

# ============================================================================
# Session metadata
# ============================================================================

mutable struct SessionMetadata
    id::String
    created_at::String
end

mutable struct JsonlSessionMetadata <: SessionMetadata
    id::String
    created_at::String
    cwd::String
    path::String
    parent_session_path::Union{String, Nothing}
    metadata::Union{Dict{String, Any}, Nothing}
end

# ============================================================================
# Session storage interface
# ============================================================================

abstract type SessionStorage{T<:SessionMetadata} end

function getMetadata(storage::SessionStorage)::Promise{T}
    return Promise()
end

function getLeafId(storage::SessionStorage)::Promise{Union{String, Nothing}}
    return Promise()
end

function setLeafId(storage::SessionStorage, leaf_id::String)::Promise{Nothing}
    return Promise()
end

function createEntryId(storage::SessionStorage)::Promise{String}
    return Promise()
end

function appendEntry(storage::SessionStorage, entry::SessionTreeEntry)::Promise{Nothing}
    return Promise()
end

function getEntry(storage::SessionStorage, id::String)::Promise{Union{SessionTreeEntry, Nothing}}
    return Promise()
end

function findEntries(storage::SessionStorage, type::String)::Promise{Vector{SessionTreeEntry}}
    return Promise()
end

function getLabel(storage::SessionStorage, id::String)::Promise{Union{String, Nothing}}
    return Promise()
end

function getSessionName(storage::SessionStorage)::Promise{Union{String, Nothing}}
    return Promise()
end

function getSessionStats(storage::SessionStorage)::Promise{SessionStats}
    return Promise()
end

function getPathToRootOrCompaction(storage::SessionStorage, leaf_id::String)::Promise{Vector{SessionTreeEntry}}
    return Promise()
end

function getEntries(storage::SessionStorage, options::Dict{String, Any})::Promise{Vector{SessionTreeEntry}}
    return Promise()
end

# ============================================================================
# Session repo interface
# ============================================================================

abstract type SessionRepo<
    TMetadata<:SessionMetadata,
    TCreateOptions,
    TListOptions
> end

function create(repo::SessionRepo, options::TCreateOptions)::Promise{Session}
    return Promise()
end

function open(repo::SessionRepo, metadata::TMetadata)::Promise{Session}
    return Promise()
end

function list(repo::SessionRepo, options::TListOptions)::Promise{Vector{TMetadata}}
    return Promise()
end

function delete(repo::SessionRepo, metadata::TMetadata)::Promise{Nothing}
    return Promise()
end

function fork(repo::SessionRepo, source::TMetadata, options::Dict{String, Any})::Promise{Session}
    return Promise()
end

# ============================================================================
# Pending session write
# ============================================================================

mutable struct PendingSessionWrite
    type::String
    message::Union{AgentMessage, Nothing}
    provider::Union{String, Nothing}
    model_id::Union{String, Nothing}
    thinking_level::Union{String, Nothing}
    active_tool_names::Union{Vector{String}, Nothing}
    custom_type::Union{String, Nothing}
    data::Union{Any, Nothing}
    content::Union{String, Nothing}
    display::Union{Bool, Nothing}
    target_id::Union{String, Nothing}
    label::Union{String, Nothing}
    name::Union{String, Nothing}
end

# ============================================================================
# Queue update event
# ============================================================================

mutable struct QueueUpdateEvent
    type::String
    steer::Vector{AgentMessage}
    followUp::Vector{AgentMessage}
    nextTurn::Vector{AgentMessage}
end

# ============================================================================
# Save point event
# ============================================================================

mutable struct SavePointEvent
    type::String
    had_pending_mutations::Bool
end

# ============================================================================
# Abort event
# ============================================================================

mutable struct AbortEvent
    type::String
    cleared_steer::Vector{AgentMessage}
    cleared_follow_up::Vector{AgentMessage}
end

# ============================================================================
# Settled event
# ============================================================================

mutable struct SettledEvent
    type::String
    next_turn_count::Int64
end

# ============================================================================
# Before agent start event
# ============================================================================

mutable struct BeforeAgentStartEvent{TSkill<:Skill, TPromptTemplate<:PromptTemplate}
    type::String
    prompt::String
    images::Union{Vector{ImageContent}, Nothing}
    system_prompt::String
    resources::AgentHarnessResources{TSkill, TPromptTemplate}
end

# ============================================================================
# Context event
# ============================================================================

mutable struct ContextEvent
    type::String
    messages::Vector{AgentMessage}
end

# ============================================================================
# Before provider request event
# ============================================================================

mutable struct BeforeProviderRequestEvent
    type::String
    model::Model
    session_id::String
    stream_options::AgentHarnessStreamOptions
end

# ============================================================================
# Before provider payload event
# ============================================================================

mutable struct BeforeProviderPayloadEvent
    type::String
    model::Model
    payload::Any
end

# ============================================================================
# After provider response event
# ============================================================================

mutable struct AfterProviderResponseEvent
    type::String
    status::Int64
    headers::Dict{String, String}
end

# ============================================================================
# Tool call event
# ============================================================================

mutable struct ToolCallEvent
    type::String
    tool_call_id::String
    tool_name::String
    input::Dict{String, Any}
end

# ============================================================================
# Tool result event
# ============================================================================

mutable struct ToolResultEvent
    type::String
    tool_call_id::String
    tool_name::String
    input::Dict{String, Any}
    content::Vector{MessageContent}
    details::Any
    is_error::Bool
    usage::Union{Usage, Nothing}
end

# ============================================================================
# Session before compact event
# ============================================================================

mutable struct SessionBeforeCompactEvent
    type::String
    preparation::Any
    branch_entries::Vector{SessionTreeEntry}
    custom_instructions::Union{String, Nothing}
    signal::Any
end

# ============================================================================
# Session compact event
# ============================================================================

mutable struct SessionCompactEvent
    type::String
    compaction_entry::CompactionEntry
    from_hook::Bool
end

# ============================================================================
# Session before tree event
# ============================================================================

mutable struct SessionBeforeTreeEvent
    type::String
    preparation::Any
    signal::Any
end

# ============================================================================
# Session tree event
# ============================================================================

mutable struct SessionTreeEvent
    type::String
    new_leaf_id::Union{String, Nothing}
    old_leaf_id::Union{String, Nothing}
    summary_entry::Union{BranchSummaryEntry, Nothing}
    from_hook::Union{Bool, Nothing}
end

# ============================================================================
# Retry scheduled event
# ============================================================================

mutable struct RetryScheduledEvent
    type::String
    operation::String
    attempt::Int64
    max_attempts::Int64
    delay_ms::Int64
    error_message::String
end

# ============================================================================
# Retry attempt start event
# ============================================================================

mutable struct RetryAttemptStartEvent
    type::String
    operation::String
end

# ============================================================================
# Retry finished event
# ============================================================================

mutable struct RetryFinishedEvent
    type::String
    operation::String
end

# ============================================================================
# Model update event
# ============================================================================

mutable struct ModelUpdateEvent
    type::String
    model::Model
    previous_model::Union{Model, Nothing}
    source::String
end

# ============================================================================
# Thinking level update event
# ============================================================================

mutable struct ThinkingLevelUpdateEvent
    type::String
    level::ThinkingLevel
    previous_level::ThinkingLevel
end

# ============================================================================
# Tools update event
# ============================================================================

mutable struct ToolsUpdateEvent
    type::String
    tool_names::Vector{String}
    previous_tool_names::Vector{String}
    active_tool_names::Vector{String}
    previous_active_tool_names::Vector{String}
    source::String
end

# ============================================================================
# Resources update event
# ============================================================================

mutable struct ResourcesUpdateEvent{TSkill<:Skill, TPromptTemplate<:PromptTemplate}
    type::String
    resources::AgentHarnessResources{TSkill, TPromptTemplate}
    previous_resources::AgentHarnessResources{TSkill, TPromptTemplate}
end

# ============================================================================
# Agent harness own events
# ============================================================================

abstract type AgentHarnessOwnEvent{TSkill<:Skill, TPromptTemplate<:PromptTemplate} end

# ============================================================================
# Agent harness event
# ============================================================================

abstract type AgentHarnessEvent{TSkill<:Skill, TPromptTemplate<:PromptTemplate} <: AgentEvent, AgentHarnessOwnEvent{TSkill, TPromptTemplate} end

# ============================================================================
# Before agent start result
# ============================================================================

mutable struct BeforeAgentStartResult
    messages::Union{Vector{AgentMessage}, Nothing}
    system_prompt::Union{String, Nothing}
end

# ============================================================================
# Context result
# ============================================================================

mutable struct ContextResult
    messages::Vector{AgentMessage}
end

# ============================================================================
# Before provider request result
# ============================================================================

mutable struct BeforeProviderRequestResult
    stream_options::Union{AgentHarnessStreamOptionsPatch, Nothing}
end

# ============================================================================
# Before provider payload result
# ============================================================================

mutable struct BeforeProviderPayloadResult
    payload::Any
end

# ============================================================================
# Tool call result
# ============================================================================

mutable struct ToolCallResult
    block::Union{Bool, Nothing}
    reason::Union{String, Nothing}
end

# ============================================================================
# Tool result patch
# ============================================================================

mutable struct ToolResultPatch
    content::Union{Vector{MessageContent}, Nothing}
    details::Union{Any, Nothing}
    is_error::Union{Bool, Nothing}
    usage::Union{Usage, Nothing}
    terminate::Union{Bool, Nothing}
end

# ============================================================================
# Session before compact result
# ============================================================================

mutable struct SessionBeforeCompactResult
    cancel::Union{Bool, Nothing}
    compaction::Union{CompactResult, Nothing}
end

# ============================================================================
# Session before tree result
# ============================================================================

mutable struct SessionBeforeTreeResult
    cancel::Union{Bool, Nothing}
    summary::Union{Dict{String, Any}, Nothing}
    custom_instructions::Union{String, Nothing}
    replace_instructions::Union{Bool, Nothing}
    label::Union{String, Nothing}
end

# ============================================================================
# Agent harness event result map
# ============================================================================

# ============================================================================
# Agent harness prompt options
# ============================================================================

mutable struct AgentHarnessPromptOptions
    images::Union{Vector{ImageContent}, Nothing}
end

# ============================================================================
# Abort result
# ============================================================================

mutable struct AbortResult
    cleared_steer::Vector{AgentMessage}
    cleared_follow_up::Vector{AgentMessage}
end

# ============================================================================
# Compact result
# ============================================================================

mutable struct CompactResult
    summary::String
    first_kept_entry_id::Union{String, Nothing}
    tokens_before::Int64
    usage::Union{Usage, Nothing}
    retained_tail::Union{Vector{AgentMessage}, Nothing}
    details::Union{Any, Nothing}
end

# ============================================================================
# Navigate tree result
# ============================================================================

mutable struct NavigateTreeResult
    cancelled::Bool
    editor_text::Union{String, Nothing}
    summary_entry::Union{BranchSummaryEntry, Nothing}
end

# ============================================================================
# Compaction settings
# ============================================================================

mutable struct CompactionSettings
    enabled::Bool
    reserve_tokens::Int64
    keep_recent_tokens::Int64
end

const DEFAULT_COMPACTION_SETTINGS = CompactionSettings(true, 16384, 20000)

# ============================================================================
# Compaction preparation
# ============================================================================

mutable struct CompactionPreparation
    first_kept_entry_id::String
    messages_to_summarize::Vector{AgentMessage}
    turn_prefix_messages::Vector{AgentMessage}
    retained_tail::Vector{AgentMessage}
    is_split_turn::Bool
    tokens_before::Int64
    previous_summary::Union{String, Nothing}
    file_ops::Any
    settings::CompactionSettings
end

# ============================================================================
# File operations
# ============================================================================

mutable struct FileOperations
    read::Set{String}
    written::Set{String}
    edited::Set{String}
end

# ============================================================================
# Tree preparation
# ============================================================================

mutable struct TreePreparation
    target_id::String
    old_leaf_id::Union{String, Nothing}
    common_ancestor_id::Union{String, Nothing}
    entries_to_summarize::Vector{SessionTreeEntry}
    user_wants_summary::Bool
    custom_instructions::Union{String, Nothing}
    replace_instructions::Union{Bool, Nothing}
    label::Union{String, Nothing}
end

# ============================================================================
# Generate branch summary options
# ============================================================================

mutable struct GenerateBranchSummaryOptions
    model::Model
    api_key::String
    headers::Union{Dict{String, String}, Nothing}
    signal::Any
    custom_instructions::Union{String, Nothing}
    replace_instructions::Union{Bool, Nothing}
    reserve_tokens::Int64
end

# ============================================================================
# Branch summary result
# ============================================================================

mutable struct BranchSummaryResult
    summary::String
    usage::Union{Usage, Nothing}
    read_files::Vector{String}
    modified_files::Vector{String}
end

# ============================================================================
# Agent harness system prompt
# ============================================================================

mutable struct AgentHarnessSystemPrompt{TC<:Any, TSkill<:Skill, TPromptTemplate<:PromptTemplate, TTool<:AgentHarnessTool}
    value::Union{String, Function}
end

# ============================================================================
# Agent harness options
# ============================================================================

mutable struct AgentHarnessOptions{TC<:Any, TSkill<:Skill, TPromptTemplate<:PromptTemplate, TTool<:AgentHarnessTool}
    session::Session
    models::Any
    tools::Union{Vector{TTool}, Nothing}
    resources::Union{AgentHarnessResources{TSkill, TPromptTemplate}, Nothing}
    system_prompt::Union{AgentHarnessSystemPrompt{TC, TSkill, TPromptTemplate, TTool}, Nothing}
    stream_options::Union{AgentHarnessStreamOptions, Nothing}
    retry::Union{Any, Nothing}
    model::Model
    thinking_level::Union{ThinkingLevel, Nothing}
    active_tool_names::Union{Vector{String}, Nothing}
    steering_mode::Union{QueueMode, Nothing}
    follow_up_mode::Union{QueueMode, Nothing}
    tool_context::Union{AgentHarnessToolContextSource{TC}, Nothing}
end

end