Skip to content

ADR: Gateway owns fallback-trigger detection via a single generic "couldn't translate" signal

Context

Several capabilities in this Feature Set need to detect when a host chat surface can't adequately continue a conversation — a form the host can't render, an unsupported document action, a sensitive-topic UI requirement, a turn-count/token threshold, or a front-end hint the gateway can't map — and fall back to a "Continue in Novaworks" deep link (continue-in-novaworks/spec.md).

Left unaddressed, each trigger condition could end up owned by whichever layer happens to notice it first: the agent explicitly signaling "I need a controlled UI for this," the sidecar inspecting response content, or the gateway inspecting host capability flags. That would mean three trigger conditions with three different detection mechanisms to build, test, and keep in sync as new conditions are added — and no single place to reason about "did we offer the fallback when we should have."

Decision

The Gateway/MCP proxy owns trigger detection uniformly, as a single generic "couldn't render/translate this for the current host" signal:

  • Host-capability checks (e.g., A2UI disabled) and any response element the gateway can't translate for the current transport/host are treated the same way, regardless of whether the underlying reason is a capability gap or something the agent decided it needed to do (e.g., requiring a document signature, a sensitive-topic UI context).
  • The agent does not need to explicitly signal individual conditions like sensitive-topic classification or unsupported document actions — those surface to the gateway as the same generic signal as any other untranslatable response element.
  • This means a trigger condition that doesn't exist yet (e.g. sensitive-topic classification, deferred per continue-in-novaworks/spec.md Open Question 5) is automatically covered once the underlying capability ships, with no new detection plumbing required on the gateway side.

Consequences

  • Every capability in this Feature Set that needs a fallback (deep link per Section 4, nudge deep link per Section 2, NovaworksCollectionSpec.fallback_url per Section 3) reuses the same detection path instead of inventing its own — see Dependencies in continue-in-novaworks/spec.md and notifications/spec.md.
  • New trigger conditions are added by teaching the gateway to recognize a new class of untranslatable response, not by adding a new agent-side signal — keeping the agent's responsibility scoped to "respond naturally" rather than "know what every host can render."
  • Risk: because it's one detection path for conditions of very different character (capability-disabled vs. sensitive-topic vs. document action), it can fire too broadly or miss cases — the specific set of untranslatable-response markers needs validating against every trigger condition during implementation (tracked in continue-in-novaworks/spec.md Risks).