# Class LittleGhost::Harnesses::Base

Documentation version: Edge

Canonical HTML: https://littleghostai.org/docs/LittleGhost/Harnesses/Base.html

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.

## Inheritance

`LittleGhost::Harnesses::Base < Object`

## Attributes

<a id="attribute-i-defaults"></a>
### `defaults` (R)

Frozen harness-specific settings.

<a id="attribute-i-executable"></a>
### `executable` (R)

Executable path or command name.

<a id="attribute-i-home"></a>
### `home` (R)

Home directory as the child sees it: the persistent home, the run's temporary
home while #run or #probe works, or nil.

<a id="attribute-i-home_root"></a>
### `home_root` (R)

Workspace path name for temporary homes, or nil.

<a id="attribute-i-mode"></a>
### `mode` (R)

`:isolated` or `:native_guards`.

<a id="attribute-i-sandbox"></a>
### `sandbox` (R)

Sandbox or Sandbox::Scope that runs the tool, or nil for the host.

## Class methods

<a id="method-c-default_executable"></a>
### `.default_executable`

```ruby
default_executable()       -> String
default_executable(value)  -> value
```

Command name used when an application does not configure a path.

<a id="method-c-harness_id"></a>
### `.harness_id`

```ruby
harness_id()       -> Symbol
harness_id(value)  -> value
```

Identifier used in events and results.

<a id="method-c-new"></a>
### `.new`

```ruby
.new(sandbox: nil, home: nil, executable: self.class.default_executable, defaults: {}, home_root: nil,
        mode: nil)
```

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 Sandbox is the boundary, so the tool's own approval prompts and
    command sandbox are turned off and it receives the placeholder key.
    Requires a Sandbox that reports isolation and does not inherit the host
    network; any other Sandbox raises ConfigurationError.

`: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;
    LittleGhost never 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.

<a id="method-c-supported_versions"></a>
### `.supported_versions`

```ruby
supported_versions()                 -> Gem::Requirement
supported_versions(*requirements)    -> Gem::Requirement
```

Tool versions whose command line and output this harness understands.

## Instance methods

<a id="method-i-command"></a>
### `#command`

```ruby
#command(request)
```

Returns the command line for `request`, beginning with #executable.

<a id="method-i-environment"></a>
### `#environment`

```ruby
#environment(request)
```

Returns child-process variables for `request`. Defaults and the request's own
`environment` are merged over this Hash.

<a id="method-i-finalize"></a>
### `#finalize`

```ruby
#finalize(state, exit_code:, stderr_tail:, outcome:)
```

Builds the Result. `outcome` is `:timed_out`,
`:budget_exceeded`, `:turns_exceeded`, or
`:failed` when #run stopped the process, and nil when the process
ended on its own.

<a id="method-i-harness_id"></a>
### `#harness_id`

```ruby
#harness_id()
```

Identifier used in events and results.

<a id="method-i-isolated-3F"></a>
### `#isolated?`

```ruby
#isolated?()
```

Whether the Sandbox is the boundary and the tool's own safeguards are off.

<a id="method-i-parse_line"></a>
### `#parse_line`

```ruby
#parse_line(line, state)
```

Records progress from one output `line` in `state` and returns an Array of
event Hashes.

<a id="method-i-probe"></a>
### `#probe`

```ruby
#probe(context: nil, timeout: 30)
```

Runs `executable --version` in the sandbox and returns a Hash with
`:available`, `:version`, `:supported`, and
`:reason`.

<a id="method-i-run"></a>
### `#run`

```ruby
#run(request, context: nil, &block)
```

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.
