DESIGN — Migrate OMP Native Chat from terminal/transcript to ACP #20

Decision

Migrate OMP Native Chat from the existing terminal/transcript-backed implementation to Orca's now-merged structured ACP stack.

This is a migration project, not a new generic-provider project.

The governing invariant is:

For every environment and workflow migrated from legacy OMP Chat to ACP, ACP must preserve or strengthen all existing user-visible and reliability guarantees. Workflows not yet at parity remain explicitly routed to the legacy implementation.

Only after parity is proven do we expand beyond the old feature set by consuming OMP-specific ACP extensions / unknown ACP messages through Orca's extension-message boundary.

Upstream foundation status

The generic infrastructure this project depends on has landed in stablyai/orca/main:

• refactor(native-chat): keep the provider resume handle opaque to shared code stablyai/orca#24991 — opaque provider resume handles — merged
• refactor(native-chat): structured agents declare their capabilities instead of shared code naming Claude and Codex stablyai/orca#25076 — provider-declared structured capabilities — merged
• feat(native-chat): open structured chat's wire and stored records to registered agents, behind a negotiated capability stablyai/orca#25159 — registered agents in wire/storage/runtime — merged
• fix(native-chat): the agent's exit ends its record, and an unconfirmed stop is joined instead of held stablyai/orca#24862 — provider stop/exit semantics — merged
• Extract provider process supervision and stream reading from Codex stablyai/orca#24989 — shared provider process supervision — merged
• Share the managed process lifecycle for structured providers stablyai/orca#25204 — shared managed provider lifecycle — merged
• Admit one provider event's journal writes as one queued operation, decided when it runs stablyai/orca#25141 — provider-event journal operations — merged
• Add a shared timeline assembler for structured agent chats (not wired yet) stablyai/orca#25064 — shared timeline assembler — merged
• Add standalone Agent Client Protocol client layer stablyai/orca#24990 — standalone ACP client — merged
• Translate ACP traffic into shared timeline events stablyai/orca#25090 — ACP → shared timeline translation — merged

The composed Grok PR stablyai#25225 is still open, but OMP no longer needs to build on that branch: the generic ACP/provider primitives we need are already in upstream main.

Target architecture

Existing
========
OMP terminal process
    ├── PTY input injection
    ├── status hooks
    └── local transcript reader
             ↓
        Native Chat UI

Target
======
StructuredAgentSessionHost
        ↓
registered structured-agent runtime
        ↓
shared managed provider process
        ↓
shared Orca ACP client
        ↓
      omp acp
        ↓
OMP AgentSession/runtime
        ↓
shared ACP → timeline translation
        ↓
Orca journal / Native Chat UI

The terminal remains available as an ordinary OMP TUI. The goal is to replace the Chat UI transport, not remove terminal use.

Current OMP ACP capabilities

Current OMP ACP already exposes first-class support for, among other things:

• initialize + capability negotiation;
• authentication methods;
• session new/load/list/resume/fork/close;
• replay of stored session history;
• prompt/cancel lifecycle;
• images;
• MCP server configuration;
• session modes;
• model/thinking/config options;
• available slash commands;
• extension UI via ACP elicitations;
• Pi/OMP AgentSession event → ACP update mapping.

OMP also has provider-specific behaviors/extensions beyond the baseline ACP surface. Those are phase 2, after migration parity.

Parity principle

ACP must not regress behavior merely because the source of truth changes from PTY/transcript to structured protocol.

For every existing OMP Chat behavior, document:

1. current terminal/transcript source;
2. current guarantee;
3. ACP source/equivalent;
4. migration test proving equal-or-stronger semantics;
5. fallback behavior if ACP is unavailable.

Examples of guarantees to inventory include:

• transcript/history rendering and ordering;
• reasoning visibility;
• tool lifecycle and edit cards;
• model/provider/usage metadata;
• compaction boundaries;
• model switching;
• thinking/session options;
• slash-command behavior;
• skills/autocomplete behavior;
• images/attachments;
• questions/approvals/interactions;
• local command behavior such as /usage;
• turn/status settlement;
• session resume/restart;
• mobile projection;
• supported local/runtime ownership cases;
• error/failure presentation;
• no duplicate messages across reconnect/replay.

