P0 — promote a desktop-neutral runtime event contract #82

New issue

Closed

opened 2026-08-12 14:40:41 +00:00 by lost-rob0t · 0 comments

lost-rob0t commented

2026-08-12 14:40:41 +00:00

(Migrated from github.com)

Motivation

Zara already has useful typed turn events in zara.actors and provider-neutral UI events in zara.pets.events, but core agent code currently imports the pet-specific runtime bridge. A desktop Copilot should consume stable application events without making the runtime depend on any particular UI surface.

This is the first architectural slice from #81 and must land before Qt widgets are wired to runtime internals.

Scope

Introduce a desktop-neutral runtime event vocabulary under an appropriate zara.runtime boundary.
Reuse existing TurnCoordinator turn IDs and cancellation semantics rather than inventing parallel turn state.
Cover lifecycle, assistant generation, voice state, intent/Prolog results, tool lifecycle, provider availability, notifications, cancellation, and runtime errors at the schema level.
Define conversation/turn correlation and event ordering metadata where needed.
Add an adapter so Zarathushtra Pets can consume generic runtime events.
Remove direct core-agent dependence on zara.pets.runtime_bridge for the migrated paths.
Preserve standalone Pet ZMQ compatibility through an adapter/transport rather than making ZMQ the canonical event definition.

Architecture

Runtime components publish typed provider-neutral domain events. Consumers subscribe through a narrow runtime boundary. Desktop and Pets are peer consumers.

Agent / Voice / Prolog / Tools
            |
      Runtime events
            |
      +-----+-----+
      |           |
   Desktop       Pets

Do not make Qt a dependency of this issue.

Acceptance criteria

Generic runtime event types exist outside zara.pets.
Turn-scoped events carry the canonical turn ID.
Events needed for assistant, tool, voice, provider, cancellation, notification and runtime-error state are modeled explicitly.
Existing Pet behavior can be driven through an adapter from the generic events.
Migrated core runtime paths no longer import zara.pets.runtime_bridge directly.
Cancellation/stale-turn guarantees from TurnCoordinator remain intact.
No provider-specific objects leak into the public desktop/runtime event schema.
Existing headless modes continue to work.

Testing requirements

Unit tests for all event schemas and validation/conversion.
Tests proving the Pet adapter maps generic runtime events to existing Pet states/events.
Tests proving event handling does not resurrect cancelled/stale turns.
Tests for subscriber/adapter failure isolation where applicable.
Run the full repository test suite and Nix checks required by project policy.

Dependencies

Existing zara.actors.TurnCoordinator and current master.
Design: #81.

Explicit non-goals

No Qt windows or tray.
No new desktop process supervisor.
No desktop-only LLM client.
No rewrite of wake/STT/TTS.
No replacement of Pykka.
No removal of standalone zara-pets compatibility.

## Motivation Zara already has useful typed turn events in `zara.actors` and provider-neutral UI events in `zara.pets.events`, but core agent code currently imports the pet-specific runtime bridge. A desktop Copilot should consume stable application events without making the runtime depend on any particular UI surface. This is the first architectural slice from #81 and must land before Qt widgets are wired to runtime internals. ## Scope - Introduce a desktop-neutral runtime event vocabulary under an appropriate `zara.runtime` boundary. - Reuse existing `TurnCoordinator` turn IDs and cancellation semantics rather than inventing parallel turn state. - Cover lifecycle, assistant generation, voice state, intent/Prolog results, tool lifecycle, provider availability, notifications, cancellation, and runtime errors at the schema level. - Define conversation/turn correlation and event ordering metadata where needed. - Add an adapter so Zarathushtra Pets can consume generic runtime events. - Remove direct core-agent dependence on `zara.pets.runtime_bridge` for the migrated paths. - Preserve standalone Pet ZMQ compatibility through an adapter/transport rather than making ZMQ the canonical event definition. ## Architecture Runtime components publish typed provider-neutral domain events. Consumers subscribe through a narrow runtime boundary. Desktop and Pets are peer consumers. ```text Agent / Voice / Prolog / Tools | Runtime events | +-----+-----+ | | Desktop Pets ``` Do not make Qt a dependency of this issue. ## Acceptance criteria - [ ] Generic runtime event types exist outside `zara.pets`. - [ ] Turn-scoped events carry the canonical turn ID. - [ ] Events needed for assistant, tool, voice, provider, cancellation, notification and runtime-error state are modeled explicitly. - [ ] Existing Pet behavior can be driven through an adapter from the generic events. - [ ] Migrated core runtime paths no longer import `zara.pets.runtime_bridge` directly. - [ ] Cancellation/stale-turn guarantees from `TurnCoordinator` remain intact. - [ ] No provider-specific objects leak into the public desktop/runtime event schema. - [ ] Existing headless modes continue to work. ## Testing requirements - Unit tests for all event schemas and validation/conversion. - Tests proving the Pet adapter maps generic runtime events to existing Pet states/events. - Tests proving event handling does not resurrect cancelled/stale turns. - Tests for subscriber/adapter failure isolation where applicable. - Run the full repository test suite and Nix checks required by project policy. ## Dependencies - Existing `zara.actors.TurnCoordinator` and current master. - Design: #81. ## Explicit non-goals - No Qt windows or tray. - No new desktop process supervisor. - No desktop-only LLM client. - No rewrite of wake/STT/TTS. - No replacement of Pykka. - No removal of standalone `zara-pets` compatibility.