Integration: Scriptorium

Purpose

Define the Scriptorium adapter contract used by analyze and trim-bounds generation in trim.

Adapter Boundary

Interface:

scriptorium.Runner
methods:
- RunArtifact(ctx, RunArtifactRequest)
- RenderArtifact(ctx, RenderArtifactRequest)

Primary implementation:

internal/adapters/scriptorium/SubprocessRunner

Execution modes:

scriptorium run
scriptorium render

Request Contract

Both request types carry:

binary/config/prompt/profile IDs;
input map and vars map;
output path;
timeout;
generated config + stdout/stderr log paths;
optional API-key env var name;
optional working directory.

Result Contract

ArtifactResult returns:

output/log/generated-config paths;
exit code and duration;
command mode (run or render);
prompt/profile provenance;
ValidationFailed marker;
metadata map.

Validation and Failure Semantics

Request validation fails for:

missing binary, prompt id, or output path;
non-positive timeout;
empty input/var names;
empty input path values;
missing required credential env var when APIKeyEnv is set.

Run behavior:

subprocess errors propagate with context;
run exit code 2 is mapped to ValidationFailed=true;
successful subprocess still fails if output file is missing or empty.

Render behavior:

subprocess errors propagate;
output file must exist and be non-empty.

Deterministic Behavior

input and var maps are sorted into deterministic --input and --var CLI args.
stage wiring adds session_id=narratio-session-<session_id> to every Scriptorium request for sticky upstream routing, overriding any configured vars.session_id.
generated invocation YAML (scriptorium.generated.v1) is emitted when requested.
adapter is stateless and does not own artifact-selection policy.

Config Mapping

Config fields consumed through runner/stage wiring are under pipeline.scriptorium.* plus per-artifact settings under pipeline.scriptorium.artifacts.*.

Maintained examples with Scriptorium config:

examples/pipeline.full.annotated.yml
examples/pipeline.production.yml

2.1 KiB Raw Blame History