64 lines
3.2 KiB
Markdown
64 lines
3.2 KiB
Markdown
# 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).
|
|
|
|
## Process Contract
|
|
|
|
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).
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Streams And Output Ownership
|
|
|
|
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.
|
|
|
|
When using `--out`, the caller owns the output path, its permissions, and
|
|
cleanup. Treat rendered prompts, generated artifacts, stdout, and stderr 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.
|
|
|
|
## 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.
|
|
|
|
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 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).
|