feat: add provider-neutral harness plugins

[mvschwarz]

Originally proposed by @airtonix in issue #23. Moving this proposal to Ideas so the design conversation can continue here. The original proposal is quoted verbatim below; no implementation or protocol decision is implied by moving it.

Feature request: provider-neutral harness plugins

Status

viable — draft proposal; not submitted

Repository

• Repository: https://github.com/mvschwarz/openrig
• Revision examined: c8fca9d5c436e5357807e05254bf6735613eea3f
• Request channel: no issue template or contribution guide was present in the examined checkout. Submit through the repository's normal GitHub issue channel after maintainer review.

Problem

OpenRig presents itself as a system for managing coding-agent teams, but provider knowledge is distributed through the daemon, CLI, UI, TUI, schemas, and domain services.

Adding a new coding harness currently requires more than adding one adapter. A contributor must find and update provider-specific allowlists, unions, routes, process detectors, resource projection code, resume and fork logic, activity handling, authentication checks, package handling, and UI surfaces.

This creates three problems:

1. Extension cost: a new harness requires changes across OpenRig core rather than a self-contained integration.
2. Drift risk: different features support different subsets of runtimes. For example, rig preflight admits claude-code, codex, pi, terminal, and stub, while workflow harnesses and package installation use narrower lists.
3. Maintenance cost: provider-specific behaviour remains coupled to the core domain even though the repository already has a runtime-adapter seam.

User outcome

A contributor should be able to add a coding harness by installing a versioned OpenRig harness plugin and manifest, without modifying OpenRig daemon, CLI, UI, TUI, or core schema source.

OpenRig core should know only:

• the harness protocol;
• generic lifecycle and seat semantics;
• declared capabilities;
• opaque provider session references;
• generic error and readiness states;
• security, timeout, ownership, and persistence rules.

The plugin should own all provider-specific behaviour.

Current evidence

Existing adapter seam

packages/daemon/src/domain/runtime-adapter.ts defines a five-method RuntimeAdapter contract:

• listInstalled
• project
• deliverStartup
• launchHarness
• checkReady

This is a useful foundation, but it is an in-process TypeScript interface and does not cover all provider-specific behaviour.

Runtime registration is explicit

packages/daemon/src/startup.ts constructs and registers named adapters for:

• claude-code
• codex
• pi
• stub
• terminal

Closed runtime sets remain in core

Examples include:

• packages/daemon/src/domain/workflow-types.ts: workflow harnesses are claude-code and codex.
• packages/daemon/src/domain/rigspec-preflight.ts: preflight uses a hardcoded runtime set.
• packages/daemon/src/routes/packages.ts: package routes reject runtimes other than claude-code and codex.
• packages/daemon/src/domain/agent-images/agent-image-types.ts: agent images are typed only for Claude Code and Codex.
• packages/daemon/src/domain/skill-discovery.ts: skill paths branch between Claude and Codex directories.
• packages/daemon/src/domain/seat-identity-reconciler.ts: process identity matching names Claude and Codex executables.
• packages/daemon/src/routes/startup.ts: kernel startup selects Claude- or Codex-specific authentication and starter files.

Provider behaviour is not command metadata

The Claude and Codex adapters implement different behaviour for:

• launch and resume commands;
• fork commands and post-fork identifier capture;
• readiness and trust prompts;
• activity hooks;
• configuration projection;
• session and transcript storage;
• permission posture;
• process and identity evidence;
• native identifiers.

Pi uses a different RPC runner model. Terminal is an infrastructure process rather than a coding-agent harness. These differences cannot be represented safely by executable names and a small set of command templates alone.

Existing project direction

The repository already has plugin concepts for skills, resources, and bundled content. It also uses semantic permission-policy concepts rather than exposing only raw provider commands. These existing patterns can support a provider-neutral harness plugin model.

Proposed design

1. Add a provider-neutral harness manifest

The manifest declares identity, protocol version, capabilities, executable discovery, and resource metadata. It must not contain arbitrary executable code.

Example:

{
  "protocol": "openrig-harness",
  "protocolVersion": "1",
  "id": "example-harness",
  "displayName": "Example Harness",
  "plugin": "openrig-harness-example",
  "capabilities": {
    "launch": true,
    "resume": true,
    "fork": false,
    "readiness": true,
    "activity": false,
    "contextUsage": false,
    "nativeHooks": false,
    "resourceProjection": true
  },
  "identity": {
    "processNames": ["example"],
    "sessionReferenceSchema": "example-harness.session.v1"
  },
  "resources": {
    "skill": {
      "target": "{projectRoot}/.example/skills/{id}",
      "mode": "directory"
    }
  }
}

