68 lines
3.5 KiB
Markdown
68 lines
3.5 KiB
Markdown
# Subprocess Integration
|
|
|
|
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.
|
|
|
|
## Artifact-First Execution And Inspection
|
|
|
|
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 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.
|
|
|
|
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, Reports, And Availability
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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).
|