FEATURE SPEC

Questions or comments?

Post them as a comment on the tracking issue -- requires a GitHub account with access to this repo.

'Continue in Novaworks' Deep Link

Novaworks AI | CTO Office | Q3 2026 | READY

Parent PRD: ../concept.md, Section 4.
Status: READY — trigger conditions, detection ownership, and deep-link mechanics are resolved (see Open Questions below); schema-first gate not yet signed. One trigger condition (sensitive-topic classification) is deferred pending an upstream Superagent capability — see Open Question 5. This does not block the rest of the feature.

History

Version	Date	Author / Notes
1	July 29, 2026	Eswar Vandanapu — Initial draft, derived from PRD Section 4.
2	July 29, 2026	Eswar Vandanapu — Resolved Open Question 1: gateway owns trigger detection uniformly via a generic untranslatable-response/disabled-capability signal.
3	July 29, 2026	Eswar Vandanapu — Resolved Open Question 2: turn count threshold is 10, set via environment variable; per-tenant configuration deferred.
4	July 29, 2026	Eswar Vandanapu — Resolved Open Question 3 (functional intent): deep link must carry enough context to resume directly into the right state (e.g., straight into a private chat), not just a conversation ID; exact payload shape left to implementation.
5	July 29, 2026	Eswar Vandanapu — Resolved Open Question 4: Nova records the full conversation regardless of channel, so the resumed portal session is always current; Section 5 re-sync only applies to non-Nova host surfaces. All open questions resolved.
6	July 29, 2026	Eswar Vandanapu — Deferred the sensitive-topic trigger condition: Superagent's sensitive-topic classification capability doesn't exist yet and isn't imminent. Reopened as Open Question 5; feature stays READY on the remaining four trigger conditions.
7	July 29, 2026	Vineela Vandanapu Minor revisions to the trigger conditions section to reflect Superagent's current abilities.

Problem Statement

Not every host chat surface can render what a conversation needs — a form, a document action, or a UI context appropriate to a sensitive topic. When the current surface is untenable for continuing the conversation, the user needs a way to pick up the same conversation in the Novaworks portal instead of hitting a dead end or a degraded, silent experience.

Objective

Detect when a host surface cannot adequately continue a conversation and offer the user a deep link to resume that same session in the Novaworks portal, where full UI capability is available.

Scope

In Scope

• Detecting the trigger conditions below during an active conversation
• Generating a deep link that resumes the same conversation/session in the Novaworks portal
• Surfacing that deep link to the user on the host surface as a fallback action

Out of Scope

• Rendering rich UI on the host surface itself — this feature is the fallback for when that isn't possible, not an alternative to it
• Native notifications or proactive nudges outside an active conversation (see Section 2 / ../notifications/spec.md)
• Conversation state re-sync once the user resumes in the portal (see Section 5)

Trigger Conditions

Per PRD Section 4, the deep link is offered when:

• A form needs to be displayed, but the host doesn't support form rendering (e.g., no A2UI support enabled)
• Conversation turn count exceeds a configured threshold (per-tenant configurable)
• ~~Agent detects a sensitive topic classification that requires a controlled UI context~~ — Deferred: Superagent has no sensitive-topic classification capability yet; it's on the Superagent roadmap with no committed date. See Open Question 5.
• An unsupported document action (sign, acknowledge) is required Deferred: Superagent does not support document actions.
• Gateway detects unsupported front-end hints

Functional Behavior

1. During a conversation turn, the gateway owns evaluating whether any trigger condition above applies. This includes both host-capability checks (e.g., A2UI disabled) and any response element the gateway can't translate for the current transport/host — regardless of whether that element originated from a capability check or from what the agent decided it needed to do (e.g., requiring a document signature, a sensitive-topic UI context).
2. If a trigger condition is met, the gateway offers a deep link to the Novaworks portal that resumes the same conversation/session.
3. If the host surface can render the required interaction natively, no deep link is offered and the conversation continues unchanged.

Compatibility

Per the PRD's compatibility matrix (row: "Continue in Novaworks deep link"): Portal is Full, A2A and MCP are TBD. This capability is itself the fallback referenced by other capabilities in this PRD (Sections 2 and 3) when their primary rendering path isn't supported on a given transport.

Open Questions

