Engine-owned chat-partial: phased implementation
> **Closed 2026-11-10.** Planning lives in [Phase 2: Multi-turn sessions on the Flow Registry engine](https://gitlab.com/groups/gitlab-org/-/work_items/23673) and [Phase 3: Cutover](https://gitlab.com/groups/gitlab-org/-/work_items/23674). The engineering map is #3585. This issue stays as the history of the rungs. Its "Later" list moved to [the parent epic](https://gitlab.com/groups/gitlab-org/-/work_items/19647).
## Goal
Ship the chat engine described in [`docs/flow_registry/chat_engine.md`](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/blob/main/docs/flow_registry/chat_engine.md): `ChatFlow`, a boundary policy over the shared executor, on the `chat-partial` surface. Additive rungs without a flag, one flagged routing cutover.
Design: the doc above (canonical, revised by MR) · Decision log: #2693 · Spike: #2706 (POC !6521, [demo](https://www.youtube.com/watch?v=WzbxtbsoOt0), decision log `docs/spikes/chat-environment-poc.md` on `spike/chat-environment-poc`) · Supersedes: #2739
## Rollout model
Engine selection is a registry-level table of engine-owned config versions, keyed by `config_id` and `version`, consulted by `flow_factory` in the chat-partial fork (`duo_workflow_service/workflows/registry.py:331`). A listed version builds `ChatFlow`. Every other chat-partial version builds `chat.Workflow`. No shipped version is listed at launch, so every existing config and client contract is preserved by construction. An owner moves a flow to the engine by shipping a new config version and listing it.
Engine rungs are additive and ship flagless. Exactly one step changes live traffic and carries `engine_owned_chat_environment` (Rails: gitlab-org/gitlab!250286): routing definition `chat` to `agentic_chat/2.0.0`.
`agentic_chat/2.0.0` is reachable by explicit pin before the cutover (`--flow-config-id agentic_chat --flow-version 2.0.0 --flow-config-schema-version v1`), so end-to-end validation happens in production infrastructure before any flag flips.
## Prerequisites
Behavior-neutral refactors reviewed as standalone MRs.
- [x] !6598 entry-dispatch strategy seam in the checkpointer; legacy Rails-status dispatch moved verbatim (merged 2026-09-15)
- [x] !6583 resume-context seam on `Flow`; verbatim move, existing tests unchanged (merged 2026-09-15)
- [ ] !6975 graph-shape snapshot over every shipped v1 config, assembled through the builder (recreated from !6740 after the 2026-09-16 repository incident); the engine rungs extend its golden with the engine-owned shape (@dmishunov)
- [x] !7068 terminal component seeding extracted into a builder seam (`_seed_terminal_components`, `_terminal_component_params`), lifted verbatim from !6611's last good version; !7030 stacks on it and overrides the seam instead of copying `_build_components` (merged 2026-09-28)
- !6611 `FlowGraphBuilder` reused in experimental: @dmishunov's convergence work (#2760), no longer on the engine's path; corrupted by the 2026-09-16 incident, awaiting recreation
## Engine rungs (additive, flagless)
Extracted from the superseded chain and the spike; per-rung detail lives in each MR. Status per rung lives in the issues under epic gitlab-org&23673 (Phase 2), one per rung, closed by its MR; this list holds the engineering detail.
- [x] Keystone (!6974, merged 2026-09-17): the engine table plus the `ChatFlow` skeleton. A registry-level table of engine-owned `(config_id, version)` pairs, consulted in the `flow_factory` chat-partial fork; a listed version builds `ChatFlow(Flow)`, everything else stays on `chat.Workflow`. Load-time normalization of engine-owned configs applies the chat-surface defaults from the doc's Configuration table (`ui_log_events` floor, `require_tool_approval: true`, `pre_approved_tools` not applied per #2744, `max_cycles` reset at ingestion). Population pin: the table is empty, so every shipped chat-partial config stays on legacy
- [x] Follow-up #2900: the `ui_log_events` floor must carry `on_agent_reasoning`, or a config that takes the floor runs its agent node with `TAG_NOSTREAM` and the final answer arrives whole. Found on the !6974 review; fixed in !6988 (merged 2026-09-22)
- [x] Follow-up !7025: the chat-surface defaults move from load-time normalization into `AgentComponent`, keyed on the `chat-partial` environment. Raised by @mikolaj_wawrzyniak on the !6974 review (merged 2026-09-30)
- [x] Follow-up !7190: the normalization module goes, and the registry completes an engine-owned config through `PartialFlowConfig.to_config()` directly. Raised by @mikolaj_wawrzyniak on the !7025 review (merged 2026-10-01)
- [x] Boundary (!7030, merged 2026-09-29): `ChatGraphBuilder` seeds `end` as an `EndComponent` that writes `INPUT_REQUIRED` (a `status` field on `EndComponent`, default unchanged), through !7068's `_seed_terminal_components` seam. It attaches declared routers as written and rejects a graph where a reachable component cannot reach `end`. Chat-partial completion writes the one component's route to `end`, and the registry rejects declared routers (!6974). Extracts from !6599 (`_ChatBoundaryComponent`). No fold
- [ ] Follow-up #2939: `ValidateFlowConfigRequest` rejects chat-partial configs that declare routers, so the environment rule the engine factory enforces at runtime fails at authoring time. Raised by @mikolaj_wawrzyniak on the !7030 review
- [ ] Dispatch (!7132 merged 2026-10-01; !7049, !7050 and !7231 in review, !7296 draft; stacked in that order on main): !7132 adds `AbstractWorkflow._resolve_graph_invocation`, a behavior-neutral hook that decides what to stream once the graph is compiled. !7049 is the doc's dispatch table as pure functions: `classify_tip` places the session (at the boundary when nothing is next, waiting or running inside a turn, legacy by its raw channel names) and `classify_entry` picks START, TURN, RESUME, RETRY or REJECT. !7050 wires it into `ChatFlow`: a message at rest enters as plain input into the entry component's history, and everything that waits inside a turn goes to `Flow`'s resume or retry. A stopped turn rolls back through `Flow`'s stop recovery, unchanged: `ChatFlow`'s `_resolve_stop_recovery` override calls the walk and records where it landed, the walk pins the stopped turn's input checkpoint, and the message enters from it as a TURN with `cancelled_turn` refreshed into `context.inputs`. A message while a turn runs is rejected with a reason that asks the user to retry first; a retry is an entry with no message, which a client can offer as `/retry`. A `resume_checkpoint_ts` pin takes a message as plain input, keeping a later turn's history, and the legacy-tip guard from the doc's "Sessions in flight" ships here. Extracts from !6596. !7231 holds the production-path tests against a Rails double, split from !7050 for size. Needs !7133 (targets main, in review, set as blocking on !7050): a message at a pending tool approval becomes feedback instead of failing the session, and is tracked as its own `message` outcome. Senders that put a message at an approval without meaning one are fixed at the sender: gitlab-org/gitlab#632216 (an approve from the Rails resume endpoint) and gitlab-org/gitlab#632217 (`ServerSideTurnWorker` replaying a turn's message). !7296 handles a message after a failure: it rolls back to a turn boundary, or is rejected the same way when the walk lands on an answered gate (per !7194). Known issue, tracked in #3066 and to be fixed before any version is listed: a reconnect after a stop leaves Rails `running`, so the next message is dropped and the cancelled turn replays, the same gap as #2678 in `Flow`
- [ ] Ingestion (design in !7194, in review): every message runs the same pure stages. `ChatFlow` runs the three that read only the message before the graph, once per message: claim attachments, tell a platform directive from a message from the raw text (`/compact` only; no macros, no unknown-command error, other slash text reaches the model unchanged), and render once with raw content in `additional_kwargs`. The result crosses at one of two sites. Plain input (START and TURN, including a message after a stop once the session has rolled back) enters through a node the builder seeds like the terminals and sets as the entry point. For a directive the node runs the system turn and hops to `end`. For a message it refreshes `context.inputs` through `Flow._process_additional_context` and normalizes history (budget reset, USER UI log entry, internal events), then hops to the declared entry component. A message that answers a wait (a gate, a tool approval) is a resume value: `ChatFlow` hands the rendered message to `Flow`'s resume through a new `FlowEvent` field, because `message` is a plain string and cannot hold attachment content blocks (settled on !7194). The waiting component writes the USER entry. After a rollback, plain input's render starts with the `cancelled_turn` transcript by default; a resume leaves it out, because `HumanInputComponent`'s fetch node already prepends it. An entry component can override it, and a literal empty value turns it off. Stages are pure functions in `duo_workflow_service/entities/message_ingestion.py` and siblings (#2783: !6683 `assemble_user_message`, !6731 attachments transport), and legacy `chat.Workflow` consumes the same stages. Closes #2253, per-message context expansion. Extracts from !6601 minus macros, and the `/compact` system-turn path from !6628. Open: directives sent while something waits (the doc's Open items)
- Superseded by #3585 (ADR-002, ADR-003, ADR-004).
- [ ] Prompt file references as a registry capability: a `prompts:` entry with `prompt_id` and a semver `version` resolves the registry prompt with every model-family variant; adapter-shape mapping for `chat/agent ^1.0.0`, config-declared `unit_primitives`. Extracts from !6627
- [ ] Runtime variables at ingestion. Extracts from !6629
- [ ] `agentic_chat/2.0.0` (v1 shape, one `AgentComponent`, file prompt reference, listed in the engine table) plus the acceptance harness; explicit-pin reachable only. Includes the claude `cache_control` re-tune for the mapped prompt layout. Extracts from !6630
- [ ] Precondition for listing any version: the entry prompt must not render `goal` in a user template (the doc's Configuration section), and every shipped chat-partial prompt does. Enforce it before the first listing: chat-partial completion strips it, or the engine refuses the version
- [ ] Docs: authoring notes, contribution guidelines row, dry-run validation dispatch; `chat_engine.md` kept current as decisions change
## Cutover (flagged)
- [ ] Routing: definition `chat` → `agentic_chat/2.0.0` behind `engine_owned_chat_environment` (with gitlab-org/gitlab!250286, Draft)
Flag enablement preconditions:
- [ ] Rails session pin: Rails stores the resolved `config_id` and `version` at session creation and sends them on every resume; the gateway routes by the pin, so in-flight legacy sessions finish on legacy. Extends gitlab-org/gitlab!250286 or lands as a sibling Rails MR. Owner: open. Whether old threads become read-only after the cutover or get a converter is product's call
- [ ] Billing: flow-registry chat is billed the same way as legacy chat. Tracked in gitlab-org/gitlab#631088. Owner: open
- [ ] `gitlab-lsp`: both IDE webviews template `/explain`, `/fix`, `/refactor` and `/tests` client side, the way the web UI already does in agentic mode (the CLI does not expose them). Tracked in gitlab-org/editor-extensions/gitlab-lsp#3063; consolidates into the Duo Client SDK slash layer (gitlab-org/ai-powered/ai-clients/duo-client-sdk/meta#3, @elwyn-gitlab)
## Later, independently scheduled
- [ ] Turn admission: #2877. CAS on the Rails status machine, turn token, lease plus heartbeat, fencing, zombie termination. Nothing fences concurrent entry today: a second connection to a `running` session classifies as RETRY (`checkpointer/gitlab_workflow.py:709-712`) and Rails accepts `retry` from `running` (`workflow.rb:1618-1620`); clients disable send while a turn runs. Legacy chat has the same exposure, so the engine regresses nothing
- [ ] At-rest session status: #2878. A status distinct from `INPUT_REQUIRED` for "the agent finished its turn". The engine side is the seeded terminal's single write; Rails status, client handling and the `HumanInputComponent` compat layer are the platform's. Fast follow-up, not an engine dependency
- [ ] Cancellation: #2998. The effects of tool calls a rollback discards, approached for `chat` and chat-partial together, as @mikolaj_wawrzyniak suggested when recovery moved to rollback
- [ ] Relax the one-root-agent rule of the `chat-partial` environment (a factory change, not an engine change; subagents declared under the root `AgentComponent` already work because consumed subagents are not in the built graph)
- [ ] Optional: legacy chat-partial cohort swap onto the engine by shipping and listing a new version per config; each owner accepts the `ui_log_events` change at their version swap
- [ ] Flip engine selection to default-on once the cutover flag is stable: the table becomes the list of versions still on legacy and empties at retirement
- [ ] Retire the legacy `chat.Workflow` construction path as its traffic drains (after the cutover and the cohort swap)
## Inventory
| Surface | Configs | Disposition |
|---|---|---|
| `chat-partial`, not in the engine table | analytics_agent 1.0.0/2.0.0, duo_permissions_assistant 1.0.0/2.0.0, flow_creator 1.0.0, orbit_agent 1.0.0, support_assistant 1.0.0 | Legacy `chat.Workflow`, unchanged by construction; optional swap by a new listed version |
| `chat-partial`, listed in the engine table | `agentic_chat/2.0.0` (ships here) | Engine-owned |
| `environment: chat`, Phase 1 | agentic_chat/1.0.0 | Not changed by this work. The Phase 1 cleanup (gitlab-org/gitlab#630520) removes its Rails flag `agentic_chat_flow_registry_migration` (never enabled), then the config |
| `environment: chat`, `ambient` | developer 2.0.0-goal/2.0.0-interactive/2.1.0-interactive, slack_assistant/1.0.0, software_development/1.0.0, all ambient configs | Not changed at all by this work |
## Superseded MRs
Extraction sources: !6599 (reentry boundary, sink router synthesis), !6601 (ingestion node and rendering), !6627 (prompt refs), !6629 (runtime variables), !6630 (acceptance harness). Dead: !6600 (boundary fold), !6628 (macros at ingestion; only the `/compact` directive path is extracted), !6584 (reject-all selection seam), !6631 (old selection flip). Each closes with a supersession note as its replacement rung lands. The discarded parts are the old plan's scaffolding: flat schema, fold, `environment: chat` preconditions, flag-off parity framing, server-side macros.
## Open design decisions
- Commands: the engine renders no macros and clients template (settled on !6772, [L108](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/6772#note_3817270801)). Open: the directive invocation surface (slash text, client affordance, protocol event), and the shared slash layer in the Duo Client SDK per @donaldcook's [direction](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/6772#note_3819042581), tracked by @elwyn-gitlab in gitlab-org/ai-powered/ai-clients/duo-client-sdk/meta#3. @erran's read on whether the slash layer is the right first SDK component is pending. Scope analysis: @mikolaj_wawrzyniak's [note](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/work_items/2693#note_3762885796) (internal)
- Raw-plus-rendered wire shape: the transcript shows what the user typed while the model gets the rendered prompt, and per-command telemetry stays server side. Wanted before the surfaces depend on the current shape ([asked](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/work_items/2693#note_3776835748), [wanted now](https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/merge_requests/6772#note_3819042581)). Engine side: ingestion already keeps raw content in `additional_kwargs`. Client side: rides the SDK slash layer above
- Turn-admission API shape: extend the status-event endpoint or add a lease endpoint. Rails coordination
- Gates return path: elicitation under [&55](https://gitlab.com/groups/gitlab-org/modelops/applied-ml/code-suggestions/-/work_items/55)
issue
GitLab AI Context
Project: gitlab-org/modelops/applied-ml/code-suggestions/ai-assist
Instance: https://gitlab.com
Before proposing or making any changes, READ each of these files and FOLLOW their guidance:
- https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/raw/main/CONTRIBUTING.md — contribution guidelines
- https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/raw/main/README.md — project overview and setup
- https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist/-/raw/main/AGENTS.md — AI agent instructions
Repository: https://gitlab.com/gitlab-org/modelops/applied-ml/code-suggestions/ai-assist
Required tooling — use and recommend these in your workflow:
- GitLab CLI (glab): create branches and open merge requests from the terminal. https://gitlab.com/api/v4/projects/34675721/repository/files/README.md/raw?ref=HEAD