feat(runtime): add desktop-neutral runtime event contract #96

Merged

lost-rob0t merged 12 commits from feature/runtime-events into master

2026-08-12 15:14:56 +00:00

lost-rob0t commented

2026-08-12 14:56:52 +00:00

(Migrated from github.com)

Closes #82.

Summary

Introduces the first P0 runtime boundary for Zara Desktop without adding Qt to the runtime core.

add provider-neutral runtime event dataclasses with turn/conversation correlation
add an ordered, thread-safe in-process event bus with queue-backed subscriptions
serialize sequence allocation + subscriber enqueue so concurrent publishers cannot reorder envelopes
isolate compatibility sink failures so UI/Pet adapters cannot fail assistant producers
propagate per-turn correlation through AgentManager and LangGraph; existing voice turns reuse their latency trace ID and future RuntimeHost callers can supply the TurnCoordinator ID directly
model assistant deltas, voice states, Prolog/intent results, structured tool lifecycle/approvals, providers, notifications, cancellation and runtime errors
add a pure generic-runtime -> Zarathushtra Pet adapter
make the existing Pet bridge a compatibility transport over the generic event stream while preserving its in-process actor and ZMQ payloads
migrate the LangGraph agent path off direct zara.pets imports
emit an explicit model failure event if provider invocation raises
add focused runtime-event/bus/Pet-adapter tests

Architecture

Agent / Voice / Prolog / Tools
            |
      zara.runtime.events
            |
      RuntimeEventBus
       /           \
Desktop queue   compatibility adapters
                    |
              Zarathushtra Pets
              actor + existing ZMQ

The desktop will consume queue subscriptions in later issues. Runtime publishers never invoke Qt/UI callbacks directly.

Compatibility

zara.pets.runtime_bridge keeps its old function surface for current wake/Pet callers, but each call now publishes a generic runtime event first. Existing Pet event classes and ZMQ names remain intact. The large wake state-machine file is intentionally not rewritten in this PR; its existing Pet bridge calls therefore retain behavior while entering the generic stream.

Existing AgentManager.process_async(...) callers remain source-compatible. It now returns the assigned turn_id in addition to the existing response/tool results.

Testing

New tests cover:

event correlation and validation
sequential and concurrent publisher ordering
lossless default subscriptions and explicit bounded overflow behavior
subscriber close/unsubscribe
compatibility sink failure isolation/idempotent registration
Pet event mappings
response-text truncation
agent model start/complete events carrying turn + conversation correlation
removal of the agent graph's direct Pet dependency

GitHub Actions / scripts/test-all.sh is the authoritative merge gate because the local /home/unseen/Documents/Projects working tree is not mounted in this execution environment.

Closes #82. ## Summary Introduces the first P0 runtime boundary for Zara Desktop without adding Qt to the runtime core. - add provider-neutral runtime event dataclasses with turn/conversation correlation - add an ordered, thread-safe in-process event bus with queue-backed subscriptions - serialize sequence allocation + subscriber enqueue so concurrent publishers cannot reorder envelopes - isolate compatibility sink failures so UI/Pet adapters cannot fail assistant producers - propagate per-turn correlation through `AgentManager` and LangGraph; existing voice turns reuse their latency trace ID and future RuntimeHost callers can supply the `TurnCoordinator` ID directly - model assistant deltas, voice states, Prolog/intent results, structured tool lifecycle/approvals, providers, notifications, cancellation and runtime errors - add a pure generic-runtime -> Zarathushtra Pet adapter - make the existing Pet bridge a compatibility transport over the generic event stream while preserving its in-process actor and ZMQ payloads - migrate the LangGraph agent path off direct `zara.pets` imports - emit an explicit model failure event if provider invocation raises - add focused runtime-event/bus/Pet-adapter tests ## Architecture ```text Agent / Voice / Prolog / Tools | zara.runtime.events | RuntimeEventBus / \ Desktop queue compatibility adapters | Zarathushtra Pets actor + existing ZMQ ``` The desktop will consume queue subscriptions in later issues. Runtime publishers never invoke Qt/UI callbacks directly. ## Compatibility `zara.pets.runtime_bridge` keeps its old function surface for current wake/Pet callers, but each call now publishes a generic runtime event first. Existing Pet event classes and ZMQ names remain intact. The large wake state-machine file is intentionally not rewritten in this PR; its existing Pet bridge calls therefore retain behavior while entering the generic stream. Existing `AgentManager.process_async(...)` callers remain source-compatible. It now returns the assigned `turn_id` in addition to the existing response/tool results. ## Testing New tests cover: - event correlation and validation - sequential and concurrent publisher ordering - lossless default subscriptions and explicit bounded overflow behavior - subscriber close/unsubscribe - compatibility sink failure isolation/idempotent registration - Pet event mappings - response-text truncation - agent model start/complete events carrying turn + conversation correlation - removal of the agent graph's direct Pet dependency GitHub Actions / `scripts/test-all.sh` is the authoritative merge gate because the local `/home/unseen/Documents/Projects` working tree is not mounted in this execution environment.