App Flow and Layer Boundaries

AppOrchestrator owns the flows the app moves through — opening a project, entering an interaction, handing over, leaving. That makes it the top of the dependency graph: it composes the conversation, visual, camera and authentication managers and sequences them.

The UI is the top of the runtime graph. It is what the user drives, and every flow has to be visible.

Whichever way those two are stacked, the one underneath has to reach up. That is the whole problem, and it is structural — not untidiness to be cleaned up in passing.

The symptom is that the reach-up gets faked. OrchestrationRequested is a nine-case event that exists only because Promethist.UI and Promethist.Conversation cannot call AppOrchestrator. And because Core.Events sits below the key types in App.State, that event cannot carry a ProjectKey or an AgentKey: every publisher stringifies (key.EngineURL.Address.ToString(), key.Ref) and the orchestrator rebuilds with EngineURL.FromUri(new Uri(e.BaseUrl)). The lossy round-trip is not sloppiness — it is what the layering forces.

Assembly references pointing UI-ward from below:

Plus upward commands faked as events, because the reference cannot exist:

MultimodalManager and AuthenticationManager do not merely reference UI — they build it, holding VisualTreeAsset fields and querying instantiated trees (root.Q<VisualElement>("choice-options")). Both are UI code with a domain attached.

The edges above look like one problem and are three. Conflating them is what makes any single fix feel forced.

P1 — Presentation control. A flow needs a screen shown or hidden. AppOrchestrator → screens.

P2 — User answers. A flow must stop, ask the user something, and continue with the answer. Everyone → DialogController / PopupController.

P3 — Flow triggers. A component learns something and a flow has to run. ConversationManager, MultimodalManager, UI → AppOrchestrator.

P2 is the load-bearing one. Four of the five real assembly edges are P2. As long as "ask the user" is spelled UI.Popups.DialogController, every layer that needs to ask anything must reference UI — so fixing P1 alone moves the cycle rather than removing it.

Stop stacking the flows and the screens on each other. Make both leaf assemblies that nothing references, meeting on a shared contract module:

Nothing references Promethist.Application, and nothing references Promethist.UI. There is no pair of assemblies with an edge in both directions and no path that could grow one, so cycles become structurally impossible rather than a thing to be careful about. Either leaf could be deleted or replaced wholesale — which is the same property that makes the app runnable headless (see Headless operation).

App.State already was the contract module in everything but name: it holds ProjectKey, AgentKey and AppState, depends only on Core, EngineCommunication and SystemNative, and was already referenced by App, UI, Conversation, Authentication and Telemetry — exactly the right set. It is now Promethist.Contracts (it was also the one assembly missing the Promethist. prefix), living in Assets/Scripts/Contracts/, with three jobs:

The existing App.State namespace stays as-is so no using changes; new events and ports live in App.Events and App.Ports. The awaitable ports do need one asmdef change: an explicit assembly definition never inherits autoReferenced packages, so Promethist.Contracts lists UniTask like every other assembly does.

The two leaves still have to be introduced to each other at runtime, and ServiceLocator already is that composition root: UI registers its IPromptService, the orchestrator registers its IAppFlows. No assembly edge either way.

Every cross-layer interaction goes through exactly one of three channels, each one-directional.

The orchestrator publishes where it is in an interaction. It does not publish, or know, what that looks like.

A single controller in Promethist.UI — InteractionSpaceController — projects that onto screens. This is ShowScreen moved to where it belongs, and it is the only thing in the app that knows the mapping:

Entering cold is None → LoadingVisual → LoadingSession → Active. Because LoadingVisual is an opaque overlay, which space sits behind it is undefined, so the projection only switches spaces at LoadingSession and None.

Handover is the shorter Active → Ending → Active, because it is the one flow whose loading the user watches from a screen of its own: the evaluations of the conversation that just ended, then AgentLoadingPrompt, which shows the incoming agent with the load running under it and offers its Continue button once that lands. Both take the loading overlay down while they are up, so the state is left at Ending until the user is through with them — a transition in between would put the overlay back over the screen the user is reading.

What precedes it depends on how many agents the engine offered. HandoverSpec.agentRefs holding one makes the popup a confirmation, accepted by a countdown running out; holding several makes it a pick between agent cards, where nothing is taken by inaction. A pick is also an answer — the chosen agent’s ref goes back to the engine as a multimodal response, the way a choice or an input answers one — so it is sent from AppOrchestrator rather than MultimodalManager, which is what keeps the response and the session end that follows it from being separated by a refusal. Because it is an answer, the agent gets to reply to it: the handover holds until the agent has spoken again, so a parting line is heard out rather than cut off by the session ending. It waits with ConversationManager.WaitForSpeechEndAsync(ignoreCurrentSpeech: true) — the same wait SuggestEndAfterTurn uses, with the extra leg that the speech still in flight when the pick was made is not the reply, so it is waited out first and NextSpeechGraceSeconds bounds how long a reply that never comes is waited for.

