Runtime Package

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

The optional runtime 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 runtime-provided actions such as agent.create

When To Use Runtime

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

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

import { AgentRelay } from '@agent-relay/sdk';
import { createRuntime, registerRuntimeActions } from '@agent-relay/runtime';
import { claude, codex, openclaw } from '@agent-relay/harnesses';

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

const runtime = await createRuntime({
  relay,
  harnesses: {
    claude,
    codex,
    openclaw,
  },
});

registerRuntimeActions(relay.actions, runtime);

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

Runtime Actions

Managed lifecycle should be exposed as actions.

relay.actions.register({
  name: 'agent.create',
  description: 'Create a managed agent session.',
  inputSchema: AgentCreateInput,
  outputSchema: AgentCreateOutput,
  handler: async (input, ctx) => runtime.create(input, ctx),
});

relay.actions.register({
  name: 'agent.release',
  description: 'Release a managed agent session.',
  inputSchema: AgentReleaseInput,
  handler: async (input) => runtime.release(input.sessionId, input.reason),
});

relay.actions.register({
  name: 'agent.status',
  description: 'Read managed session status.',
  inputSchema: AgentStatusInput,
  handler: async (input) => runtime.status(input.sessionId),
});

This keeps agent creation in line with every other capability. Agents call a tool or SDK action; the runtime owns the implementation.

Runtime Is Not Core Messaging

The runtime 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

Runtime:

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

Driver Vocabulary

The lower-level managed harness implementation may still use driver language internally. Public docs should describe the optional package as runtime and the created object as a session.

Use:

• harness for the adapter definition
• session for the created agent boundary
• runtime for optional managed lifecycle
• 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 runtime 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.

Runtime Events

Runtime-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 runtime-managed agents and externally owned agents visible through one listener system.

OpenClaw And ACP Adapters

OpenClaw and ACP bridge support are adapters. They can stay in the repo when they implement the harness/session contract or help a provider join Relay.

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