Files
scriptorium/docs/integrations/subprocess.md

68 lines
3.5 KiB
Markdown
Raw Normal View History

# 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.
2026-09-26 15:47:26 +00:00
## 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).