ADR-101: AgentRuntime — the agent-run lifecycle as a public service 

Context 

Persistence (ADR-081), human-in-the-loop approval (ADR-084) and termination semantics (ADR-092) work, but they were assembled inside ToolPlaygroundController: it began the run, built the trace, persisted events, caught the suspension, settled the status and executed the resume. The lifecycle ladder — runLoop → catch suspension → catch guardrail → catch failure → settle completed — was copied three times (batch, resume, stream), and any new consumer (a scheduler task, a queue worker, an editor action) would have had to re-assemble it again, each copy a chance to get the fail-closed rules wrong.

Decision 

AgentRuntimeInterface (Classes/Service/Agent/) is the public application service for agent runs; AgentRuntime implements it and owns the ladder exactly once. The playground controller is now a UI adapter: it parses the request into an AgentRunRequest / ApprovalDecision and maps the returned AgentRunResult onto its JSON / NDJSON shapes, which are unchanged.

interface AgentRuntimeInterface
{
    public function run(AgentRunRequest $request, ?Closure $onStep = null): AgentRunResult;
    public function approve(string $runUuid, ApprovalDecision $decision, ?Closure $onStep = null): AgentRunResult;
    public function cancel(string $runUuid): bool;
    /** @return list<AgentRunEvent> */
    public function events(string $runUuid, int $afterSequence = -1): array;
    public function status(string $runUuid): ?AgentRun;
}

• run() / approve() never throw for a run outcome — the result is already settled, discriminated by AgentRunOutcome (COMPLETED / AWAITING_APPROVAL / SUSPEND_FAILED / GUARDRAIL_BLOCKED / GUARDRAIL_APPROVAL_REQUIRED / FAILED). approve() throws typed AgentRuntimeExceptions only for an invalid request, before any execution: not-awaiting-approval, configuration gone, corrupt state, event position unavailable, claim lost.
• onStep is a live observer fired for each recorded step before it is persisted (preserving the streaming path's emit-before-persist order); the NDJSON stream is built on it.
• The roadmap sketched start(request): handle + run(handle). That split is only real once the request payload is persisted so a different process can execute it — the queue epic. Until then a handle would not be rehydratable, so run() is synchronous begin-and-execute; AgentRunRequest is a plain value object so the queue epic can serialise it and add asynchronous execution without changing these signatures.

Consequences 

• AgentRuntimeInterface is a public DI alias (Category B), raising the audited public-service count from 34 to 35 (later raised to 36 by ADR-106, which makes GuardrailRegistry public for its TCA itemsProcFunc, to 37 by ADR-201, whose UnavailableToolsResolverInterface a consumer looks up in the container by name to feature-detect it — Category B, and to 38 by ADR-206, whose ToolDataHandler every writing tool creates through makeInstance() — Category E). This ADR supersedes ADR-094 as the count authority. It is a consumer interface: call it, do not implement or decorate it outside nr_llm — methods and AgentRunOutcome cases may be added in minor releases (the queue epic will), so exhaustive matches need a default arm. ToolLoopServiceInterface stays public for consumers that want the bare loop; the runtime is the preferred surface.
• nrllm:agent:cancel goes through the runtime; the playground controller lost its ToolLoopService / AgentRunPersister dependencies.
• Breaking: AgentRunPersister::resumeHandle() now returns ?AgentRunHandle (null = refuse the resume), and AgentRunRepositoryInterface gained maxEventSequence().
• Now possible without touching the playground: scheduler and messenger workers, consumer extensions, batch runs, review queues, editor actions and status polling (events() pages by sequence) — the run lifecycle they get is the tested one.