class LittleGhost::Harnesses::Base

Runs one coding-agent command-line tool as a bounded Sandbox process and turns its JSON-lines output into StreamEvent values and a Result.

A harness instance holds trusted settings: the Sandbox (or Sandbox::Scope) that runs the tool, the executable path, where the tool’s home directory lives, and harness-specific defaults. Requests carry the task and its limits.

By default each run gets a new private home directory beneath a Workspace path that the Sandbox lets processes write, and the directory is removed when the run ends, so nothing one run writes there, such as tool configuration, reaches a later run. Passing home opts in to a persistent home that the application owns; see #initialize.

A subclass implements command and parse_line, usually environment, and may override finalize:

class SupportAgentHarness < LittleGhost::Harnesses::Base
  harness_id :support_agent
  default_executable "support-agent"
  supported_versions ">= 1.2"

  def command(request)
    [executable, "run", "--json", request.prompt]
  end

  def environment(request)
    {"SUPPORT_AGENT_HOME" => home}
  end

  def parse_line(line, state)
    data = JSON.parse(line)
    state.text = data["answer"] if data["type"] == "answer"
    state.text ? [{kind: :text, text: state.text}] : []
  end
end

parse_line returns event Hashes whose :kind is :start, :text, :tool_call, :tool_result, or :usage. run wraps each in StreamEvent.build(:harness, harness:, session_id:, event:) and adds one final :stop event. Lines that are not valid JSON are counted in State#malformed_lines and skipped. finalize builds the Result and may be overridden to adjust it.

run stops the process when the request’s timeout elapses, when the reported cost exceeds budget_usd, or when reported turns exceed max_turns, even if the tool does not enforce those limits itself. Cost and turns are reported by the tool, which the model controls, so timeout and limits enforced by a network gateway are the bounds to rely on. Cancellation and run deadlines from context raise after the process is stopped. The process is always closed before run returns.

Each run emits at most 1,000 events before its :stop event, which reports how many were dropped. Session identifiers that are not short tokens are discarded.

Placeholder credentials and base URLs come from defaults or the request’s environment. Real provider keys belong in a network gateway that replaces the placeholder, never in the harness.