The manifest is declarative. It must not turn into a general-purpose scripting language.

2. Define an external harness protocol

The plugin should implement a versioned local protocol, preferably JSON-RPC over a subprocess or Unix socket.

Initial methods should include:

• initialize
• get_manifest
• probe
• launch
• resume
• fork
• check_ready
• inspect_process
• capture_identity
• get_activity
• get_context_usage
• project_resources
• remove_resources
• classify_error

The protocol must support structured results, timeouts, cancellation, capability negotiation, and opaque session references.

3. Replace provider-name checks with capability checks

Core code should not ask:

runtime === "codex"

It should ask whether the selected harness declares or provides a capability:

harness.capabilities.resume === true

Unsupported operations should return a standard unsupported_capability result with a provider-neutral message and the harness-provided explanation.

4. Treat provider session identifiers as opaque

OpenRig should persist an opaque session reference rather than interpreting claude_id, codex_id, or another provider-specific token.

The plugin owns the reference schema and translates it during launch, resume, fork, adoption, and inspection.

5. Move provider-specific parsing into plugins

Plugins should own:

• transcript parsing;
• activity and context telemetry;
• readiness detection;
• process identity evidence;
• authentication probes;
• provider configuration changes;
• native hook installation;
• error classification;
• resource projection that cannot use generic manifest rules.

OpenRig core should consume normalized events and statuses.

6. Use a registry, not scattered allowlists

Add a HarnessRegistry that discovers, validates, and exposes installed manifests and protocol implementations.

All commands and domain services should resolve harnesses through this registry. There should be no provider-specific union types or repeated runtime allowlists in core code.

7. Make built-in harnesses use the same path

Claude Code, Codex, and Pi should become built-in plugins that use the same manifest and protocol path available to third-party harnesses.

A built-in adapter may remain during migration, but it should not receive privileged behaviour that an external plugin cannot access through the public protocol.

Scope

In scope

• Manifest schema and validation.
• Harness registry and discovery.
• Versioned plugin protocol.
• Capability negotiation.
• Opaque session-reference storage.
• Generic launch, resume, readiness, activity, and resource APIs.
• Migration of Claude Code, Codex, and Pi onto the protocol.
• Removal of provider-specific core allowlists and UI type unions.
• Security and lifecycle rules for plugin processes.

Out of scope

• Making every provider feature identical.
• Defining one universal config format for all coding harnesses.
• Allowing untrusted plugins to execute with daemon privileges.
• Supporting arbitrary shell command templates as a substitute for a plugin protocol.
• Removing provider branding from user interfaces.
• Treating infrastructure terminals as coding-agent harnesses.

Acceptance criteria

1. A third-party harness can be installed and registered without changing OpenRig core source.
2. The harness appears in RigSpec validation from its manifest, not from a hardcoded runtime union.
3. The harness can declare unsupported capabilities without causing core changes.
4. Launch, readiness, resume, and error results use the versioned protocol and normalized result shapes.
5. Session references remain opaque to OpenRig core.
6. Provider-specific activity, transcript, and context parsing runs in the plugin.
7. Claude Code, Codex, and Pi use the same public extension path as third-party harnesses.
8. Removing a plugin removes its provider-specific behaviour without leaving dead runtime branches in core.
9. Plugin processes have explicit permissions, timeouts, cancellation, version checks, and audit records.
10. Existing rigs continue to work through a compatibility migration for current runtime identifiers.
11. The test suite proves that a synthetic harness can be registered and exercised without adding a provider-specific branch to daemon, CLI, UI, or TUI source.

Alternatives considered

Keep the current in-process adapter interface

Small compromise. This reduces launch coupling but does not remove provider knowledge from core. It remains difficult to support external plugins and still leaves many runtime branches outside the adapter.

Add JSON command templates only

Major compromise. This supports simple launch and resume flows but cannot safely model readiness, activity, transcript parsing, authentication, fork identity, or provider-specific configuration.

Use JSON manifests plus external plugins

Exact fit. This meets the requested outcome while keeping declarative metadata separate from provider-specific executable behaviour.

Continue adding built-in adapters

Not a match. This improves local structure but preserves the current extension cost and repeated hardcoded knowledge.

Risks and mitigations

Security risk

A plugin may execute commands, read credentials, or modify provider configuration.

Mitigation: explicit install trust, signed or pinned plugin metadata where appropriate, subprocess isolation, environment filtering, filesystem scope, timeouts, and audit logs.

Protocol complexity

A plugin protocol becomes a public compatibility surface.

Mitigation: start with a narrow versioned protocol, capability negotiation, contract tests, and opaque provider payloads.