The parity inventory in #52 is authoritative. Features omitted from that inventory are not implicitly allowed to regress.

Migration policy

Phase A — parity baseline

Add OMP as a registered ACP structured provider, but keep the existing terminal/transcript Chat path as a fallback.

Use feature/capability/version gating so unsupported OMP builds remain on the old path.

Phase B — parity completion

Move each existing behavior onto the ACP path and pin it with regression tests.

ACP becomes default only after all required parity gates pass.

Phase C — ACP-only extensions

After parity:

• inventory every OMP-specific ACP notification/request/config surface that Orca's generic translator does not yet consume;
• receive forward-compatible unknown/extension messages through the ACP client's extension boundary;
• translate useful OMP semantics into existing Orca timeline/control models;
• add generic Orca ACP primitives upstream where the concept is provider-neutral;
• keep OMP-only behavior in a narrow OMP ACP dialect.

Do not bypass ACP and fall back to omp --mode rpc merely to access a richer provider event.

Unknown ACP / extension handling

The merged ACP client already has a forward-compatible extension-message boundary.

Use that boundary deliberately:

standard ACP message
    → generic ACP translator

unknown / OMP extension
    → OMP ACP dialect
         ├── normalize to existing Orca event/control
         ├── expose bounded provider-specific metadata if useful
         └── safely ignore unsupported future extensions

Do not let arbitrary extension payloads flow directly into renderer code.

Session identity and migration

A major parity requirement is continuity for existing OMP sessions.

Determine whether the ACP session id/load semantics map directly to the same persisted OMP session store used by the current transcript path.

For an existing OMP Chat session:

• preserve the conversation identity;
• load the same OMP session through ACP when possible;
• replay history exactly once;
• preserve current branch/session state supported by ACP;
• never fabricate a new conversation merely because Chat transport changed.

If some legacy terminal session cannot be safely adopted by ACP, keep the old path available and report the limitation explicitly.

Reliability

ACP migration must preserve or improve:

• one writer per live provider session;
• fail-closed process ownership;
• no automatic resend of ambiguous user input;
• generation-safe cancellation;
• exactly-once interaction responses;
• replay/live boundary without duplicates;
• correct interrupted/stopped tools;
• correct session settlement;
• provider crash → explicit failed/stopped state;
• no stale process/event mutation after replacement.

Remote/mobile scope

Existing support is the floor.

If the current terminal/transcript path works only for a subset of local/runtime cases, ACP may expand support, but must not silently remove a supported path.

Capability routing should choose:

OMP ACP structured path
        if supported
else
existing terminal/transcript Native Chat path

until the fallback is explicitly retired.

Child issues

Execution tracker: #67 (v3 plan).

