class LittleGhost::Agent

# File lib/little_ghost/agent.rb, line 299

# File lib/little_ghost/agent.rb, line 321

# File lib/little_ghost/agent.rb, line 345

# File lib/little_ghost/agent.rb, line 357

# File lib/little_ghost/agent.rb, line 384
private

# File lib/little_ghost/agent.rb, line 96
def agent_id(*values)
  return assembly_id if values.empty?

  assembly_id(values.fetch(0))
end

# File lib/little_ghost/agent.rb, line 310

# File lib/little_ghost/agent.rb, line 333

# File lib/little_ghost/agent.rb, line 369

# File lib/little_ghost/agent.rb, line 214
def capture_diagnostics(*values)
  return capture_diagnostics_value if values.empty?

  self.capture_diagnostics_value = values.fetch(0) == true
end

# File lib/little_ghost/agent.rb, line 275
def code_mode(engine: nil, except: nil, **options)
  unknown = options.keys - %i[sandbox limits]
  raise ArgumentError, "unknown keyword: #{unknown.first.inspect}" unless unknown.empty?

  declaration = options.merge(engine:, except:).compact
  self.code_mode_configuration_value = declaration.freeze
end

# File lib/little_ghost/agent.rb, line 149
def limits(**values)
  return limits_value if values.empty?

  self.limits_value = limits.merge(values.transform_keys(&:to_sym))
end

# File lib/little_ghost/agent.rb, line 103
def logical_path
  parts = name.to_s.split("::")
  parts[-1] = parts.last.sub(/Agent\z/, "") if parts.any?
  parts.reject(&:empty?).map { |part| underscore(part) }.join("/")
end

# File lib/little_ghost/agent.rb, line 124
def model(*values, &block)
  return model_value if values.empty? && !block
  if block && !values.empty?
    raise ArgumentError, "model accepts either one selection or a block"
  end
  if values.length > 1
    raise ArgumentError, "model accepts one selection"
  end

  self.model_value = block || copy_model_selection(values.fetch(0))
end

# File lib/little_ghost/agent.rb, line 532
def initialize(
  model: nil,
  runtime: nil,
  tools: [],
  template_resolver: nil,
  template_paths: [],
  run: nil,
  executor: nil,
  delegation_activity: nil,
  agent_path: Subagents::AgentPath::ROOT,
  max_turns: 100,
  max_tool_calls: 1_000,
  max_tool_result_tokens: DEFAULT_MAX_TOOL_RESULT_TOKENS,
  model_settings: {},
  workspace: nil,
  sandbox: nil
)
  standalone = model.nil? && run.nil?
  super(run:, runtime:, workspace:, sandbox:, standalone:)
  if standalone
    @framework_prompts = FrameworkPrompts.new(paths: template_paths)
    @framework_prompt_invocation_paths = [].freeze
    @owns_resources = true
    @closed = false
    @close_mutex = Mutex.new
    @interjections_mutex = Mutex.new
    @active_interjections = []
    return
  end

  @model = model
  @runtime = runtime || run&.runtime
  @framework_prompts = if @runtime
    FrameworkPrompts.for_runtime(@runtime)
  else
    FrameworkPrompts.new(paths: template_paths)
  end
  @framework_prompt_invocation_paths = [].freeze
  @run = run
  @workspace = workspace || run&.workspace
  @sandbox = sandbox || run&.sandbox
  if @runtime.is_a?(Runtime) && !@workspace
    @workspace = @runtime.build_workspace
    @sandbox ||= @runtime.build_sandbox(workspace: @workspace)
  end
  @owns_resources = run.nil? && (@workspace || @sandbox)
  binding = Tool::Binding.new(agent: self, run:, runtime: @runtime, model:, workspace: @workspace, sandbox: @sandbox)
  @tool_registry = ToolRegistry.new(tools, binding:)
  self.class.tool_declarations.each do |declaration|
    @tool_registry.register(declaration, replace: true)
  end
  initialize_code_mode
  @structured_output_strategy = StructuredOutput.resolve(
    self.class.result_schema,
    model:,
    ordinary_tools: @tool_registry.specifications
  )
  @model_settings = model_settings.to_h.freeze
  @template_resolver = template_resolver || default_template_resolver(template_paths)
  @executor = executor || Support::Executor.new(runner: task_runner)
  @delegation_activity = delegation_activity
  @agent_path = Subagents::AgentPath.validate!(agent_path)
  @max_turns = Integer(max_turns)
  @max_tool_calls = Integer(max_tool_calls)
  @max_tool_result_tokens = Integer(max_tool_result_tokens)
  @closed = false
  @close_mutex = Mutex.new
  @exclusive_tools_mutex = Mutex.new
  @interjections_mutex = Mutex.new
  @active_interjections = []
  @assembly_transitions_mutex = Mutex.new
  @assembly_transitions = {}
  @assembly_tool_batch_sizes = {}
  @assembly_transition = nil
  @_little_ghost_invocation_mutex = Mutex.new
  @_little_ghost_invocation_active = false
  raise ArgumentError, "max_turns must be at least 1" if @max_turns < 1
  raise ArgumentError, "max_tool_calls must be at least 1" if @max_tool_calls < 1
  raise ArgumentError, "max_tool_result_tokens must be at least 1" if @max_tool_result_tokens < 1
  @artifact_lifecycle = @runtime&.then do |resolved_runtime|
    resolved_runtime.runtime_hooks.find { |hook| hook.is_a?(Runtime::Hooks::Artifacts) }
  end
  apply_cancellation_decision!(run_callbacks(:after_initialize, self))
  @_little_ghost_prompt_assign_baseline = prompt_application_state.freeze
