Harness Driver Package

Use the optional harness driver package when Agent Relay needs to manage session lifecycle, logs, readiness, and driver-provided actions.

Core Agent Relay owns messaging, delivery contracts, actions, and events — not spawning.

@agent-relay/harness-driver is the client SDK for the broker-pty-engine — the generic PTY engine inside the broker that spawns and owns agent processes. A caller uses it to spawn a PTY and drive it. It is used inside an action runner: when a node's spawn capability fires, the action runner resolves the harness that capability declares and calls the harness driver to start it, while the broker-pty-engine hosts the PTY. It is not a standalone service.

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.

registerDriverActions(actions, driver) takes an AgentRelayActions registry, not the AgentRelay facade. Pass the same registry to createWorkspace so the actions register on the relay (and relay.action(...) listeners fire):

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

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

// 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(actions, driver);

The package is optional by design: sending messages and registering actions with the core SDK pulls in no PTY, process management, browser, cloud, or workflow dependencies.

Harness driver actions

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

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

registerDriverActions(actions, 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 uses the same Relay workspace but does 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

  • harness — the adapter definition
  • session — the created agent boundary
  • harness driver — the optional managed lifecycle package
  • action — an agent-callable managed operation

Whether a provider runs in a PTY, headless mode, app-server mode, or attached mode only matters when configuring that harness directly.

CLI Shape

Managed session lifecycle lives under the node agent command group:

agent-relay workspace create release-review
agent-relay node agent spawn codex --channels reviews
agent-relay node agent list
agent-relay node agent release <agent>

See Agent management for the full flag set.

Harness driver events

Harness-driver-managed sessions 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.

External Adapters

An external adapter joins Relay by implementing the harness/session contract (see Harnesses). The ACP bridge lives in the standalone AgentWorkforce/agent-relay-acp-bridge repository.