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 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.

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 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 (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 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

Managed session lifecycle lives under the local agent command group:

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

See Agent management for the full flag set.

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.

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. Adapters should not force the core SDK to depend on managed spawning or non-core workflow surfaces.