rescue
  @tool_registry&.close
  @code_mode_runtime&.close
  raise
end

# File lib/little_ghost/agent.rb, line 169
def result_schema(schema = nil, name: nil, description: nil, strategy: :auto, **schema_keywords)
  return result_schema_value if schema.nil? && schema_keywords.empty? && name.nil? && description.nil? && strategy == :auto

  if schema.nil?
    schema = schema_keywords
  elsif !schema_keywords.empty?
    raise ArgumentError, "Provide result_schema as a hash or keyword schema, not both"
  end

  raise ArgumentError, "result_schema must be a hash" unless schema.is_a?(Hash)

  normalized_schema = Class.new(Tool).tap { |tool| tool.input_schema(schema) }.input_schema
  validate_result_schema_keywords!(normalized_schema)
  unless normalized_schema["type"] == "object"
    raise ConfigurationError, "result_schema must describe a top-level object"
  end

  schema_name = (name || "#{agent_id}_result").to_s
  unless schema_name.match?(/\A[a-zA-Z0-9_-]{1,64}\z/)
    raise ConfigurationError, "result_schema name must contain 1-64 letters, numbers, underscores, or hyphens"
  end
  strategy = strategy.to_sym
  unless StructuredOutput::STRATEGIES.include?(strategy)
    raise ConfigurationError, "result_schema strategy must be auto, provider, or tool"
  end

  self.result_schema_value = {
    schema: normalized_schema,
    name: schema_name,
    description: description&.to_s,
    strategy:
  }
end

# File lib/little_ghost/agent.rb, line 240
def system_prompt(*values, &block)
  return system_prompt_builder_value || system_prompt_value if values.empty? && !block

  self.system_template_value = nil
  if block
    self.system_prompt_value = nil
    self.system_prompt_builder_value = block
  else
    self.system_prompt_value = values.fetch(0).to_s
    self.system_prompt_builder_value = nil
  end
end

# File lib/little_ghost/agent.rb, line 225
def system_template(*values)
  return system_template_value if values.empty?

  self.system_template_value = values.fetch(0).to_s
end

# File lib/little_ghost/agent.rb, line 258
def tools(*values)
  invalid = values.flatten.compact.find { |value| !value.is_a?(Class) }
  if invalid
    raise ConfigurationError, "Class-level tools must be classes"
  end

  declarations = tool_declarations_value + values
  self.tool_declarations_value = declarations
  tool_declarations
end

# File lib/little_ghost/agent.rb, line 871
def close
  resources, interjections = @close_mutex.synchronize do
    return if @closed

    @closed = true
    [
      [@code_mode_runtime, tool_registry, (@sandbox if @owns_resources), (@workspace if @owns_resources)],
      @interjections_mutex.synchronize { @active_interjections.dup }
    ]
  end
  first_error = nil
  interjections.each do |active|
    active.close(AgentInterjectionError.new("Agent was closed"))
  end
  resources.each do |resource|
    resource.close if resource.respond_to?(:close)
  rescue => error
    first_error ||= error
  end
  raise first_error if first_error
end

