promptkit/docs/roadmap/conversation-continuation.md

# Conversation Continuation And Application-Directed Interaction

Status: proposed feature roadmap; open decisions await discussion. No
implementation is authorized by this document. Recommendations below are not
accepted contracts, except for the guiding principle explicitly recorded below.

## North Star: Content-Neutral, Generally Useful Capabilities

**Accepted direction:** evaluate each capability for its usefulness across
different downstream applications. PromptKit must be able to implement it and
explain its value without assuming or inferring the meaning of the content
passed through prompts and responses.

PromptKit can own conversation and execution mechanics: captured messages,
continuations, independent branches, execution relationships, budgets,
cancellation, observations, and usage. Applications own the interpretation of
responses and their reasons for choosing the next action. Repair, analysis,
clarification, and branching exploration are examples of consumer workflows
that could use the same mechanisms.

Coordination and looping remain open questions. Neither is presumed necessary
or excluded. Assess their value as generally useful capabilities, rather than
as an implementation of Audita's repair loop. A coordinator, if selected,
would execute application-directed interactions without needing to understand
why the application requests another turn or stops.

Apply two questions to proposed public concepts and implementation machinery:

1. Can their value be explained using conversation and execution concepts alone?
2. Can different applications use them without translating their domain into
   repair-specific concepts?

Audita supplies concrete evidence of need and acceptance examples; its workflow
does not define PromptKit's abstraction. Terms such as rejected candidate,
accepted revision, and withdrawal belong to the consuming application. This
direction concerns the new capabilities and does not rename or expand
PromptKit's existing structural-output repair functionality.

## Purpose And Scope