A screen declares its own space and whether it is an overlay, in code:

UIController registers itself into UIScreens on Awake when it names a space, so the projection needs no serialized references at all — the one fact about a screen lives with that screen, and nothing about the mapping is wired in the scene. Entering a space shows only its non-overlay screens; leaving one hides everything in it, overlays included. Chrome is the same idea one level down: a screen that can be up with its controls held back implements IChromeScreen, which is how LoadingSession shows the agent’s visual with nothing to talk to yet.

Commands are void because nearly every call site is fire-and-forget; the async OpenProjectAsync stays private to the orchestrator, where OpenAgentAsync awaits it. The one exception is OpenLinkAsync, for a caller that offers to try again: it answers an OpenOutcome - Opened, NotFound, AgentNotFound (the agent’s project opened, but it serves no such agent), Declined (terms or login) or Unrecognized. A not-found error dialog is awaited before the outcome is answered, so the caller’s retry never lands under it; startup reads Opened and AgentNotFound alike as a project being open. ServiceLocator.Register<T> keys on typeof(T), so ServiceLocator.Register<IAppFlows>(this) registers under the interface with no locator change.

OpenLink is the deep-link router offered as a command: where a link leads - a project, an agent, an unsupported relay - is the orchestrator’s decision, made in one place for a pasted link and a followed one alike. The projects sidebar’s add popup turns whatever the user entered into a link before handing it over, so it goes through the same router - see "Adding a project or agent" in ui/ui.adoc.

RefreshCurrentProject is the ex-passenger of ShowScreen(AppScreen.Home), which invalidated the project cache and re-fetched — a data concern that had been riding inside a UI switchboard. Exposed as a command it also answers pull-to-refresh.

LogOutOfProject is RemoveProject without the removal: it drops the stored refresh token and the identity fields on SavedProject, and the project stays in the sidebar as a signed-out one. The cached ProjectInfo goes with the token — it was fetched with the identity that just went away, and a different account (or none) can see a different agent list — so the project is invalidated either way, and reopened at once when it is the one on screen. It is offered only for a project whose SavedProject.IsIdentityRequired is false; the UI does not present the action at all for the others, since one that requires an identity would only prompt for a new login on the spot.

The port that removes four of the five assembly edges. It separates asking from rendering the question: the API is declared in the contract module, the UI Toolkit implementation stays in Promethist.UI.

Callers never resolve the service themselves — they go through the static Prompts, which falls back to answering with DefaultResult when nothing is registered. That is what makes headless a property of the port rather than of every call site:

Prompt types are plain data in the contract module. UI owns a PromptPresenter : IPromptService that maps prompt type to VisualTreeAsset and builder, living beside PopupController — which is where all the Q<VisualElement>("choice-options") tree-building from the managers ended up.

AgentLoadingPrompt is the one prompt that carries a task: the load it waits out, which is what turns its indicator into the Continue button. The orchestrator awaits that same task, so it hands over a Preserve()`d one — a plain `UniTask can only be awaited once.

The task is a UniTask<bool>, joining the visual load with the false that a session which never opened answers with — see the A session that never opens trap below. A screen that cannot go on anywhere must not offer to: the loading screen takes itself down on a false exactly as it does on a throw, and answers false itself, leaving the orchestrator’s own wait to read the same answer and retreat.

Like the evaluations it follows, it is presented as a whole screen rather than a popup — AgentLoadingUI, in the agent detail screen’s language (hero thumbnail, name, title, description card). It covers the whole device rather than the capped column the other screens keep to, because what is behind it is the 3D visual being swapped, which must not show through while it changes. That is the IsWidthCapped ⇒ false case the settings screen also takes: the root keeps the device for the backdrop and the panel inside it is capped instead.

ShowBusy is a distinct shape because auth-waiting is not a question — it is "keep this on screen while I work". Modelling it as a prompt with an answer nobody reads would be a lie about the flow. It still offers the user two ways out, which it hands back through a plain Answered callback rather than a result, because the login landing on its own is the outcome the caller is actually waiting for.

ReconnectingPrompt is the same shape for the same reason, and shows what the shape is worth beyond auth: the orchestrator puts it up on ConversationInterrupted and disposes it on ConversationResumed, on ConversationLost, and on any SetState — a reconnect only runs inside a live interaction, so a transition means the notice is stale even in the flows that cancel the reconnect without it reporting anything back. Its one button reports through Abandoned, and the orchestrator answers that with the ordinary ExitInteractionAsync: leaving cancels the reconnect on its way out, so the user gets no "conversation ended" report for a call they made themselves.

