Record generation output and subprocess requirements
This commit is contained in:
@@ -80,6 +80,26 @@ Application-specific wiring remains to be designed, but inclusion of these
|
|||||||
three capabilities is settled. Prepared-request preview and the future of
|
three capabilities is settled. Prepared-request preview and the future of
|
||||||
`render` remain a separate discussion below.
|
`render` remain a separate discussion below.
|
||||||
|
|
||||||
|
### Generation and subprocess requirements
|
||||||
|
|
||||||
|
Decision recorded 2026-11-19: optimize the default generation response for the
|
||||||
|
majority of consumers, who want only the raw resulting artifact. Metadata is
|
||||||
|
optional. Consumers requesting it may receive it inline with the content or in
|
||||||
|
a separately saved report; either is acceptable, and both may be supported if
|
||||||
|
convenient. Supporting both delivery modes is not a requirement.
|
||||||
|
|
||||||
|
Prefer native CommandKit reporting and PromptKit result types before introducing
|
||||||
|
a Scriptorium-specific response format. A failure must produce a nonzero process
|
||||||
|
status and information explaining the failure. This does not require a new
|
||||||
|
structured error envelope: native diagnostics are an acceptable way to deliver
|
||||||
|
that information.
|
||||||
|
|
||||||
|
Scriptorium remains a neutral interface to PromptKit. Pass through the errors,
|
||||||
|
validation outcomes, and result information that PromptKit supplies rather than
|
||||||
|
adding independent judgments about generated content or redefining upstream
|
||||||
|
failure semantics. Adapting those outcomes to CommandKit and process exit codes
|
||||||
|
is application work; deciding what constitutes a PromptKit failure is not.
|
||||||
|
|
||||||
## Upstream baseline
|
## Upstream baseline
|
||||||
|
|
||||||
The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and
|
The initial review covered CommandKit **v0.7.0**, ckconfig **v0.9.0**, and
|
||||||
@@ -107,22 +127,34 @@ not requirements to reproduce during migration.
|
|||||||
|
|
||||||
### 1 Generation output and process outcomes
|
### 1 Generation output and process outcomes
|
||||||
|
|
||||||
The starting proposal is to keep generated artifact bytes easy to consume,
|
The consumer requirements above are settled. The proposed native composition is
|
||||||
with execution metadata separately available. CommandKit supports both raw
|
a CommandKit `Report` whose value is PromptKit's `RunResult`, with a text
|
||||||
output and structured reports; using it does not require wrapping generated
|
template that emits only generated content. Default/text output would serve
|
||||||
artifacts in a report envelope.
|
artifact consumers; standard JSON/YAML formats would expose the native result
|
||||||
|
and its metadata. This uses CommandKit's existing reporting mechanism and
|
||||||
|
PromptKit's existing result shape; ckprompt does not supply a general generation
|
||||||
|
command or prescribe this composition. Confirm this choice and decide whether
|
||||||
|
separate report-file delivery adds enough value to include it as well.
|
||||||
|
|
||||||
Decide the new generation interface: stdout versus explicit file output,
|
PromptKit's `RunResult` includes content, validation, selected resources, usage,
|
||||||
execution-report delivery, and how those choices interact with standard format
|
and timing. Operational failures return no partial `RunResult`; observer events
|
||||||
and verbosity controls. In particular, quiet mode suppresses CommandKit output
|
separately expose terminal metadata, retry counts, and presence-aware usage.
|
||||||
but does not cancel execution; application-owned file effects need an explicit
|
Do not invent an empty or synthetic success result to represent a failure.
|
||||||
design. Ordinary diagnostics should follow upstream reporting conventions.
|
Use native failure diagnostics, and consider additional observation reporting
|
||||||
|
only if a concrete consumer need warrants it.
|
||||||
|
|
||||||
Adopt upstream usage and operational outcomes, then decide how to represent
|
Settle explicit artifact-file output and its interaction with report selection
|
||||||
generated-output validation failure as an application domain outcome. The
|
and standard verbosity controls. Quiet mode suppresses CommandKit output but
|
||||||
current use of exit 2 for that failure conflicts with CommandKit's usage and
|
does not cancel execution; application-owned file effects need an explicit
|
||||||
invalid-configuration convention. Also settle output/report write failures and
|
design.
|
||||||
how callers distinguish them from generation or validation failures.
|
|
||||||
|
Map PromptKit's typed errors and reported outcomes into CommandKit conventions,
|
||||||
|
preserving its distinction between a completed content check reporting
|
||||||
|
`ValidationFailed` and an operational error. Select any necessary domain exit
|
||||||
|
code without reusing the current validation-failure exit 2, which conflicts with
|
||||||
|
CommandKit's usage convention. Also specify artifact/report delivery failures
|
||||||
|
using CommandKit's presentation-failure behavior where applicable. These are
|
||||||
|
adapter mappings, not a new application validation policy.
|
||||||
|
|
||||||
Signal cancellation and the whole-operation deadline remain application
|
Signal cancellation and the whole-operation deadline remain application
|
||||||
responsibilities. Decide their mapping to the CommandKit invocation context
|
responsibilities. Decide their mapping to the CommandKit invocation context
|
||||||
|
|||||||
Reference in New Issue
Block a user