diff --git a/docs/roadmap/conversation-continuation.md b/docs/roadmap/conversation-continuation.md index b247f52..607c238 100644 --- a/docs/roadmap/conversation-continuation.md +++ b/docs/roadmap/conversation-continuation.md @@ -176,10 +176,11 @@ interpret the purpose of that work. can build those workflows from the selected branch-level capabilities. **Details to settle:** callback cancellation boundaries, exact request/stop and -outcome types, final-turn delivery at budget exhaustion, and error/report -semantics belong to Decision 4. Execution association and usage accounting belong -to Decision 5. The sketches below illustrate the selected responsibility split; -they do not settle those public contracts. +outcome types, and error/report semantics belong to Decision 4. That decision +records the accepted normal delivery of the last permitted response. Execution +association and usage accounting belong to Decision 5. The sketches below +illustrate the selected responsibility split; they do not settle the remaining +public contracts. #### Illustrative Consumer Sketches @@ -261,18 +262,37 @@ can start separate coordinators from the same initial exchange; accepted sibling corrections and other branches remain with Audita. Both sketches omit application-specific error handling and depict normal turn -progression. They do not prescribe how callback errors or the final result at -the budget boundary are delivered; Decision 4 must specify those paths so the -application can handle completed work without mistaking it for accepted content. +progression. The final permitted response follows the same callback path as +earlier responses, as accepted in Decision 4. Callback errors, zero-turn budgets, +and cancellation around delivery remain open there. Completed work must not be +mistaken for application acceptance of its content. The concrete interface should let both examples use the same coordination mechanism without manual message-history assembly or per-turn lifecycle bookkeeping. Callback model-call association remains part of Decision 5. ### 4. How Are Application Next Actions And Execution Outcomes Represented? -**Status: open.** For the coordinator selected in Decision 3, define -content-neutral next actions and distinguish application-directed completion, -budget exhaustion, interruption, and operational failure. +**Status: normal response delivery and exhaustion decision accepted; remaining +outcome and failure details open.** The coordinator uses content-neutral next +actions and distinguishes application-directed completion from exhaustion. + +**Accepted normal flow:** deliver each completed response once through the +ordinary application callback, including the last permitted response. If the +callback returns `Stop`, report application-directed completion. If it requests +another turn and none remain, report exhaustion without executing that request. +Using the entire budget does not itself imply exhaustion; exhaustion means the +application requested additional work that the budget would not permit. + +This gives consumers one response-processing path, including any application +validation, without a separate path for the final response. Internal transport +retries and structural repairs do not produce additional conversation-response +callbacks. Cancellation and operational-failure delivery semantics remain open; +this normal-flow decision does not settle those cases. `Stop` and other API +spellings remain illustrative until public types are selected. + +**Alternative considered, not selected:** stop immediately when the turn budget +is used and expose the final response only in the report. This avoids another +callback but requires separate consumer processing of the final response. **Recommendation:** let the application request another turn or indicate that the interaction should stop, separately from reporting an operational error. @@ -287,17 +307,18 @@ unavailable-assessment outcomes to the selected generic controls. Cancellation and operational errors should retain useful Go error identities. Applications decide whether a stopped branch affects independent work. -**Alternative:** use callback errors to signal ordinary termination as well as -operational failure. This can reduce the number of result types, but makes -normal control flow harder to distinguish from failure. Compare it against a -small explicit next-action result without introducing domain-specific statuses. +**Alternative considered, not selected for normal termination:** use callback +errors to signal ordinary termination as well as operational failure. This can +reduce the number of result types, but makes normal control flow harder to +distinguish from failure. The accepted normal flow uses an explicit stop action; +the operational-error contract remains to be selected. -**Details to settle:** next-action and outcome vocabulary, callback/result types, -result-plus-error behavior, zero-budget behavior, and what consumes an -additional-turn budget when preparation or generation fails. Keep such a budget -distinct from structural repair and transport retry. Specify how an application -receives the last completed response when no further turns remain, including -whether and how its callback is invoked at that boundary. +**Details to settle:** zero-turn budgets; cancellation before callback delivery, +during callbacks, and before subsequent execution; exact next-action and outcome +types; result-plus-error behavior; and what consumes an additional-turn budget +when preparation or generation fails. Keep that budget distinct from structural +repair and transport retry. Whether a failed execution produces a reusable +exchange remains a Decision 1 question. ### 5. How Are Related Executions And Usage Accounted For?