eric/promptkit
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Document per-run session and reasoning overrides

Browse Source
This commit is contained in:
Eric Rakestraw
2026-07-29 19:47:39 +00:00
parent f6ee18f6b3
commit 0a839aa16d
7 changed files with 73 additions and 24 deletions
Download Patch File Download Diff File Expand all files Collapse all files

35
docs/internal/runner.md
View File

@@ -31,8 +31,8 @@ The runner has no durable run or session store.
`Prepare` performs the reusable pre-generation workflow:
1. validate the prompt selection and load the prompt definition;
2. hash the loaded definition;
1. validate the required prompt selection and normalize any direct session ID;
2. load the prompt definition and hash the original definition;
3. select the request profile or the prompt's default profile;
4. resolve the profile's backend ID, when present;
5. resolve application-neutral defaults, backend defaults, profile values,
@@ -41,7 +41,8 @@ The runner has no durable run or session store.
7. resolve the output contract and load a structured-output schema when
required;
8. load and hash input artifacts;
9. render and hash the prompt; and
9. render messages, resolve the effective session ID, and hash the effective
rendered prompt; and
10. return the effective settings, source identities, messages, hashes, and
preparation timing.
@@ -54,6 +55,15 @@ apply in that order. A profile requiring a direct key clears an inherited
backend environment name unless the request supplies its own name. Secret
values remain excluded from serialized metadata.
Reasoning overrides are tri-state: nil inherits the profile, a pointer to a
nonblank string trims and replaces it, and a pointer to a blank string clears
it. A nonblank direct session is normalized before source loading, bypasses
the prompt session template, and is applied after ordinary message rendering.
A blank direct value retains prompt-template behavior. The runner clears the
template only on a value copy of the definition, so the definition hash always
describes the original source while the rendered-prompt hash includes the
effective direct or rendered session.
The registry is read-only after engine construction. Concurrent `Prepare` and
`Run` calls resolve independent defensive backend values and keep all
invocation state local.
@@ -71,10 +81,11 @@ target, validation errors, prior output, and structured-output specification.
This capability remains internal and is not a public option.
A successful result includes the output artifact and raw output, validation
state, prompt and rendered-prompt hashes, selected profile and backend,
effective settings, input hashes, token usage, a generated run identifier, and
UTC timing. The same effective target, including backend identity, reaches
generation and any repair attempt.
state, effective session ID, prompt and rendered-prompt hashes, selected
profile and backend, effective settings, input hashes, token usage, a generated
run identifier, and UTC timing. The same effective session reaches generation
through the rendered prompt. The same effective target, including backend
identity, reaches generation and any repair attempt.
## Failure Categories
@@ -84,16 +95,18 @@ validation failures. Wrapping preserves the package identities mapped by the
public facade and retains collaborator identities where they are part of the
internal contract. Context cancellation propagates through the invoked
collaborator and is classified by the owning operation.
An overlong direct session is an invalid request before source loading, while
an invalid or overlong prompt session template remains a prompt-render failure.
An unknown selected backend, or a selected backend with no configured resolver,
is classified as a profile-load failure.
## Test Ownership And Changes
The [runner tests](../../internal/usecase/runner_test.go) own preparation order,
selection and override precedence, schema-before-generation behavior, hashing,
generation and validation outcomes, backend propagation, bounded repair,
credentials and redaction, error categories, artifact metadata, usage, and
timing.
selection and override precedence, direct-session resolution,
schema-before-generation behavior, hashing, generation and validation
outcomes, backend propagation, bounded repair, credentials and redaction,
error categories, artifact metadata, usage, and timing.
Changes to orchestration should continue to use the existing package
interfaces, keep request state local to an invocation, and preserve `Run`'s use