DialogController keeps its own DialogType/DialogButtons/DialogResult: it is a self-contained widget, and PromptPresenter is exactly the place that maps MessagePrompt onto it. MessageButtons.None maps to DialogButtons.None, which hides the whole button row and drops the backdrop out of OnBackdropClicked’s dismissal — a dialog that never settles, so it holds the queue behind it and its awaiter never resumes. Only `MessagePrompt.Blocking asks for it, and only for a state the app cannot carry on from. Headless is the one exception: with no IPromptService registered the prompt answers DefaultResult immediately, since there is nothing to be stuck in front of.

The whole exit flow, in one readable method in AppOrchestrator, with the feedback survey and the evaluations wait as ordinary `await`s:

Compare with what it replaces: the same flow spread across ExitInteraction, ShowScreen, EvaluationsUI.OnDone and an OrchestrationRequested.Navigate round-trip, with the "does this agent have evaluations" decision made in the app layer and the "so show that screen" decision made two hops away.

With no IPromptService registered, Show returns the prompt’s DefaultResult immediately. The orchestrator therefore runs every flow end to end with no UI in the scene at all — by construction, not by discipline, and the same holds for a fake provider in a test.

That is the acceptance criterion for this design. If a flow cannot run without UI present, the boundary has been crossed somewhere.

The reverse holds too: a build with the orchestrator’s GameObject disabled still gets past the Android native splash. NativeSplash releases the splash right after scene load unless something called NativeSplash.Hold() from Awake. The orchestrator does, and releases it itself once localization is ready. RuntimeInitializeLoadType.AfterSceneLoad runs after the scene’s Awake calls but before Start. Disabling only the component is not enough: Awake still runs on a disabled component, so the splash stays held.

Only publish the ends nobody asked for. A general "the conversation ended" event re-enters the orchestrator: its exit flow calls EndConversationAsync(), which reaches OnDisconnected, which publishes, which starts the exit flow again. A state guard on Ending looks like the fix and is not enough — handover also ends a conversation legitimately, and now runs at Ending for its whole duration, so an Ending-only guard is blind to which end it is looking at: it would swallow a genuine drop of the incoming session as readily as it hides the spurious exit flow.

The orchestrator is the only thing that ends a conversation on purpose, so the only end that needs a channel at all is the one it did not cause. ConversationLost is published only for an unintentional end — ConversationManager already carries the distinction it needs in wasIntentional, which it already uses to decide whether to report the drop to the user. Re-entrancy is then impossible rather than guarded against, and this is why the event needs no reason enum: the other two ends it would encode do not belong on it. It carries only an optional Message - the engine’s text for a non-recoverable error, shown instead of the generic "conversation ended". Requested needs no event, because the orchestrator is the caller; an agent proposing an end is ConversationEndSuggested, a different fact at a different moment — see below.

The same distinction now carries a second decision: an unintentional drop is resumed on the session id it lost before it is given up on, and ConversationLost is published only once that fails. ConversationInterrupted and ConversationResumed report the attempt, and an end the app asked for is never resumed — see Session Reconnect.

A session that never opens. CreateConversationAsync answers false rather than throwing, because the flows that call it are Forget()`ed — an engine error arriving before the session is ready (a refused tenant, a socket that drops) surfaced only as an unobserved exception, and the app stayed on its loading state with the overlay up and no way out. `ConversationManager.ReportStartFailedAsync owns the report: conversation.error.startFailedReason when the engine named a reason meant for the user, conversation.error.startFailed when it did not, and the untranslated internal cause appended in dev mode only — the rule the engine’s Description already follows. It is public because the orchestrator’s own preconditions (an unknown agent, an agent outside the open project) fail the same interaction before a conversation is ever asked for. The orchestrator owns the retreat, AbortInteractionAsync, which unloads the visual and returns to None. ConversationLost is not involved and there is nothing to end — the conversation never connected.

A startup that opens nothing. Every failure inside OpenProjectAsync — a project the engine will not serve, declined terms, a cancelled login — answers false and leaves CurrentProjectKey pointing at a project no ProjectInfo was ever cached for. Nothing else recovers from that: CurrentProjectChanged is only published for a load that succeeded, so HomeController.Refresh logs its missing project and returns, and the app sits on placeholder Home and Projects screens with no route out — the saved project is reopened on every launch, so it is not even a restart away. OpenStartupAsync owns the recovery: it awaits the one open the app starts on and falls back to the default project when it answers false. Only startup falls back — a project the user picks, or a deep link followed while the app is running, fails against an app that already has somewhere to be.

When the default fails too — either as that fallback or as the project the app started on — there is nothing left to try, and the app ends on MessagePrompt.Blocking: a dialog with no buttons, ignoring its backdrop, telling the user to restart the app or reload the page. Awaiting it never resumes, which is the point. It is deliberately a dead end rather than a retry button, because everything a retry would re-attempt has already been attempted, and the states behind the dialog are the empty screens this trap is about.

This is why OpenLink became OpenLinkAsync and answers whether a project ended up open rather than whether the link parsed. Startup needs the outcome, not the recognition, and the two came apart in both directions: a relay link was "handled" and opened nothing, an unrecognized one was not handled and fell through to the current project. OpenAgentAsync returns the same fact so an agent link’s project counts, however the interaction that follows goes.

The default project is not always on production. AppState.DefaultEngineURL reads the page’s own host on Web, so the preview and PRP deployments default to the engine that served the client rather than the production one their region resolves to — the client and its engine are the same host, and a build shipped from one that talks to another has no project of its own to fall back to. Anything the host does not parse into a Promethist engine (a local build, a bare host) stays on production, and every other platform keeps resolving the region as before.

Flows left behind in managers. ConversationManager.EndAfterTurn asked the user "end the conversation?" and then commanded the exit — a flow living in a manager. It is now SuggestEndAfterTurn, which mutes, waits out the agent’s speech and publishes ConversationEndSuggested; the orchestrator owns both the prompt and the teardown. The "no" branch needs a way back, so the manager grew one command for it — SendDecline(), which restores the mute state and sends the engine’s decline. Likewise the handover popup: MultimodalManager reports EngineHandoverRequested and the orchestrator decides whether to confirm with a HandoverPrompt first. Both are more churn than the port strictly requires, and both are the same rule applied consistently.

Two questions about the same conversation. The engine can ask both at once: a sessionShouldEnd command and a handover interaction in the same turn. SuggestEndAfterTurn waits out the agent’s speech before publishing, so the suggestion typically lands while the handover popup is already up and counting down — and a confirmation dialog then stacks on top of a question the user is mid-answer to. The offer subsumes it: accepting the handover ends this conversation anyway, refusing it is the same "keep talking" the dialog’s "no" means. So a suggestion arriving while the offer is up is ignored outright, ResolveEngineHandoverAsync clearing the flag in a finally so a popup that fails to present cannot silence every later suggestion too. The flag stays set through the wait for the agent’s reply as well: that reply is exactly what SuggestEndAfterTurn waits out before publishing, so lifting it earlier would put the dialog on screen in the seconds between the pick and the handover taking over. What a refusal owes the engine is the same #decline the dialog’s "no" sends, only carrying the offer’s ref — so it names the interaction turned down rather than overloading the bare notice, and it lifts the mute SuggestEndAfterTurn forced along the way.

The window after the offer is a different matter, and needs no flag — a handover runs at Ending for its whole duration, so the state guard at the top of OnConversationEndSuggested covers it. That guard is also why the one inside ResolveSuggestedEndAsync stays: it catches the state changing while the dialog is up, which the entry check cannot see.

AppScreen in the foundation. The enum lived in Core.Events, below everything, naming UI screens. It is deleted, not moved.

Each stage compiles and ships on its own, and deletes edges on its own. All four have landed.

ProjectLoadFinished in stage 1 also retires the two // TODO Inform of end of load for pull to refresh comments in OpenProjectAsync, which existed because the orchestrator had no way to report a finished load that did not involve touching UI. It carries the project and whether the load succeeded, because a failed load is precisely the end that CurrentProjectChanged cannot report.

Four things the design did not name, and one thing it got wrong.

AgentOpened. Opening an agent link without an action used to end in agentDetailUI.ShowAgent(key). Stage 2 has nowhere to put that call, and it is not a flow decision — so OpenAgentAsync publishes the fact that an agent was opened and AgentDetailController decides that an opened agent looks like its detail card.

The space registry. See Target structure: two leaves and a contract module above — UISpace, UIScreens and IChromeScreen. The alternative was six serialized references on the projection, half of them into prefab instances.

Prompts. The static entry point in front of IPromptService, so the headless fallback lives in one place instead of at every call site.

SendDecline. The command the "keep talking" branch of ConversationEndSuggested needs, now that the manager no longer owns that question.

The UniTask reference. The design claimed the awaitable ports needed no asmdef change. They do — see Target structure: two leaves and a contract module.

Two pieces of pre-existing debt are also worth knowing about, both in Prefabs/UI/Screens/Conversation UI.prefab: it carries components for UI.ConversationUI and UI.UIDocumentDataSourceBinder, neither of which exists any more. The scene’s instance adds the real ConversationController on top, so nothing is broken, but the prefab shows two missing scripts until someone removes them.