Agent Harness

The agent harness is the executor the runtime uses for a run. In holaOS, the harness is an important subsystem, but it is not the whole system. The runtime owns the environment contract around it: workspace structure, capability projection, continuity artifacts, app orchestration, and the reduced execution package passed into the harness.

Where it sits

1. The workspace holds the authored inputs such as workspace.yaml, AGENTS.md, installed app manifests, and skills.
2. The runtime compiles that into per-run state: prompt layers, selected model configuration, MCP tool visibility, attachments, and a workspace checksum.
3. The harness host invokes the selected agent harness.
4. The harness executes the run and emits normalized lifecycle events back into the runtime path.

The harness sits inside the runtime execution boundary. It does not sit beside the workspace, and it does not replace the runtime.

Why the harness is interchangeable

holaOS does not hard-code one harness as the whole system contract. Instead, the runtime defines a stable boundary around the harness so different executors can fit into the same environment model.

That means the harness can, in principle, be swapped for other agent runtimes such as:

• OpenCode
• Codex
• Claude Code
• Hermes Agent
• OpenClaw
• another future harness that can satisfy the same contract

The important point is not the specific brand of harness. The important point is that the workspace model, runtime state, memory behavior, and capability projection do not have to be redefined every time the executor changes.

What the runtime contract provides

Today the runtime prepares a harness request that includes:

• workspace and session identity
• the current instruction and input attachments
• selected model and provider configuration
• composed system prompt and runtime context
• workspace skill directories
• resolved MCP servers and tool references
• workspace configuration checksum
• run lifecycle metadata

The harness receives a reduced execution package, not the whole raw system.

What a harness implementation must provide

The current runtime split has two layers:

Runtime adapterdefinition in runtime/harnesses

Declares capabilities, runner prep behavior, how to build the harness request, and how the runtime checks readiness.

Harness host plugindefinition in runtime/harness-host

Decodes the prepared request and actually executes the harness command, returning normalized lifecycle events to the runtime.

That split is what makes interchangeability practical instead of theoretical.

Normalized run lifecycle

The runtime boundary is not just about input shape. It also normalizes the main run lifecycle back out of the harness.

Current runner event types include:

• run_claimed
• run_started
• thinking_delta
• output_delta
• tool_call
• skill_invocation
• auto_compaction_start
• auto_compaction_end
• run_completed
• run_failed

That lets the runtime and desktop observe runs without depending on one harness's native event format.

Current implementation

Today the OSS repo ships a single harness path: pi.

That path is currently implemented through:

• runtime/harnesses/ for the harness definition
• runtime/harness-host/ for the host CLI and plugin execution
• a Pi-based executor underneath that path

In practical terms, the currently shipped harness is built on top of Pi Mono and registered as the pi harness. The important design choice is that the runtime boundary around it is intentionally broader than Pi itself.

What stays stable even if the harness changes

• the workspace contract
• the runtime-owned state store and continuity model
• MCP and capability projection per run
• app lifecycle and integration resolution
• the desktop as a product surface on top of the environment

Changing the harness should change the executor, not the definition of holaOS.