From c948fef8fc72d2e714c2280021fcafb3799ce2e7 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Wed, 11 Nov 2026 21:54:06 +0000 Subject: [PATCH] Record zero-turn budget and callback cancellation decisions --- docs/roadmap/conversation-continuation.md | 82 +++++++++++++++++------ 1 file changed, 62 insertions(+), 20 deletions(-) diff --git a/docs/roadmap/conversation-continuation.md b/docs/roadmap/conversation-continuation.md index 607c238..f790af8 100644 --- a/docs/roadmap/conversation-continuation.md +++ b/docs/roadmap/conversation-continuation.md @@ -175,12 +175,12 @@ interpret the purpose of that work. questions without demonstrated shared answers across consumers. Applications can build those workflows from the selected branch-level capabilities. -**Details to settle:** callback cancellation boundaries, exact request/stop and -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. +**Details to settle:** exact request/stop and outcome types, and remaining +error/report semantics belong to Decision 4. That decision records accepted +response delivery, zero-turn budget behavior, and cancellation boundaries. +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 @@ -263,18 +263,20 @@ corrections and other branches remain with Audita. Both sketches omit application-specific error handling and depict normal turn 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. +earlier responses, as accepted in Decision 4. That decision also defines zero-turn +budgets and cancellation around callback delivery; remaining operational-error +details are 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: 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. +**Status: normal response delivery, exhaustion, zero-turn budgets, and callback +cancellation decisions 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 @@ -286,14 +288,54 @@ 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 +callbacks. Cancellation can interrupt normal delivery as specified below; +remaining operational-failure delivery semantics are open. `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. +**Accepted zero-turn behavior:** with an active context, invoke the initial +callback once even when the additional-turn budget is zero. The callback receives +the starting exchange and knows that no additional turns remain; this is not +delivery of a newly generated response. It can use existing application state +without repeating earlier assessment. + +- `Stop` produces application-directed completion. +- Requesting another turn produces exhaustion without executing the request. +- Returning an error produces an operational failure, subject to the + cancellation checks below. + +Zero bounds coordinator-driven continuation executions, not work inside the +application callback. The callback can still consult data or make model calls. +Applications wanting to disable all such work can skip invoking the coordinator. +The alternative of treating zero as an immediate no-op with no callback is not +selected: it would introduce special behavior and would not distinguish an +already-complete interaction from one requesting more work. + +**Accepted cancellation behavior:** check the caller's context immediately +before callback invocation, including the initial callback. If cancellation is +already observed, do not invoke the callback; report interruption and preserve +the context error identity. Preserve completed-turn information already obtained +by the coordinator in the returned report without implying that the application +processed or accepted it. This does not require recovering a response that a +failed underlying execution did not return. + +Cancellation can race with callback invocation. The callback receives the same +context and is responsible for cooperating with cancellation during its work. +PromptKit checks the context again after the callback returns and before starting +another execution. It does not forcibly terminate callback code. Thus ordinary +response delivery is once per completed turn during normal progression, while +cancellation can interrupt that progression. Preserving available completed work +on interruption does not create a separate final-response processing path during +normal budget exhaustion. + +The alternative of invoking the callback after cancellation with a canceled +context is not selected. It could help callbacks that only record results, but +callbacks may perform substantial application work or model calls; PromptKit +cannot assume they are merely bookkeeping. + **Recommendation:** let the application request another turn or indicate that the interaction should stop, separately from reporting an operational error. PromptKit need not know whether the application is repairing, investigating, @@ -313,12 +355,12 @@ 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:** 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. +**Details to settle:** exact next-action and outcome types; remaining operational +error and result-plus-error behavior beyond the accepted interruption report; +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?