This roadmap records PromptKit's design questions arising from
[Audita's feature request](audita-request.md). That request owns the consumer
workflow and requested acceptance scenarios; this document owns the proposed
PromptKit direction, discussion order, and eventual implementation sequencing.

The proposed capabilities are:

- Capture a rendered request and its final assistant content, then continue it
  using ordinary configured prompts without reconstructing the original request.
- Allow independent continuations from one captured exchange.
- Consider coordination and bounded looping using application-supplied next
  actions and follow-up requests.

Continuation has direct value by removing consumer capture, reconstruction,
prefix comparison, and history assembly. A coordinator could also remove
repeated lifecycle work, if its general value justifies its public contract.
Audita would continue owning candidate selection, domain validation, feedback
meaning, branch scheduling, accepted sibling proposals, and transcript changes.
Its domain-specific repair code would not move wholesale into PromptKit.

The request needs in-process use. Persistent sessions, restartable workflows,
conversation storage, and batch-item reconciliation are outside its scope.
The existing [prepared execution handle](../../prepared_execution.go) remains a
single-use execution capability; continuation needs its own semantics.

## Open Decisions In Discussion Order

### 1. What Does A Captured Exchange Contain?

**Status: open.** Decide whether capture represents a logical conversation or
the complete sequence of provider requests, including structural repair.

**Recommendation:** capture the complete rendered request, preserving message
content, roles, and cache metadata, followed by the final assistant content
returned by the run. An initial run that needed structural repair would retain
its final content without adding the internal corrective instructions to the
logical conversation. This supplies reusable context for subsequent turns while
keeping transport attempts and structural repair separate from application
turns. It also matches Audita's requested history.

Make capture opt-in. A continuation would append its rendered follow-up messages
and final response to produce a new exchange, leaving the source exchange and
other branches unchanged. Previously rendered history would not require the
original input files or templates to be rendered again.

**Alternative:** retain the actual corrective messages and responses that led
to the final output. This provides more execution detail, but increases retained
content and carries internal repair instructions into later model context.
Attempt diagnostics can serve that need separately if a consumer requires it.

**Details to settle:** capture availability after structural validation
exhaustion or an operational failure; how callers request capture for ordinary
and prepared runs; and the ownership and engine-binding of captured exchanges.
The request's “full final assistant response” should refer to the content
supported by PromptKit, without silently adding a raw provider-envelope API.

### 2. How Are Follow-Up Execution Settings Selected?

**Status: open.** Decide which settings come from the follow-up request and
which, if any, carry forward from the originating exchange.

**Recommendation:** preserve conversation content while resolving the new
profile and output contract through the follow-up prompt and ordinary request
overrides. The follow-up can therefore use a different model and response
schema without modifying the original exchange. Reuse existing selection and
precedence rules rather than adding another settings-resolution system.

In particular, prefer the follow-up prompt's default profile when no explicit
profile is supplied, with the ordinary missing-profile behavior if neither is
available. Do not retain the original direct credential merely to retain
conversation history; resolve credential supply for the new execution.

**Alternative:** inherit the originating execution's profile and settings unless
overridden. This is convenient for repeated turns against the same model, but
adds another precedence source and can make a follow-up prompt's defaults
surprising. Inheriting an old output contract is especially unsuitable when
proposal and revision responses have different shapes.

**Details to settle:** session-ID inheritance versus follow-up template
resolution, explicit overrides, credential lifetime, and the ordering of
follow-up definition messages and caller-appended messages. Preserve authored
roles rather than silently rewriting follow-up system or developer messages.

### 3. Should PromptKit Coordinate Turns, And Where Does Application Work Run?

**Status: open.** Evaluate whether a coordinator or loop provides generally
useful behavior beyond continuation primitives. If selected, determine its
scope and a lifecycle that permits application callbacks to call the same
engine and backend, including with capacity limited to one.

The current [run flow](../internal/runner.md#run-flow) retains logical admission
through structural validation and repair. Releasing an active generation permit
alone does not release that admission lease.

**Recommendation:** assess the value across repair, analysis, and branching
conversation examples before choosing the abstraction. If PromptKit provides
coordination, compose completed executions: finish a turn and release its
admission lease before invoking application work. Each later turn receives
ordinary admission. A coordinator would hold no backend capacity while awaiting
application work. This reuses existing execution machinery and permits
callbacks to make their own model calls without interpreting their purpose.

**Alternative:** provide continuation and observation primitives while leaving
looping to consumers. This keeps PromptKit's API smaller, but may leave repeated
execution and accounting coordination downstream. Compare the actual consumer
work under both approaches. Extending the structural-repair loop is another
possible implementation route, but would require changing lease ownership and
decoupling it from repair-specific assumptions.

**Details to settle:** whether to provide coordination, looping, or both; scope
over a single branch versus multiple branches; callback cancellation boundaries;
and the sequence of request construction, execution, and application decisions.
Applications retain the meaning of those decisions and policy for stopping
other work after a failure.

### 4. How Are Application Next Actions And Execution Outcomes Represented?

**Status: open.** Subject to Decision 3, define content-neutral next actions and
distinguish application-directed completion, budget exhaustion, interruption,
and operational failure.

**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.

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.

**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.

**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. If coordination is left
to consumers, limit this decision to continuation execution outcomes.

### 5. How Are Related Executions And Usage Accounted For?

**Status: open.** Define accounting for the initial exchange, each continuation,
its structural repairs and transport retries, and model calls made by
application callbacks, whether or not PromptKit supplies a coordinator.

The current [observation boundary](../internal/observation.md) keeps nested
invocations independent. A callback's arbitrary model calls cannot simply be
assumed to belong to the enclosing interaction's totals.

**Recommendation:** preserve independent run accounting and add explicit
relationships between exchanges, branches, and associated runs, with sequence
relationships if coordination is selected.
Choose a small association mechanism, such as a scoped observation facility or
explicit execution references, so consumers need not rebuild lifecycle tracking.
Shared initial work should be referenced by branches and counted once when
reporting the combined operation. Report available usage with its existing
presence/completeness meaning; do not promise complete cost accounting.

**Alternative:** have PromptKit automatically capture every nested run during an
application callback. This minimizes explicit association but can include
unrelated work and changes the existing invocation-isolation boundary.
Another simpler option is to report continuation usage only and let applications
attach callback accounting; that leaves more work downstream and needs checking
against Audita's stated reporting requirement.

**Details to settle:** association of concurrent callback calls, observer
composition, failure-path diagnostics, and which totals include which child
executions. A turn budget would bound continuation attempts, not all provider
calls performed by structural repair, transport retries, or application work.

### 6. Where Should Continuation Inspection Live?

**Status: open.** Clarify the request's references to inspection without changing
the established resource-inspection boundary.

**Recommendation:** expose originating exchange, follow-up prompt, and execution
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.

**Alternative:** introduce a dedicated conversation inspection API. This may
be useful if a retained exchange needs a richer view, but should be justified
against a simple details method. Extending resource inspection with execution
history would give those APIs a different responsibility.

**Details to settle:** the minimum inspectable metadata, how callers explicitly
access captured message content, and separation of content-bearing details from
metadata-only observations. Public type names and serialization details belong
in implementation planning after this boundary is settled.

## Proposed Delivery And Validation

Resolve the decisions above before selecting exact public signatures or writing
an implementation plan. The recommended sequence is:

1. Deliver capture and independent continuation through the public facade,
   allowing Audita to remove its reconstruction and prefix-verification work.
2. If selected after evaluating general usefulness, build coordination and/or
   bounded looping on that capability, reusing ordinary execution, validation,
   capacity, and observation machinery.

Use [Audita's acceptance scenarios](audita-request.md#suggested-delivery-and-acceptance-scenarios)
as consumer checks, alongside analysis and branching-conversation examples that
exercise the same APIs without repair-specific concepts. Additional proposed
coverage should establish:

- The selected conversation history when the initial run needed structural
  repair, including use of its full final assistant content.
- Continuation after the original input files change or disappear, without
  altering the captured history.
- Independent branches retaining their own history and outcomes.
- Assessment calls against the same backend at capacity one, without capacity
  retained by the coordinator blocking them.
- Associated validator usage and shared initial usage reported without
  double-counting, including incomplete usage and operational failures.

These are planning targets, not new implemented guarantees. Keep additional
mechanisms and constraints tied to the selected decisions and demonstrated
consumer needs.