From bc95d1f9fdf8cbf9675dc3b2c26e9b26d8137a99 Mon Sep 17 00:00:00 2001 From: Eric Rakestraw Date: Thu, 12 Nov 2026 19:58:24 +0000 Subject: [PATCH] Keep coordinator termination contract minimal --- docs/roadmap/conversation-continuation.md | 109 ++++++++++++++-------- 1 file changed, 69 insertions(+), 40 deletions(-) diff --git a/docs/roadmap/conversation-continuation.md b/docs/roadmap/conversation-continuation.md index f790af8..aa21012 100644 --- a/docs/roadmap/conversation-continuation.md +++ b/docs/roadmap/conversation-continuation.md @@ -140,7 +140,7 @@ authored roles. This does not reopen the accepted execution-setting precedence. ### 3. Should PromptKit Coordinate Turns, And Where Does Application Work Run? -**Status: accepted; exact callback and reporting contracts remain open.** Provide +**Status: accepted; exact public types and accounting details remain open.** Provide independently usable continuation primitives and an optional sequential coordinator for one branch. The application selects each next request or decides to stop. PromptKit manages turn progression and execution bookkeeping under the @@ -175,9 +175,9 @@ 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:** 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. +**Details to settle:** exact request/stop and outcome types, and turn-budget +consumption belong to Decision 4. That decision records accepted response +delivery, zero-turn budgets, cancellation, and minimal error/result semantics. 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. @@ -210,11 +210,11 @@ choose_next(ctx, turn): vars = {"question": question} )) -report, error = coordinate( +termination, error = coordinate( ctx, start = initial_exchange, additional_turns = 3, next = choose_next ) -application.present_analysis(analysis, report, error) +application.present_analysis(analysis, termination, error) ``` PromptKit preserves the history and performs each selected execution. It does @@ -247,11 +247,11 @@ choose_next(ctx, turn): vars = audita.follow_up_variables(branch) )) -report, error = coordinate( +termination, error = coordinate( ctx, start = initial_exchange, additional_turns = 3, next = choose_next ) -audita.record_branch_outcome(branch, report, error) +audita.record_branch_outcome(branch, termination, error) ``` The first callback uses existing findings, so initial batch validation is not @@ -264,17 +264,18 @@ 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. 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. +budgets, cancellation around callback delivery, and a minimal termination result. +The sketches do not imply an archive of responses in that result: applications +already receive each completed response through the callback. 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, exhaustion, zero-turn budgets, and callback -cancellation decisions accepted; remaining outcome and failure details open.** +**Status: response delivery, exhaustion, zero-turn budgets, cancellation, and +minimal error/result semantics accepted; turn-budget consumption remains open.** The coordinator uses content-neutral next actions and distinguishes application-directed completion from exhaustion. @@ -288,9 +289,9 @@ 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 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. +callbacks. Cancellation and operational errors can interrupt normal delivery as +specified below. `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 @@ -316,11 +317,12 @@ 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. +already observed, do not invoke the callback; return the context error with its +identity preserved. If the coordinator already obtained a completed response +that has not been delivered to the callback, preserve that single response in +the optional result described below. This does not imply application processing +or acceptance, or 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. @@ -336,31 +338,56 @@ 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, -or exploring. Permit starting from an existing exchange and application state -without forcing the application to repeat earlier work. +**Accepted operational-failure behavior:** each continuation is an ordinary +execution supplied with captured conversation history. Applications receive +completed responses through the callback before another continuation begins. +An execution or callback error stops coordination and propagates to the caller, +preserving useful Go error identities. PromptKit does not automatically replay +the failed continuation or callback. Existing transport retries and structural +repair remain within ordinary execution. Earlier callback deliveries and +application work remain intact; applications decide whether the failure affects +other branches or the overall workflow. -Return execution diagnostics that preserve completed work when an interaction -stops. A completed model call does not imply application acceptance of its -content. Audita would map its own acceptance, rejection, withdrawal, and -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. +**Accepted minimal return contract:** provide only the following information: + +- An ordinary Go error for execution failures, callback failures, and + cancellation, preserving `errors.Is`/`errors.As` behavior. +- A small outcome value distinguishing application-directed stopping from + budget exhaustion on normal termination. These outcomes are not errors. +- An optional completed response when cancellation prevented its delivery to + the callback. Reuse existing response types where practical. + +Delivery means the callback was invoked with the response; it does not imply +the application finished processing or accepted it. If that callback returns +an error, the response is not classified as undelivered or automatically +delivered again. The coordinator returns no archive of previously delivered +responses. A small optional result accommodates the undelivered-response case; +exact Go declarations remain for implementation planning. + +Failure-stage fields, additional run-ID references, a separate failure +classification hierarchy, and aggregate reporting are not part of this minimal +termination contract. They require a demonstrated consumer need before addition. +This does not remove fields from existing response values or observation APIs. +Decision 5 separately evaluates accounting, and Decision 6 inspection, without +presuming that either needs to expand the coordinator's termination result. + +Audita retains its own meanings for acceptance, rejection, withdrawal, and +assessment unavailability. A normal stop does not assert any of those outcomes. **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. +distinguish from failure. Normal stopping uses an explicit action, while failures +use ordinary Go errors. A broader structured termination report was also +considered and not selected: its additional metadata is unnecessary for the +demonstrated minimal contract. -**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. +**Details to settle:** what consumes an additional-turn budget when preparation +or generation fails. Keep that budget distinct from structural repair and +transport retry. Exact next-action, outcome, and optional-result types remain +implementation planning details. Whether a completed run with failed structural +validation produces a reusable exchange remains a Decision 1 question; the +operational-error decision does not reclassify that validation result. ### 5. How Are Related Executions And Usage Accounted For? @@ -402,6 +429,8 @@ relationships in continuation details, prepared execution metadata, sequence reports, and observations as appropriate. Keep `InspectPrompt`, `InspectProfile`, and `InspectBackend` focused on their configured resources. Reuse the existing approach to generically renderable inspection data where new details are exposed. +Any proposed report should demonstrate its consumer value; Decision 4's minimal +termination contract does not promise a sequence report or response archive. **Alternative:** introduce a dedicated conversation inspection API. This may be useful if a retained exchange needs a richer view, but should be justified