Retire the legacy CLI and document native operator workflows
This commit is contained in:
@@ -1,64 +1,67 @@
|
||||
# Subprocess Integration
|
||||
|
||||
This document covers process-boundary behavior for callers that invoke
|
||||
Scriptorium as a child process. Command syntax, flags, output, and exit codes
|
||||
are defined by the [CLI reference](../cli.md). Interface selection belongs in
|
||||
the [consumer integration overview](../consumers/api.md).
|
||||
Use the executable when a local process boundary is appropriate.
|
||||
The [CLI contract](../cli.md) owns exact command/flag/status syntax; the
|
||||
[consumer overview](../consumers/api.md) compares subprocess and HTTP use.
|
||||
|
||||
## Process Contract
|
||||
## Artifact-First Execution And Inspection
|
||||
|
||||
Use `scriptorium render` when the caller needs prepared output without a model
|
||||
call, and `scriptorium run` for generation. Pass an explicit `--config` or
|
||||
make the configuration search paths available to the child process; configuration
|
||||
discovery, fields, profile selection, and credential mechanisms are defined in
|
||||
the [configuration reference](../config.md).
|
||||
Select a stored prompt and capture its generated artifact from stdout. Use native
|
||||
requirements discovery before generated input files exist, concrete validation
|
||||
once bindings exist, and prepared preview to render without a model call.
|
||||
The [CLI migration guide](../consumers/upgrading-cli.md) explains replacements
|
||||
for older command and file-output conventions.
|
||||
|
||||
Pass required API-key environment variables through the child environment. Do
|
||||
not place raw API keys in arguments. Keep the environment limited to the values
|
||||
needed for the selected profile.
|
||||
Pass an explicit application configuration or deliberately arrange the child's
|
||||
[configuration discovery](../config.md). Supply only the environment needed for
|
||||
selected credentials; never put raw keys in arguments.
|
||||
|
||||
For application-only preflight, invoke `scriptorium config validate`; it exits
|
||||
0 with empty stdout when the application configuration loads, but does not
|
||||
prove that Promptkit sources or credentials are usable. `config show` emits
|
||||
resolved YAML and `config sources` emits newline-terminated JSON provenance.
|
||||
All three use the same source selection and explicit overrides as execution
|
||||
commands and require separate stderr capture for diagnostics. Their output can
|
||||
include source paths, identifiers, credential reference names, and ordinary
|
||||
backend parameters; treat it as potentially sensitive.
|
||||
Discovery completeness is distinct from binding satisfaction and execution
|
||||
readiness. Partial reports can succeed. Consumers own their binding graph and
|
||||
policy for incomplete findings; Scriptorium supplies no workflow state.
|
||||
|
||||
## Streams And Output Ownership
|
||||
## Streams, Reports, And Availability
|
||||
|
||||
Capture stdout and stderr separately. Stdout contains the requested artifact or
|
||||
prepared output unless the caller selects an output file; stderr contains
|
||||
summaries, diagnostics, and server messages. The exact destinations and status
|
||||
meanings are part of the [CLI reference](../cli.md), not a stable stderr data
|
||||
protocol.
|
||||
Capture stdout and stderr separately. Diagnostics are not a machine-readable
|
||||
error protocol, even when structured result output is selected. Prefer exit
|
||||
classification and native report fields; do not parse diagnostic prose.
|
||||
|
||||
When using `--out`, the caller owns the output path, its permissions, and
|
||||
cleanup. Treat rendered prompts, generated artifacts, stdout, and stderr as
|
||||
potentially sensitive.
|
||||
The default generated result is artifact content. Native structured results and
|
||||
optional separate reports carry the full returned result, including content and
|
||||
metadata. They are not the former metadata-only CLI observation report. Native
|
||||
prompt/prepared inspection also carries content. Treat all captured streams and
|
||||
reports as potentially sensitive.
|
||||
|
||||
For `run`, an optional [execution report file](../cli.md) contains terminal
|
||||
metadata separate from generated stdout or `--out`. The caller owns that
|
||||
path's permissions and retention. Output and report files are not a
|
||||
transaction: one may be written when the other fails, and a preexisting report
|
||||
may remain when the invocation has no terminal event. Check the exit status
|
||||
and diagnostics rather than assuming a report path contains this run's data.
|
||||
To save main output, supply a file as the subprocess stdout destination or use
|
||||
shell redirection. Omit quiet when that main result is needed: quiet suppresses
|
||||
it even for redirected stdout. A separately requested report remains an
|
||||
application file effect independent of quiet and main format selection.
|
||||
|
||||
A completed content-validation failure can still deliver an artifact/result;
|
||||
consumers decide whether it is usable. An operational failure with no result
|
||||
produces diagnostics and a nonzero status, not a synthesized result/error
|
||||
envelope. An existing separate report may then describe an older invocation.
|
||||
|
||||
## Partial Delivery And Caller Responsibility
|
||||
|
||||
Main output is attempted before a requested report, and report delivery is
|
||||
attempted even after main presentation failure. Either destination may contain
|
||||
partial data after an error. File delivery is not transactional and has no
|
||||
rollback or atomic-replacement promise.
|
||||
|
||||
Callers own redirected file creation/truncation, permissions, retention, and
|
||||
keeping destinations separate. A shell may truncate its file before the process
|
||||
starts, unlike a separate report that is opened only after a result exists.
|
||||
Check the finalized exit status and diagnostic stream; do not infer success or
|
||||
freshness from a file's existence.
|
||||
|
||||
## Cancellation And Recovery
|
||||
|
||||
A CLI invocation performs one synchronous request and creates no durable run
|
||||
state. A supervising process that needs cancellation must terminate the child
|
||||
process according to its own process-management policy. A later invocation is a
|
||||
new request and can make another model call; there is no resume or checkpoint
|
||||
protocol.
|
||||
Interrupt/SIGTERM cancels the child's invocation context. Engine cancellation is
|
||||
cooperative. The [whole-operation budget](../cli.md#generation) is separate from
|
||||
per-attempt provider timeouts and excludes process/configuration setup and
|
||||
delivery. Supervisors still own forced process termination when required.
|
||||
|
||||
For `run`, callers may set the [whole-run deadline](../cli.md) to bound the
|
||||
engine invocation. It is separate from the per-attempt generation timeout and
|
||||
does not include child startup or output writing. A typed operation deadline
|
||||
failure exits 1.
|
||||
Supervisors still own process termination when they need to stop the child
|
||||
outside that engine interval.
|
||||
|
||||
For deployment, filesystem permissions, and sensitive-artifact handling, see
|
||||
the [operations guide](../operations.md).
|
||||
A new invocation is a new request that may incur another provider call/cost.
|
||||
There is no checkpoint, archive, conversation, or resume protocol. Deployment and
|
||||
sensitive-data handling belong to [operations](../operations.md).
|
||||
|
||||
Reference in New Issue
Block a user