From b423de12c3bcf7cc59fff71acb530493b1502481 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Sat, 14 Nov 2026 00:54:59 +0000 Subject: [PATCH] Clarify continuation ordering and API planning --- docs/roadmap/conversation-continuation.md | 32 +++++++++++++++++++---- 1 file changed, 27 insertions(+), 5 deletions(-) diff --git a/docs/roadmap/conversation-continuation.md b/docs/roadmap/conversation-continuation.md index 559b6cc..153a68d 100644 --- a/docs/roadmap/conversation-continuation.md +++ b/docs/roadmap/conversation-continuation.md @@ -73,6 +73,11 @@ adds the rendered follow-up messages and final response to a new exchange, leavi the source and independent branches unchanged. No previous templates or input files need to be read or rendered again. +Avoid unnecessary repeated copying of retained history where practical, while +preserving independent branches and detached inspection values. Internal sharing +of immutable history is an implementation option, not a required representation +or a public allocation or complexity guarantee. + Another engine instance in the same process can continue the exchange, applying its own configuration to the new request. The originating engine is not required. This permits application engine replacement without promising serialized or @@ -196,8 +201,17 @@ using the receiving engine's existing rules. In particular: History introduces no additional execution-setting precedence. The follow-up can change model or response schema without altering the original exchange. -Exact assembly order for captured history, follow-up definition messages, and -caller-appended messages remains an API-planning detail; preserve authored roles. + +Assemble each continuation's messages in this order: + +1. The captured logical history, including its final assistant content. +2. The rendered follow-up prompt definition messages, in definition order. +3. The follow-up request's caller-appended messages, in caller order. + +Preserve authored roles and message content; do not move messages based on role. +Continuation adds no history-size limit or automatic truncation. Upstream +context-window or other request rejections follow ordinary generation-error +behavior. ### Capacity And Application Work @@ -378,13 +392,15 @@ API without manual history assembly or per-turn lifecycle bookkeeping. ## API Planning And Delivery -No product-level decisions remain open. Design exact types and signatures within -the accepted behavior above: +No product-level decisions remain open. The companion implementation plan should +settle exact public types and signatures before implementation, within the +accepted behavior above: - Capture opt-in syntax and exchange representation. Prefer a request option; separate capture methods remain viable. Prefer a details accessor, while a public value is viable if it preserves ownership and generic rendering. -- Continuation message assembly order and placement of immediate-parent metadata. +- Continuation request shape and placement of immediate-parent metadata, using + the message assembly order defined above. - Callback state, next-action types, normal outcomes, and the optional undelivered-response result. - Collector attachment, observer composition, and summary field representation. @@ -392,6 +408,12 @@ the accepted behavior above: only if concrete ordinary/prepared/coordinator/callback usage sketches expose awkwardness; either approach uses existing observation machinery. +Check the concrete API against both consumer sketches and ordinary and prepared +execution, including capture selection, exchange access, coordinator actions and +results, and observer composition. Keep these choices consistent across the +staged plan rather than leaving each implementation stage to choose its own +public contract. + Deliver in separable stages: 1. **Capture and independent continuation:** expose execution-derived exchanges,