3.5 KiB
Subprocess Integration
Use the executable when a local process boundary is appropriate. The CLI contract owns exact command/flag/status syntax; the consumer overview 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 explains replacements for older command and file-output conventions.
Pass an explicit application configuration or deliberately arrange the child's configuration discovery. 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 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.