P0 — add RuntimeHost and Qt-safe application command bridge #83

New issue

Closed

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

lost-rob0t commented

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

(Migrated from github.com)

Motivation

The desktop GUI must control the existing Zara runtime without invoking AgentManager, Prolog, voice, or tools directly from Qt widgets. The Qt main thread also must never own blocking assistant work.

Scope

Introduce a desktop-neutral application command vocabulary such as SubmitTurn, CancelTurn, StartVoice, StopVoice, MuteSpeech, and runtime shutdown/restart requests.
Add a RuntimeHost lifecycle boundary that owns Zara application services off the GUI thread.
Run/own the runtime asyncio loop on a dedicated runtime thread or equivalent isolated execution context.
Add a Qt-safe bridge adapter using queued signals/slots only at the desktop edge.
Route cancellation through the existing turn coordinator.
Define startup/readiness/error/shutdown semantics.
Preserve headless CLI operation.

Architecture

Qt main thread
    |
queued commands/events
    |
RuntimeHost worker thread
    |
Zara runtime / actors / asyncio / Prolog / tools

The zara.runtime layer remains Qt-neutral. The Qt adapter belongs under zara.desktop.

Acceptance criteria

Widgets can submit/cancel work through a command interface without direct low-level runtime access.
Runtime work does not execute synchronously on the Qt main thread.
Runtime readiness and failures arrive as structured events from #82.
Runtime shutdown drains/cancels active work and terminates cleanly.
Cancellation is idempotent and turn-scoped.
Stale results cannot update a newer turn.
Headless modes continue to operate without importing Qt.
Runtime host code does not require a running QApplication.

Testing requirements

Deterministic fake-runtime tests for command submission and event delivery.
Thread-affinity tests proving blocking runtime work is not executed on the GUI thread.
Cancellation and stale-event tests.
Startup failure and shutdown tests.
Full repository/Nix test suite.

Dependencies

#82 runtime event contract.
Design: #81.

Explicit non-goals

No tray or visual chat widgets.
No new IPC daemon/supervisor.
No rewrite of providers or Prolog.
No replacement of the existing headless CLI lifecycle.
No requirement to move the whole runtime onto QtAsyncio.

## Motivation The desktop GUI must control the existing Zara runtime without invoking `AgentManager`, Prolog, voice, or tools directly from Qt widgets. The Qt main thread also must never own blocking assistant work. ## Scope - Introduce a desktop-neutral application command vocabulary such as `SubmitTurn`, `CancelTurn`, `StartVoice`, `StopVoice`, `MuteSpeech`, and runtime shutdown/restart requests. - Add a `RuntimeHost` lifecycle boundary that owns Zara application services off the GUI thread. - Run/own the runtime asyncio loop on a dedicated runtime thread or equivalent isolated execution context. - Add a Qt-safe bridge adapter using queued signals/slots only at the desktop edge. - Route cancellation through the existing turn coordinator. - Define startup/readiness/error/shutdown semantics. - Preserve headless CLI operation. ## Architecture ```text Qt main thread | queued commands/events | RuntimeHost worker thread | Zara runtime / actors / asyncio / Prolog / tools ``` The `zara.runtime` layer remains Qt-neutral. The Qt adapter belongs under `zara.desktop`. ## Acceptance criteria - [ ] Widgets can submit/cancel work through a command interface without direct low-level runtime access. - [ ] Runtime work does not execute synchronously on the Qt main thread. - [ ] Runtime readiness and failures arrive as structured events from #82. - [ ] Runtime shutdown drains/cancels active work and terminates cleanly. - [ ] Cancellation is idempotent and turn-scoped. - [ ] Stale results cannot update a newer turn. - [ ] Headless modes continue to operate without importing Qt. - [ ] Runtime host code does not require a running `QApplication`. ## Testing requirements - Deterministic fake-runtime tests for command submission and event delivery. - Thread-affinity tests proving blocking runtime work is not executed on the GUI thread. - Cancellation and stale-event tests. - Startup failure and shutdown tests. - Full repository/Nix test suite. ## Dependencies - #82 runtime event contract. - Design: #81. ## Explicit non-goals - No tray or visual chat widgets. - No new IPC daemon/supervisor. - No rewrite of providers or Prolog. - No replacement of the existing headless CLI lifecycle. - No requirement to move the whole runtime onto QtAsyncio.