1. ~~Which layer owns trigger detection for each condition~~ — Resolved: the Gateway/MCP proxy owns trigger detection uniformly. The gateway offers the deep link any time it hits a response element it can't translate for the current host, or the host has a required capability disabled (e.g., A2UI disabled). The agent doesn't need to explicitly signal conditions like sensitive-topic classification or unsupported document actions — those surface to the gateway as the same generic "couldn't render/translate" signal, not a distinct agent-originated trigger.
2. ~~What is the per-tenant threshold for conversation turn count / token length~~ — Resolved: per-tenant configuration is out of scope for now. Turn count threshold is 10, set via an environment variable (not per-tenant config) so it can be changed platform-wide without a code change, and so per-tenant configurability can be added later without a breaking change.
3. ~~What does the deep link actually carry~~ — Resolved (functional intent; exact payload is a technical/implementation choice): more than just a conversation ID. At minimum, the link must let the portal drop the user directly into the right resumed state — e.g., a private chat opens directly into that private chat, rather than a generic landing view the user then has to navigate from. The specific payload shape (session ID plus trigger context, a signed token, etc.) is left to implementation.
4. ~~Does the resumed portal session need any of the re-sync behavior from Section 5~~ — Resolved: no. Nova records the full conversation regardless of originating channel, so the portal session resumed via this deep link is always current as of the moment it's opened. Section 5 re-sync behavior only applies when the user later returns to a non-Nova host surface, not to the portal itself.
5. Open — deferred, not blocking: the sensitive-topic trigger condition depends on Superagent's sensitive-topic classification capability, which doesn't exist yet (roadmap item, no committed date). This spec's fallback mechanism will support that trigger once it does — no design change is expected here, since the gateway's generic "couldn't translate" detection (Open Question 1) already covers it without needing a distinct signal. Unblock condition: Superagent's sensitive-topic detection capability ships (link its tracking issue here once one exists). Not scheduled by a date on this spec.

Dependencies / Related Sections

• Section 2 — Notifications and Async Activity Signals: nudges use this same deep-link mechanism as their fallback (see ../notifications/spec.md, Dependencies).
• Section 3 — Structured Input Collection: NovaworksCollectionSpec.fallback_url is expected to point through this mechanism when a host can't render a collection request.
• Section 5 — Re-sync Chat with Host Surface: governs what happens if the user later returns to a non-Nova host surface after acting in the portal; not applicable to the portal session itself (see Open Question 4).

Risks

Risk	Severity	Mitigation
Gateway's generic "couldn't translate" fallback fires too broadly (or misses cases), since it's a single detection path for conditions of very different character (capability-disabled vs. sensitive-topic vs. document action)	Medium	Define the specific set of untranslatable-response markers the gateway checks for per trigger condition; validate against all conditions in Trigger Conditions during implementation.
Transport support gap (A2A/MCP marked TBD) leaves no fallback at all on those surfaces	Medium	This feature is itself the fallback of last resort — confirm at minimum a URI/text link can be delivered over A2A and MCP even without richer rendering.
Sensitive-topic conversations have no fallback of any kind until Superagent ships sensitive-topic classification (Open Question 5)	Medium	Track as blocked-by on this feature's GitHub issue against Superagent's sensitive-topic-detection roadmap item; re-evaluate once that capability lands — no design change expected on this side.

Testing Needed

1. A2UI-disabled host receives a form → deep link offered. On a host with A2UI support disabled, drive a conversation to a point where the agent needs to render a form. Verify the gateway detects the untranslatable response element, offers a "Continue in Novaworks" deep link (no raw form or silent failure), and that opening the link resumes the same conversation directly inside the correct state in the portal (e.g., the private chat containing that turn), not a generic landing page.
2. Turn-count threshold trigger. Configure the turn-count environment variable to a small test value (e.g., 3) and drive a conversation past that count with no other trigger condition present. Verify the deep link is offered once the threshold is exceeded, and is not offered on turns at or below the threshold. Confirm changing the env var (no code change) shifts the trigger point accordingly, validating Open Question 2's resolution.
3. Host that natively supports the required interaction → no deep link. Repeat scenario 1's form-rendering case on a host with A2UI enabled. Verify the gateway does not offer the deep link and the conversation continues natively on the host — confirming the negative path from Functional Behavior step 3 and that the generic detection doesn't over-fire.
4. Deep link delivered over a TBD transport (A2A/MCP). On an A2A or MCP-connected host, trigger any in-scope condition (e.g., turn-count threshold). Verify at minimum a URI/text deep link is delivered even without rich rendering support, addressing the Risks-table gap that A2A/MCP fallback isn't proven end-to-end.

---

Novaworks AI | Confidential