# File lib/little_ghost/agent.rb, line 666
def interject(
  message,
  cancellation_token: Support::CancellationToken.new,
  deadline: nil,
  target_operation_id: nil,
  interjection_id: nil,
  batch_key: nil,
  metadata: {}
)
  message = Message.new(role: :user, content: message) if message.is_a?(String)
  raise ArgumentError, "interject message must be a String or LittleGhost::Message" unless message.is_a?(Message)
  safe_content = message.content.all? do |content|
    content.is_a?(Content::Text) ||
      content.is_a?(Content::Image) ||
      content.is_a?(Content::Document)
  end
  unless safe_content
    raise ArgumentError, "interject message content must contain only text, images, or documents"
  end

  interjections = @interjections_mutex.synchronize do
    active = if target_operation_id
      @active_interjections.select { |candidate| candidate.target_operation_id == target_operation_id }
    else
      @active_interjections
    end
    if active.empty?
      raise AgentInterjectionError, "Agent is not currently running"
    end
    if active.length > 1
      raise AgentInterjectionError, "Agent has multiple active invocations; the interjection target is ambiguous"
    end

    active.first
  end
  options = {batch_key:, metadata:}
  options[:id] = interjection_id unless interjection_id.nil?
  ticket = interjections.enqueue(message, **options)
  instrument(
    :agent_interjection_queued,
    parent_operation_id: interjections.operation_id,
    interjection_id: ticket.id,
    event_kind: :interjection,
    diagnostic: {input: diagnostic_message(message)}
  )
  begin
    response = ticket.value(cancellation_token:, deadline:)
    interjections.release(ticket)
    response
  rescue => error
    interjections.release(ticket, withdraw: true)
    instrument(
      :agent_interjection_failed,
      parent_operation_id: interjections.operation_id,
      interjection_id: ticket.id,
      event_kind: :interjection,
      error_type: error.class.name,
      diagnostic: {exception: diagnostic_exception(error)}
    )
    raise
  end
end

# File lib/little_ghost/agent.rb, line 738
def stream(
  input = nil,
  history: nil,
  context: nil,
  cancellation_token: Support::CancellationToken.new,
  deadline: nil,
  settings: nil,
  template_locals: nil,
  template_paths: nil,
  parent_operation_id: nil,
  checkpoint: nil,
  conversation_id: nil,
  interjection_metadata: nil,
  interjection_ids: [],
  interject_ready: nil
)
  if standalone?
    raise ArgumentError, "input is required" if input.nil?

    return build_run(entrypoint_payload(input, {
      history:,
      context:,
      settings:,
      template_paths:,
      deadline_at: deadline,
      cancellation_token:
    }.compact)).each
  end

  raise ArgumentError, "input is required" if input.nil?

  history ||= []
  context ||= {}
  settings ||= {}
  template_locals ||= {}
  template_paths ||= []
  invocation_paths = Array(template_paths).map do |path|
    unless path.is_a?(LittleGhost::TrustedPath)
      raise ArgumentError, "invocation template paths must be LittleGhost::TrustedPath values"
    end
    path
  end
  settings = @model_settings.merge(settings)
  Enumerator.new do |events|
    invocation_acquired = false
    interjections = AgentInterjections.new
    begin
      begin_invocation!
      invocation_acquired = true
      run_context = RunContext.new(
        state: context,
        cancellation_token: cancellation_token,
        deadline: deadline,
        metadata: {agent_id: self.class.agent_id},
        checkpoint:,
        conversation_id:,
        interjection_metadata:,
        interjection_ids:
      )
      with_invocation(run_context) do
        execute(
          input,
          history: history,
          context: run_context,
          settings: settings,
          template_locals: template_locals,
          template_paths: invocation_paths,
          events: events,
          parent_operation_id:,
          interjections:,
          interject_ready:
        )
      end
    rescue => error
      interjections.close(error)
      raise
    ensure
      cleanup_error = nil
      begin
        @code_mode_runtime&.close(context: run_context) if run_context
      rescue => error
        cleanup_error = error
      end
      begin
        interjections.close(AgentInterjectionError.new("Agent finished before the interjection was delivered"))
      rescue => error
        cleanup_error ||= error
      ensure
        begin
          unregister_interjections(interjections)
        ensure
          end_invocation! if invocation_acquired
        end
      end
      raise cleanup_error if cleanup_error
    end
  end
end

# File lib/little_ghost/agent.rb, line 863
def system_prompt
end

# File lib/little_ghost/agent.rb, line 867
def tools = tool_registry

# File lib/little_ghost/agent.rb, line 905
def model_tools(tools, context:, turn:)
  return tools unless @code_mode_runtime

  exceptions = Array(@code_mode_declaration[:except]).map(&:to_s)
  tools.select do |specification|
    name = specification.fetch(:name, specification["name"]).to_s
    tool = tool_registry.fetch(name) if tool_registry.names.include?(name)
    exceptions.include?(name) || %w[exec wait stop].include?(name) ||
      tool.is_a?(Subagents::ControlTool) || !tool
  end
end

# File lib/little_ghost/agent.rb, line 898
def with_invocation(_context)
  yield
end

# File lib/little_ghost/agent.rb, line 920
def with_tool_execution(_execution)
  yield
end