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.
Attributes
Frozen harness-specific settings.
Executable path or command name.
Workspace path name for temporary homes, or nil.
:isolated or :native_guards.
Sandbox or Sandbox::Scope that runs the tool, or nil for the host.
Public Class Methods
# File lib/little_ghost/harnesses/base.rb, line 94 def default_executable(*values) return @default_executable || superclass_value(:default_executable) if values.empty? @default_executable = String(values.fetch(0)).freeze end
Command name used when an application does not configure a path.
# File lib/little_ghost/harnesses/base.rb, line 83 def harness_id(*values) return @harness_id || superclass_value(:harness_id) if values.empty? @harness_id = values.fetch(0).to_sym end
Identifier used in events and results.
# File lib/little_ghost/harnesses/base.rb, line 149 def initialize(sandbox: nil, home: nil, executable: self.class.default_executable, defaults: {}, home_root: nil, mode: nil) raise ArgumentError, "harness executable is required" if executable.nil? || String(executable).empty? raise ArgumentError, "harness home must be an absolute path" unless home.nil? || String(home).start_with?("/") @sandbox = sandbox @executable = String(executable).dup.freeze @home = home && String(home).dup.freeze @home_root = home_root&.to_sym @mode = resolve_mode(mode) @defaults = defaults.to_h.transform_keys(&:to_sym).freeze if @defaults.key?(:api_key) && !String(@defaults[:api_key]).start_with?(PLACEHOLDER_API_KEY) raise ConfigurationError, "harness api_key must be a placeholder beginning with #{PLACEHOLDER_API_KEY}" end end
Builds a harness. sandbox is a Sandbox or Sandbox::Scope that runs the tool, or nil to run it directly on the host. defaults holds harness-specific settings such as :base_url, :api_key, :model, :environment, and :output_bytes. An :api_key must be a placeholder that begins with little-ghost-placeholder.
mode decides which safeguards apply:
:isolated-
The
Sandboxis the boundary, so the tool’s own approval prompts and command sandbox are turned off and it receives the placeholder key. Requires aSandboxthat reports isolation and does not inherit the host network; any otherSandboxraisesConfigurationError. :native_guards-
The tool keeps its own safeguards: a restricted tool and permission set, and its own command sandbox where it has one. The child inherits the environment, so the tool authenticates with the user’s own credentials;
LittleGhostnever reads, stores, or forwards them.
Without mode, an isolating Sandbox selects :isolated and nil or any other Sandbox selects :native_guards.
Without home, each run creates a private home beneath home_root, the name of a Workspace path the Sandbox lets processes write (:root for the Workspace root), and removes it afterwards. When home_root is nil the first writable runtime path in the Sandbox policy is used, or a host temporary directory when the Sandbox does not isolate. home instead names a persistent home directory as the child sees it; the tool can change files there, including its own configuration, and those changes affect every later run that uses the same home.
# File lib/little_ghost/harnesses/base.rb, line 105 def supported_versions(*requirements) return @supported_versions || superclass_value(:supported_versions) || Gem::Requirement.default if requirements.empty? @supported_versions = Gem::Requirement.new(*requirements) end
Tool versions whose command line and output this harness understands.
Public Instance Methods
Source
# File lib/little_ghost/harnesses/base.rb, line 253 def command(request) raise AbstractMethodError, "#{self.class} must implement #command" end
Returns the command line for request, beginning with executable.
Source
# File lib/little_ghost/harnesses/base.rb, line 259 def environment(request) = {}
Returns child-process variables for request. Defaults and the request’s own environment are merged over this Hash.
# File lib/little_ghost/harnesses/base.rb, line 270 def finalize(state, exit_code:, stderr_tail:, outcome:) status = outcome || state.status || (exit_code&.zero? ? :completed : :failed) Result.new( harness: harness_id, status:, text: state.text, session_id: state.session_id, cost_usd: state.cost_usd, usage: state.usage, turns: state.turns, exit_code:, stop_reason: state.stop_reason&.to_s&.[](0, STOP_REASON_LIMIT), stderr_tail: ) end
Source
# File lib/little_ghost/harnesses/base.rb, line 180 def harness_id = self.class.harness_id
Identifier used in events and results.
Source
# File lib/little_ghost/harnesses/base.rb, line 183 def isolated? = mode == :isolated
Whether the Sandbox is the boundary and the tool’s own safeguards are off.
Source
# File lib/little_ghost/harnesses/base.rb, line 263 def parse_line(line, state) raise AbstractMethodError, "#{self.class} must implement #parse_line" end
Records progress from one output line in state and returns an Array of event Hashes.
# File lib/little_ghost/harnesses/base.rb, line 187 def probe(context: nil, timeout: 30) return with_temporary_home { |harness| harness.probe(context:, timeout:) } unless home result = runner.execute_program( [executable, "--version"], timeout:, context:, max_output_bytes: 16_384, environment: base_environment ) unless result.success? return {available: false, version: nil, supported: false, reason: "#{executable} --version exited with #{result.exit_code.inspect}"} end version = result.stdout[/\d+\.\d+\.\d+(?:[-.][0-9A-Za-z.]+)?/] return {available: true, version: nil, supported: false, reason: "version was not reported"} unless version supported = self.class.supported_versions.satisfied_by?(Gem::Version.new(version)) {available: true, version:, supported:, reason: supported ? nil : "version #{version} is not supported"} rescue ArgumentError {available: true, version:, supported: false, reason: "version #{version} could not be compared"} rescue ToolError => error {available: false, version: nil, supported: false, reason: error.message} end
Runs executable --version in the sandbox and returns a Hash with :available, :version, :supported, and :reason.
# File lib/little_ghost/harnesses/base.rb, line 217 def run(request, context: nil, &block) raise ArgumentError, "harness request must be a LittleGhost::Harnesses::Request" unless request.is_a?(Request) return with_temporary_home { |harness| harness.run(request, context:, &block) } unless home state = State.new timeout = context ? context.remaining_time(request.timeout) : request.timeout deadline = monotonic_time + timeout session = runner.start_program( command(request), context:, environment: process_environment(request), inherit_environment: !isolated?, cwd: request.cwd, output_bytes: defaults.fetch(:output_bytes, DEFAULT_OUTPUT_BYTES) ) session.close_write outcome, stderr_tail = consume(session, request, state, deadline, context, block) exit_code = session.wait(timeout: EXIT_WAIT)&.exitstatus result = finalize(state, exit_code:, stderr_tail:, outcome:) stop = { kind: :stop, status: result.status, stop_reason: result.stop_reason, cost_usd: result.cost_usd, turns: result.turns, exit_code: } stop[:dropped_events] = state.values[:dropped_events] if state.values[:dropped_events] emit(block, state, stop) result ensure session&.close end
Runs request and returns a Result, yielding each :harness StreamEvent to the optional block.
Raises CancelledError or DeadlineExceededError when context stops the run; the process is stopped first.