Harness Driver Package

Core Agent Relay does not need to own spawning. It owns messaging, delivery contracts, actions, and events.

The optional harness driver package owns managed session lifecycle:

• create sessions
• release sessions
• attach to existing sessions
• resume or fork when supported
• track readiness and idle state
• collect logs and terminal output
• bridge PTY, headless, app-server, or provider SDK details
• register driver-provided actions such as agent.create

When To Use The Harness Driver

Use only the core SDK when your app already owns the agent process or can embed Relay directly.

Use the harness driver package when Agent Relay should manage the harness boundary for you.

import { AgentRelay } from '@agent-relay/sdk';
import { BrokerDriver, registerDriverActions } from '@agent-relay/harness-driver';

const relay = await AgentRelay.createWorkspace({ name: 'release-review' });

// The driver owns the managed harness boundary: broker startup, PTY/headless
// spawn, release, and status.
const driver = new BrokerDriver();

// Expose that lifecycle as actions (agent.create, agent.release, agent.status).
registerDriverActions(relay, driver);

The harness driver package should be optional. An SDK user should not pull in PTY, process management, browser, cloud, workflow, or proactive runtime dependencies just to send messages or register actions.

Harness driver actions

Managed lifecycle is exposed as actions. registerDriverActions registers agent.create, agent.release, and agent.status against any AgentDriver, so callers create and release managed agents the same way they invoke any other action.

import { registerDriverActions } from '@agent-relay/harness-driver';

registerDriverActions(relay, driver);

// An agent invokes `agent.create` through its MCP tools. Like every action it is
// fire-and-forget: the call returns an acknowledgement and the driver emits
// `action.completed` when the session is up. React with a listener.
relay.addListener(relay.action('agent.create').completed(), (event) => {
  console.log('spawned', event.output);
});

relay.addListener(relay.action('agent.create').failed(), (event) => {
  console.error('spawn failed', event.error);
});

Pass { actionPrefix } to registerDriverActions to namespace the actions, and provide any AgentDriver implementation; BrokerDriver is the built-in one that manages a local broker.

This keeps agent creation in line with every other capability. Agents call a tool; the harness driver owns the implementation and reports the result through action.completed.

The Harness Driver Is Not Core Messaging

The harness driver may use the same Relay workspace, but it should not define the core communication API.

Core:

• workspace creation and connection
• agent registration
• channels, DMs, threads, reactions, attachments, inboxes
• delivery contracts and receipts
• action registry and invocation
• event subscriptions
• MCP tool generation

Harness driver:

• process or session lifecycle
• PTY and headless details
• app-server attachment
• readiness and idle detection
• logs, terminal snapshots, transcript adapters
• managed delivery adapters
• driver-specific action implementations

Driver Vocabulary

The package name is the harness driver. Public docs describe the optional package as the harness driver and the created object as a session.

Use:

• harness for the adapter definition
• session for the created agent boundary
• harness driver for the optional managed lifecycle package
• action for agent-callable managed operations

Avoid making users learn whether a provider is running in a PTY, headless mode, app-server mode, or attached mode unless they are configuring that harness directly.

CLI Shape

The CLI should expose harness driver lifecycle as an optional group instead of making it the core product.

agent-relay workspace create release-review
agent-relay mcp start --workspace "$RELAY_WORKSPACE_KEY"
agent-relay driver create reviewer --harness codex --channel '#reviews'
agent-relay driver status reviewer
agent-relay driver release reviewer

If the implementation still uses driver as the command group, the docs should explain it as a managed session harness command, not as the central broker.

Harness driver events

Harness-driver-managed sessions should emit the same normalized session events as any other harness:

• session.started
• status.changed
• tool.called
• tool.completed
• transcript.chunk
• terminal.output
• file.changed
• delivery.delivered
• session.released

This keeps harness-driver-managed agents and externally owned agents visible through one listener system.

OpenClaw And External Adapters

OpenClaw can stay in the repo as an adapter when it implements the harness/session contract or helps a provider join Relay. The ACP bridge lives in the standalone AgentWorkforce/agent-relay-acp-bridge repository.

Adapters should not force the core SDK to depend on managed spawning or non-core workflow surfaces.