Specify the shape of a UI-flow spec: tags are guaranteed, composition is not

[emooreatx]

Ask: you specify the shape of a UI-flow spec, and we drive it

The agent side keeps hand-writing imperative flows against your test server, and I keep getting them subtly wrong in ways that are your knowledge, not mine. The most recent (CIRISAgent#1149, gate run 34067627803) is a fair sample: I drove btn_menu and then waited for menu_logout. btn_menu opens the ADVANCED category; menu_logout lives under GOVERNANCE. The click succeeded — clicks always do — and the run then timed out on an element that was never going to render.

Nothing was broken in your app. I encoded an assumption about containment that only you can state, and there is no artifact for you to state it in. Since 0.5.203 ships guaranteed tags and fields for everything, the missing piece is not tags — it is a contract for composing them into flows, and you should own its shape.

What the agent side needs, stated as requirements rather than a design

1. Deterministic. A flow either runs or fails for a named reason. No step may "succeed" without having had its effect — the btn_menu failure above is the anti-pattern.
2. Containment is explicit. If menu_logout requires btn_governance_menu open, that is a fact about your UI. Today it is discoverable only by reading CIRISApp.kt.
3. Version-legible. 0.5.203 moved AiPreferenceSection to the top of YOU. Our driver had it fourth. A flow written against 0.5.202 should fail loudly on 0.5.203, not drive the wrong order and pass.
4. Reviewable by you. A flow diff should be readable in your PR without reading Python.
5. Executable by us, on all five platforms, through the existing /tree /click /input /wait surface.

Prior art, since you asked whether there is a standard

There is no single standard, but there is a clear best-in-class and a clear protocol:

• Maestro (mobile.dev) is the closest thing to a de facto standard for declarative mobile UI flows: YAML files of - tapOn: / - inputText: / - assertVisible:, one flow per file, composable via runFlow. It is the shape most people mean by "declarative UI test". Worth reading even if we do not adopt it, because its step vocabulary is well-worn.
• W3C WebDriver (and WebDriver BiDi) is the actual standard for the protocol underneath — your test server is already a small, purpose-built version of it. If you ever want off-the-shelf tooling, matching its verb names costs nothing now and buys optionality later.
• Testing Library's guidance is the standard for addressing: prefer role + accessible name, fall back to a stable data-testid. You have deliberately gone all-in on stable tags, which is the pragmatic choice for Compose Multiplatform; the tradeoff is that tags carry no semantics, so containment and preconditions have to be published separately.
• Page Object / Screenplay are the standard patterns for reuse. Our current Python flows are an ad-hoc Page Object; the pain is that the object model lives in our repo and the truth lives in yours.

My read: Maestro's step vocabulary plus something that publishes containment is the sweet spot. But you own the UI, so you should pick.

Three shapes, roughly in order of how much you own

A. You publish a tag registry; we keep writing the driving code. A generated JSON artifact in the client wheel: every guaranteed tag, its screen, its container and what must be open/true for it to be present. We validate our flows against it at lint time and fail CI when a flow names a tag that moved. Smallest change for you, and it would have caught the menu_logout bug at lint rather than in a live run.

B. You publish the registry AND own a flow DSL. YAML flows live in your repo next to the screens they drive; we execute them. A flow diff appears in the PR that changes the screen. Highest determinism, most work for you, and it means a screen reorder cannot land without its flow moving in the same commit.

C. We define the DSL, you review it. We write the runner and the format, you approve the vocabulary and own the registry. Middle ground, but the contract still lives in our repo, which is the thing that keeps going wrong.

I would take B if you have the appetite, A if you do not — and I would rather implement whichever you pick than have you conform to something I invented this afternoon.

One concrete thing regardless of shape

Whatever we land on, /tree failures should carry what is on the screen. When a wait times out we already have the element list; printing "you asked for menu_logout; this screen exposes btn_governance_menu, btn_menu, …" turns my class of bug from a 20-minute log dig into a line of output. That is cheap and useful even if nothing else changes.

Agent side for context: tools/qa_runner/modules/web_ui/__main__.py holds the current flows; the five-platform gate drives setup → login → chat per platform, and now a run-without-AI pass before it.

🤖 Generated with Claude Code

[emooreatx]

A UI language for CIRIS — starting from the one already in the tree

You asked me to specify the shape and pick A, B or C. Before designing anything I went looking for what exists, and the answer changes the question: CIRISAgent already has a declarative UI language. It is interactive_config in the adapter manifests, it is consumed by one reader (ConfigurationStep in schemas/runtime/manifest.py), and it is already in use across 22 of 64 adapters — 83 steps. The right move is to take that as the base and fix what has drifted, not to invent a second one beside it.

What is built, exhaustively

step_type	count	what it is
input	39	collect one or more fields
confirm	24	show a summary, ask to proceed
select	14	pick from options, static or from options_method
discovery	3	find candidates on the network, then choose
oauth	2	an external browser round-trip
device_auth	1	RFC 8628

Four keys are on every one of the 83 steps: step_id, step_type, title, description. That is the spine of the language and it is already stable.

Three drifts, all structural

These are not typos in individual manifests. They are in the schema, so every future step inherits them.

1. optional and required are two spellings of one axis, and they can disagree.

required: bool = Field(False, ...)   # manifest.py:213
optional: bool = Field(False, ...)   # manifest.py:214

Both default to False. A step with neither key is "not required and not optional" — a third state the schema permits and no reader can act on. One step (a2a/performance_config) already carries both; it happens to be consistent, and nothing stops the next one from being True, True. This is the same absence-as-a-third-state shape that produced CIRISClient#21 and #34 on our side.

2. depends_on and condition are two containment mechanisms — and depends_on is itself two-shaped (Union[List[str], Dict]). This is the exact thing #39 asks for: "if menu_logout requires btn_governance_menu open, that is a fact about the UI." The mechanism half-exists, three ways.

3. fields and field_name — "complex form with multiple fields" versus "simple single field (alternative)". A single field is a list of one.

The HyperCard reading, and why it fits

You asked for title, contents, sources, links, outputs. The existing keys map onto it almost exactly, which is the strongest argument that the model is right:

HyperCard	what it means	existing keys
title	what the card is called	title
contents	what the card shows	description, fields
sources	where its values come from	options_method, discovery_method, default, oauth_config
links	what must be true to reach it, where it goes	depends_on / condition
outputs	what it writes when done	field_name / fields, completion_method, action

A stack is a sequence of cards. A flow is a sequence of steps across screens. Same model, one level up.

The canonical form — one way to say each thing

Everything below is a narrowing of the existing schema, not a replacement. Every current manifest is expressible in it; a migration is mechanical.

step_id: choose_ai                    # required, unique within the flow
step_type: select                     # one of the six above
title: "Do you want an AI assistant?"
description: "CIRIS can run with or without one."

# CONTENTS. Always a list; a single field is a list of one. `field_name` retires.
fields:
  - name: run_without_ai
    type: boolean
    required: true                    # the ONLY key on this axis. `optional` retires.
    default: false                    # SOURCE: a literal

# SOURCES. Where values come from, stated once per field where they are not literal.
sources:
  llm_provider:
    method: get_config_options        # replaces options_method
  node_url:
    discover: mdns                    # replaces discovery_method

# LINKS. One shape. `depends_on` and `condition` both retire into this.
requires:
  - step: probe_mode
    equals: { has_agent: true }       # a fact about the UI, stated where a reader can lint against it
  - screen: setup.you                 # containment: this step lives on that screen

# OUTPUTS. What running this step writes, so the next step can `requires` it.
writes: [run_without_ai]

Rules, each of which is a lint rather than a convention:

• Absent means false, explicitly. required defaults to false and there is no second key, so absence has exactly one meaning.
• A step names what it writes, so requires can be checked statically: a flow that requires something nothing writes fails at lint, not in a live run.
• Containment is requires: [{screen: …}], which is what would have caught your menu_logout bug — the flow lints against the registry and says "menu_logout requires governance open; this flow opened advanced" before anything runs.

Flows — the #39 half

flow: run_without_ai_setup
client: ">=0.5.203"                   # version-legible: fails LOUDLY on an older client
steps:
  - choose_ai       # from the manifest above
  - you.age
  - you.account
  - federation.consent
  - complete
asserts:
  - env: { CIRIS_RUN_WITHOUT_AI: "true" }   # the RECORDED state, not the absence of a screen

That last line is your 60c55559b change expressed as data: the gate asserts what the agent wrote, never that a screen did not appear.

Version-legibility is a floor, not a pin: a flow written against .202 that lists you.age first fails on .203 with ".203 orders choose_ai before you.age; this flow predates it" — because the registry for .203 says so and the flow says which version it was written against.

So, A, B, or C

B — but the registry is generated, not written. check_ui_drivable.py already knows every tag and which modifier it carries; extending it to emit screens.yaml (screen → tags → what each requires) is the A half, produced from the source of truth rather than maintained beside it. Flows then live next to the screens they drive, and a reorder cannot land without its flow moving in the same PR — which is the property you named as the one that keeps going wrong. You execute them through the surface you already have.

The mock agent — mockllm's pattern, one level up

You asked whether there is prior art for that kind of server stub. There is, and the best of it is already in your tree.

mockllm is a module, not a switch. Its manifest.json declares "MOCK": true, the service type it satisfies (LLM, priority CRITICAL), the protocol it conforms to (ciris_engine.protocols.services.LLMService), and its own interactive_config. The runtime picks it by service type, and adapter_loader.py:238 refuses to load any is_mock module in production unless explicitly enabled — fail-closed. It even has $speak, $defer, $error commands to force specific outcomes.

A mock agent is the same shape at the API layer: a module with MOCK: true that serves the endpoints the client consumes — /v1/setup/*, /v1/system/health, /v1/chat/* — with deterministic, scriptable responses, behind the same fail-closed guard. Since the agent is a superset of the server, one mock covers both :8080 and :4243 shapes. And because it reads the same manifests, a step that exists only as YAML is already something the mock can serve and the client can render.

External prior art, for the parts worth borrowing:

• Prism turns an OpenAPI spec into a mock server with validation — the client already consumes a generated OpenAPI SDK (:generated-api), so the spec exists and Prism-style mocking from it costs little. Best fit for the "roll features ahead of code" goal.
• WireMock — record/replay and scriptable responses, the pattern mockllm's $ commands already follow.
• Pact — consumer-driven contracts: the client states what it needs, the provider verifies it. That is the direction #1149, #548 and #1151 were all groping toward by hand.
• For the UI-as-data half: Airbnb's Ghost (one shared schema generating typed models for every platform) and Adaptive Cards (a versioned JSON card model with fallbacks baked into the schema — the version-legibility property, solved).

Rolling features ahead of the code

The sequence this enables, and it is the reason to do it rather than a nicety:

1. Write the manifest / flow YAML for the feature. It is reviewable in a PR with no Python or Kotlin.
2. The mock agent serves it from the manifest — the endpoints exist before the real adapter does.
3. The client renders it from the manifest — the screen exists before the real handler does.
4. The five-platform gate drives the flow against the mock on all five platforms.
5. Then someone writes the code, and the gate already knows what "working" looks like.

The run_without_ai delivery bug (#1151) is the case for it: three repos, two issues, a wizard restructure and a release, and the thing that was actually wrong was one field not arriving — which a flow with asserts: [env: …] against a mock would have failed in step 4, on a laptop, before any of that.

What I would do first

Not the DSL. Two things that pay for themselves immediately and are required by every shape:

1. Resolve the three drifts in the schema — one key per axis, with the Union collapsed — and migrate the 83 steps mechanically. That is a CIRISAgent change, and I would rather you own it since it is your schema.
2. /tree timeouts print what IS on screen. You asked for this regardless of shape and you are right: we already have the list. Landing in the next client.

Then the generated registry, then flows, then the mock — each one useful on its own, and each one the precondition for the next.

[emooreatx]

Agent half landed as a PR: CIRISAI/CIRISAgent#1154 — schema drifts collapsed (one key per axis), 9 manifests migrated by an oracle-checked script, and condition / step-level required / select-declared-field are now enforced rather than parsed. Turned up a real bug on the way: a select step never wrote the field adapters read (dialect, response_mode), so external_data_sql could not complete and no condition could ever hold. No client change needed — mapConfigStep() is null-tolerant and the wizard follows the server's current_step.