• Tracking: OMP Native Chat → ACP migration (v3 plan) #67 — Tracking: OMP Native Chat → ACP migration (v3 plan)
• Structured launch availability per registered agent, with legacy-chat fallback on decline #78 — Structured launch availability per registered agent, with legacy-chat fallback on decline
• Register omp acp as an opt-in structured ACP agent behind the availability gate #68 — Register omp acp as an opt-in structured ACP agent behind the availability gate
• Resting model catalog for registered structured agents from their model probe spec #79 — Resting model catalog for registered structured agents from their model probe spec
• Post-cutover migration: adopt existing legacy OMP sessions into ACP chat #69 — Post-cutover migration: adopt existing legacy OMP sessions into ACP chat
• OMP live timeline parity: messages, reasoning, tools, edits, errors, usage #70 — OMP live timeline parity: messages, reasoning, tools, edits, errors, usage
• ACP compaction updates → compaction boundary and usage invalidation (provider-neutral) #80 — ACP compaction updates → compaction boundary and usage invalidation (provider-neutral)
• OMP commands, options and composer over ACP #71 — OMP commands, options and composer over ACP
• ACP elicitation forms and OMP approval-policy parity #81 — ACP elicitation forms and OMP approval-policy parity
• OMP dialect: mid-turn "Send now" steers via OMP's ACP steer extension #82 — OMP dialect: mid-turn "Send now" steers via OMP's ACP steer extension
• Mobile: render and drive registered structured agents (provider-neutral) #72 — Mobile: render and drive registered structured agents (provider-neutral)
• OMP ACP lifecycle: settlement, Stop, crash, restart, status, notifications #73 — OMP ACP lifecycle: settlement, Stop, crash, restart, status, notifications
• New OMP chats default to ACP when the provider satisfies orca-native-chat-v1 #74 — New OMP chats default to ACP when the provider satisfies orca-native-chat-v1
• OMP ACP dialect: classify and bound the extension surface #75 — OMP ACP dialect: classify and bound the extension surface
• Native image prompts for ACP agents + OMP skills #76 — Native image prompts for ACP agents + OMP skills
• Legacy OMP chat retirement criteria, dead-code removal, upstream submission #77 — Legacy OMP chat retirement criteria, dead-code removal, upstream submission
• Single-writer protection for ACP-held OMP sessions (resume guards, AI Vault ownership) #83 — Single-writer protection for ACP-held OMP sessions (resume guards, AI Vault ownership)
• Post-cutover migration: persisted ACP↔Terminal handoff for OMP chats #84 — Post-cutover migration: persisted ACP↔Terminal handoff for OMP chats
• ACP: emit compaction updates live and usage after compaction oh-my-pi#10 — ACP: emit compaction updates live and usage after compaction
• ACP reopen of adopted sessions: Windows cwd normalization, resource-not-found, usage after load/resume oh-my-pi#12 — ACP reopen of adopted sessions: Windows cwd normalization, resource-not-found, usage after load/resume
• ACP extension _omp/session/steer: inject a message into the running turn oh-my-pi#13 — ACP extension _omp/session/steer: inject a message into the running turn
• ACP permission gate follows the configured approval policy for orca-native-chat-v1 clients oh-my-pi#14 — ACP permission gate follows the configured approval policy for orca-native-chat-v1 clients
• ACP: reject TUI-only slash commands explicitly; implement /clear in text mode oh-my-pi#15 — ACP: reject TUI-only slash commands explicitly; implement /clear in text mode
• ACP: stream non-assistant transcript entries live; accept !/python execution input oh-my-pi#16 — ACP: stream non-assistant transcript entries live; accept !/python execution input
• ACP contract orca-native-chat-v1: define, test, and advertise oh-my-pi#17 — ACP contract orca-native-chat-v1: define, test, and advertise

Superseded (closed): #21, #52–#59.

Cross-repo boundary

Most work belongs in 44madfire/orca.

If migration reveals an OMP ACP server bug or missing provider semantic, track/fix it in 44madfire/oh-my-pi, linked from the relevant Orca issue. Do not patch provider semantics inside Orca when the bug belongs to OMP.

A provider-side tracking issue exists in the OMP fork for discovered gaps.

Non-goals

• no direct OMP RPC structured transport in Orca;
• no same-session Terminal↔Chat hot handoff requirement beyond safe persisted-session migration;
• no removal of ordinary OMP terminal functionality;
• no Pi work in this epic;
• no provider-specific renderer plugin surface;
• no extension feature expansion before parity is proven.

Acceptance criteria

• Every existing terminal/transcript OMP Native Chat guarantee is inventoried.
• Native omp acp is registered through the merged generic provider stack.
• ACP matches or exceeds the existing Chat path on every required parity row.
• Existing OMP sessions migrate/load safely or fall back explicitly.
• ACP becomes the default only after parity and reliability gates pass.
• OMP-specific ACP extensions are added only after parity.
• No direct OMP RPC transport exists in Orca.
• Provider-side bugs are fixed in OMP, not papered over in Orca.
• Final implementation is suitable for a focused upstream Orca contribution.