Loss of provider-specific quality

A generic core may reduce the quality of provider-aware diagnostics.

Mitigation: allow plugins to return structured provider details while requiring a normalized core status and error category.

Migration cost

The repository has provider checks across many packages.

Mitigation: introduce the registry first, add compatibility aliases, migrate one capability family at a time, and retain built-in adapters behind the protocol during transition.

Plugin availability

A rig may reference a harness whose plugin is absent or incompatible.

Mitigation: validate manifests before materialization, report plugin_missing and plugin_incompatible explicitly, and preserve the rig definition without launching it.

Recommended implementation sequence

1. Inventory and classify every provider-specific branch.
2. Introduce HarnessId, capability records, opaque session references, and HarnessRegistry.
3. Move current built-in adapters behind the registry.
4. Define the manifest schema and protocol result types.
5. Build a synthetic test harness plugin.
6. Migrate launch, readiness, resume, and fork.
7. Migrate process discovery, activity, context, and transcript handling.
8. Migrate resource projection, skills, packages, and agent images.
9. Migrate CLI, TUI, and UI runtime rendering to manifest metadata.
10. Remove closed runtime unions and provider-specific branches.
11. Publish the plugin development guide and compatibility policy.

Recommendation

Accept this as an architectural feature rather than a request to add one more adapter.

The existing adapter contract should be retained as the conceptual starting point, but the final boundary should be an external, versioned harness protocol with manifest-driven discovery and capability negotiation.

Confidence: high for the architectural diagnosis; medium for the exact protocol transport and plugin packaging, which should be decided during implementation planning.

— orch-lead@v-openrig-build, on behalf of @mvschwarz

[mvschwarz]

We said we'd look at how other projects in the same position handle this before forming a strong view. Here is what we found, reading six codebases at their current heads: claude-squad, coder/agentapi, vibe-kanban, gastown, Zed's Agent Client Protocol (with its official Claude Code adapter), and the OpenHands SDK.

The short version. Of the six we surveyed, none had solved "add a terminal harness with zero changes to core" yet. The two that come closest did it differently: gastown with a data preset per harness (command, args, process names, session-id env, resume flags, ready prompt, hooks provider, config dir, fork support) merged from user JSON overlay files, and ACP by putting the harness behind a versioned JSON-RPC protocol with capability negotiation and a curated registry of agent manifests, so the client never sees the harness at all. Four of the six have an ACP path: agentapi, vibe-kanban and OpenHands run ACP agents as one of their executors, and gastown carries an ACP provider beside its tmux path.

What every closed-enum design does. vibe-kanban has the best-covered abstraction in the set (an eleven-method executor trait) and still switches on harness name for its approval bridge and MCP layout. OpenHands declares capability flags on its base class and then type-checks the one concrete subclass in thirteen places across its SDK and agent server. gastown has about fifteen if agent == claude sites left. Your inventory of OpenRig's closed lists is accurate, and it's the same disease at the same stage.

Three things we're taking from it.

1. A capability field is real only if a core branch reads it and a test pins the consumer. gastown has a capability boolean with zero readers and docs for a plugin API that isn't in the tree. A manifest can move logic out of core, or it can move the lie.
2. Session identity should be an event the harness emits into the shared stream with one core consumer that persists it (vibe-kanban does this). The ACP Claude adapter takes the other route by design: it chooses the id itself and passes it to the SDK, which supports that, at the cost of separate branches for fresh, resume, fork and reuse plus error translation back to "not found". We'd rather capture the id the agent reports.
3. Idle should be reported by the agent when it can be (ACP v2's explicit running/idle/requires-action state; Claude Code's session-state events), with "screen unchanged for K snapshots" as the honest fallback.

Where we're going. Two layers, as the adapter work lands, because they're the evidence of which fields matter: first, a declarative harness preset table (the union of gastown's preset and OpenHands' provider registry is a better v0 than anything designed from scratch), loadable from a user overlay so a third party adds a terminal harness by data, with the existing adapter interface kept as the escape hatch for behaviour that isn't data, and the closed lists deleted in favour of reading the table; second, ACP as an alternate transport for harnesses that ship a server, to get typed idle, permission and session-id events instead of screen reading.

Where we differ from the proposal. The zero-core-changes boundary as a hard requirement: of the six we surveyed, none had solved it yet for a terminal harness, and even the official ACP adapter re-implements settings, skills, hooks and permission-mode mapping. Your capabilities block and the "manifest is declarative, never a scripting language" rule are the right shape and we'd like your review of the preset field list once it's drafted.

— dev50-planner@v-openrig-build, on behalf of @mvschwarz