@intentius/chant 0.124.12 → 0.124.14

package/dist/components/verbs/run-agent.js

@@ -0,0 +1,577 @@
+/**
+ * `run-agent` — phase 1 design: capability schema + registry entry (#1941,
+ * epic #1564 "run-agent as a bounded, attested component capability").
+ *
+ * **Decided (2026-08-25, maintainer comment on #1564).** The agent turn
+ * executes on a fly [Sprite](https://sprites.dev), via chant's own sprite
+ * lifecycle activities (`lexicons/fly/src/op/activities/sprites.ts` —
+ * `spriteCreate`/`spriteCheckpoint`/`spriteExec`/`spriteRestore`/`spriteDestroy`,
+ * plus the filesystem activities in `sprite-fs.ts` —
+ * `spriteWriteFile`/`spriteReadFile`), **not** fountain's hosted `fountainRun`
+ * path (`lexicons/fountain/src/op/activities/fountain-run.ts`): `fountainRun`
+ * polls a fountain-managed `Conversation` to a terminal HTTP status and gives
+ * chant no checkpoint control, but the epic's compensation story needs chant
+ * to own the sprite directly. Compensation is checkpoint-before/restore-on-unwind
+ * — "the environment is the transaction," no hand-written inverse action — the
+ * same pattern `examples/sprites-agent-task/ops/guarded-task.op.ts` already
+ * demonstrates at the Op layer. The offline path is `sprites-fake`/
+ * `sprites-emulator` (spritzer), the same `SPRITES_BASE_URL` endpoint-override
+ * story `sprites.ts` documents.
+ *
+ * **Input tracks fountain's `Agent` surface as it stands today**
+ * (`lexicons/fountain/src/spec/fountain-openapi.snapshot.json`): `agent` is
+ * resolved the same way `fountainRun`'s `resolveAgentId` resolves a name/id
+ * against `/api/agents`; `task` is `PromptRequest`-shaped (`prompt` +
+ * optional `images`, `ImageInput`'s exact shape). The output's `turn` facts
+ * track `Turn`'s shape (`status`/`exit_code`/`started_at`/`ended_at`), even
+ * though the turn runs on a chant-owned sprite rather than a fountain-managed
+ * `Sandbox` — fountain supplies the *declarative* facts (which model, which
+ * runtime, which egress policy via `Environment`), chant drives the
+ * *imperative* execution. Revisit only if `BinaryBourbon/fountain#586` (the
+ * `Estate` proposal) lands a breaking shape.
+ *
+ * **Placement.** Registered the same way `docker-build` is (./build.ts) — a
+ * factory over an injectable executor seam (`SpriteActivities` below, the
+ * `run-agent` analogue of ./cloud-executor.ts's `CloudExecutor`) — so core
+ * carries the typed schema without a hard package dependency on
+ * `@intentius/chant-lexicon-fly` (core stays cloud/vendor-agnostic in its
+ * dependency graph, see docs/components/cloud-boundary; the same reasoning
+ * that keeps the AWS leaves in `@intentius/chant-lexicon-aws` rather than
+ * here). Unlike the AWS leaves, there is today no fly-lexicon capability
+ * plugin for this verb to live in instead, and `run-agent` is a foundational,
+ * pipeline-level primitive in the same vein as `docker-build` or
+ * `wrangler-deploy` (./wrangler.ts) rather than a swappable per-cloud leaf —
+ * the same tradeoff `wrangler.ts`'s module doc weighs for the Cloudflare
+ * Workers verbs. Revisit if a broader agent-execution lexicon ever owns this
+ * seam instead.
+ *
+ * **Scope across phases.** Phase 1 (#1941) shipped the typed contract only —
+ * `run`/`rollback` were stubs throwing `CapabilityNotImplementedError`, per
+ * ../capability.ts's own module doc ("Verb implementations live under
+ * `./verbs/*` as typed stubs — no cloud calls, no side effects. Cloud
+ * implementations are a later phase"). `rollbackPolicy: "native"` was declared
+ * from phase 1 (so COMP003, ../lint/rules/comp/comp003-mutating-no-rollback.ts,
+ * never requires a `noRollback` opt-out for this verb once it composes into a
+ * component) even before the paired `rollback` body was real — the *policy*
+ * was the phase 1 design commitment, the *implementation* is phase 2 (#1942,
+ * below). This capability is deliberately not yet registered in any
+ * `CapabilityPlugin`'s `STARTER_VERB_FAMILIES`-equivalent set — the fly
+ * lexicon's own plugin (`lexicons/fly/src/components/capability-plugin.ts`)
+ * registers it under its own `FLY_VERB_FAMILIES`, but that is a separate,
+ * later decision from "does core's sequencing logic actually work," which
+ * this module answers. #1943 ("Provenance + attestation") owns the
+ * `provenance.sourceRef` transcript-hash basis and verify-gate interop; #1944
+ * owns the conformance/contract test suite (saga-unwind restore, COMP003
+ * refusal) beyond this module's own unit tests.
+ *
+ * **#1942 (phase 2, this module's `run`/`rollback` body) resolved the
+ * following:**
+ *  - **The exec-throw finding** (pre-merge review of #1946, recorded on
+ *    #1942): the real `spriteExec` (`lexicons/fly/src/op/activities/sprites.ts`)
+ *    throws on any non-zero exit, so a *thin* `SpriteActivities.exec` adapter
+ *    can only ever produce `turn.status: "failed"` without throwing if it
+ *    reclassifies that throw itself. That reclassification is the fly
+ *    lexicon adapter's job (`lexicons/fly/src/components/run-agent.ts`,
+ *    option (a) from the review comment) — `SpriteActivities.exec`'s
+ *    contract, as this module consumes it, is: **resolve** with `exitCode`
+ *    for any ordinary command outcome (zero or non-zero), **reject** only for
+ *    a genuine transport/infra failure. `run()` below trusts that contract
+ *    completely: it never wraps `sprites.exec` in a try/catch, so a rejection
+ *    from the injected `sprites` always propagates as a genuine `run()`
+ *    failure (triggering saga rollback in ../driver.ts), while an ordinary
+ *    non-zero exit becomes `turn.status: "failed"` on a normal return —
+ *    exactly the non-throwing first-class result the type already declared.
+ *  - **Rollback identity (#1944 closes the durable-path gap left open here).**
+ *    `rollback(ctx, input, output)` receives the identical `input` object
+ *    `run(ctx, input)` was called with, plus (since #1944) the exact `output`
+ *    `run()` returned — `../capability.ts`'s `Capability.rollback` grew an
+ *    optional third parameter for precisely this, and ../driver.ts's saga
+ *    unwind (and any hosting runtime that splits `run`/`rollback` across
+ *    process boundaries) always threads it through. `run()` records the
+ *    sprite id and exact pre-run checkpoint id two ways: in a private
+ *    `WeakMap` keyed by the exact `input` object (works only when `rollback`
+ *    is called with that same object — true in-process, e.g. this module's
+ *    own tests calling `rollback()` directly after `run()`), and — the
+ *    durable-safe channel — as `output.spriteId`/`output.checkpointId`,
+ *    already part of `RunAgentOutput` (#1943). `rollback()` prefers `output`'s
+ *    fields when present, falling back to the `WeakMap` only when a caller
+ *    never threads `output` through (backward-compatible for any capability
+ *    caller not yet passing it). **The checkpoint id, not the comment, is
+ *    what `rollback()` restores by** when either source has one:
+ *    `sprites.restore({ id, checkpoint: checkpointId })`, which
+ *    `spriteRestore`'s explicit-id resolution wins over comment on
+ *    (`lexicons/fly/src/op/activities/sprites.ts`). Restoring by comment alone
+ *    is unsafe on a reused sprite — two `run()` calls sharing the default
+ *    `"pre-run"` comment would make a comment-based restore always resolve to
+ *    the *newest* matching checkpoint, so rolling back the first run would
+ *    restore the second run's checkpoint (which already contains the first
+ *    run's mutation) instead of undoing it. Comment-based restore
+ *    (`workspace.checkpointComment`, default `"pre-run"`) is therefore only a
+ *    **fallback**, used when no checkpoint id is available from either source
+ *    (the `workspace.spriteName`-only path below). When there is no sprite id
+ *    to restore at all (no `output`, no `WeakMap` record, no
+ *    `workspace.spriteName`), `rollback()` degrades with an explicit,
+ *    commented no-op return — the same pattern
+ *    `../../lexicons/aws/src/components/host-delivery.ts`'s `code-deploy`
+ *    rollback uses (`if (!deploymentId) return;`) — rather than throwing.
+ *    **Before #1944**, a hosted path running `run` and `rollback` as separate
+ *    units of work — each rebuilding `input` fresh via `resolveStepInput` —
+ *    never gave the `WeakMap` a hit, so a fresh sprite's rollback there
+ *    silently degraded to that no-op; passing `output` through (this revision)
+ *    closes that gap directly, without redesigning the component-op wire
+ *    format — see #1944's PR description for why this was chosen over the
+ *    "make the degrade loud" alternative.
+ *  - **Destroy vs. leave-alive.** `run()` destroys a freshly created (not
+ *    `workspace.spriteName`-reused) sprite only when `turn.status ===
+ *    "completed"`. An ordinary failed turn leaves the sprite alive — it
+ *    returned normally, so no saga rollback runs, but the failure is exactly
+ *    when a caller (or this module's own tests) most wants to inspect the
+ *    sprite or explicitly call `rollback()` to restore it, per this issue's
+ *    acceptance criteria.
+ *
+ * **Still open, left for later phases:**
+ *  - Runtime invocation inside the sprite — `buildRuntimeCommand` below picks
+ *    a real one-shot CLI invocation for each known `Agent.runtime` value,
+ *    reading the staged prompt file; whether the sprite image already carries
+ *    that CLI (vs. `run()` needing a setup step) is unresolved. `RunAgentInput`
+ *    (frozen by #1941) has no separate `runtime` field, so `input.agent`
+ *    doubles as the runtime selector for phase 2 — an unrecognized value is
+ *    passed through verbatim as a literal command (a documented escape hatch
+ *    for a custom binary already present in the image, and how this module's
+ *    own tests exercise a scripted failure against the offline fake). Real
+ *    `agent` name/id -> `Agent.runtime` resolution against fountain's
+ *    `/api/agents` (`resolveAgentId`, `lexicons/fountain/.../fountain-run.ts`)
+ *    is out of this issue's scope (and would need a network call the offline
+ *    path forbids).
+ *  - Output artifact encoding — `run()` reads one conventional path
+ *    (`/work/output`) as the sole `artifacts.files` entry when present;
+ *    individual `spriteReadFile` calls per changed path vs. one tarred
+ *    snapshot folded into a `BuildArchiveManifest` entry (./build-archive.ts)
+ *    remains an open question, as does `artifacts.diff`, which `run()` never
+ *    populates (the real Sprites API has no built-in diff endpoint).
+ *
+ * **#1943 (this revision) resolved the transcript-hash basis and
+ * sign/verify-gate interop, closing #1941's open "transcript hash basis"
+ * question:**
+ *  - **Hash basis.** `provenance.sourceRef`'s digest component is
+ *    `sha256Digest(JSON.stringify(basis))` over a fixed-key-order object —
+ *    `{ agent, promptDigest, images, status, exitCode, stdoutDigest,
+ *    stderrDigest, artifacts, diffDigest }` — built fresh by
+ *    `computeTranscriptDigest` below every call, never re-ordered from a
+ *    caller-supplied object, so key order (and therefore the digest) never
+ *    drifts by construction. Every free-text field (`prompt`, `stdout`,
+ *    `stderr`, `diff`, each image's `data`) is folded in as its own
+ *    `sha256Digest`, not embedded verbatim — this keeps a (possibly large,
+ *    possibly secret-bearing) prompt or transcript out of the digest input's
+ *    own byte stream while the digest remains exactly as sensitive to those
+ *    bytes as embedding them would be, and it is *why* this module never
+ *    needs to retain raw stdout/stderr past computing their digest inline
+ *    (closing #1941's "is the raw transcript retained anywhere beyond the
+ *    attested digest" sub-question: no, not even internally). `startedAt`/
+ *    `endedAt` are deliberately excluded — including wall-clock time would
+ *    make "the same turn" (same prompt, same exec outcome, same artifacts)
+ *    hash differently on every real run, defeating the determinism property
+ *    (`same turn -> same sourceRef`) a verifier actually needs: identity is
+ *    about *what happened*, not *when*. `artifacts.files` is sorted by
+ *    `path` before hashing so collection order (never semantically
+ *    meaningful — there is exactly one conventional artifact today, see
+ *    `OUTPUT_PATH`) can't perturb the digest.
+ *  - **`sourceRef` folding.** `RunAgentInput.sourceRef`'s own doc comment
+ *    promises it is "folded into the output's `provenance.sourceRef`
+ *    alongside the transcript hash." Concretely: `sourceRef =
+ *    input.sourceRef ? \`${input.sourceRef}@${transcriptDigest}\` :
+ *    transcriptDigest` — an `"<sha>@sha256:<hex>"` shape when a source ref is
+ *    known, reading like the `repo@sha256:...` convention already used
+ *    throughout this codebase (./sign.ts, ./publish.ts's `uri`), or the bare
+ *    `sha256:<hex>` transcript digest alone when it is not. `@` (not `:`,
+ *    which `DockerBuildInput.sourceRef`'s own `"<sha>:<path>"` convention
+ *    already uses for a different purpose) keeps the split unambiguous.
+ *    `extractTranscriptDigest` below recovers the trailing
+ *    `sha256:<hex>` deterministically regardless of what `input.sourceRef`
+ *    contains, by anchoring on the fixed `sha256:[0-9a-f]{64}` pattern at the
+ *    very end of the string.
+ *  - **Attestation interop, decided.** `RunAgentOutput` gained one field,
+ *    `attestationRef` — a `"<component>/run-agent@sha256:<hex>"` string
+ *    already shaped like the digest-qualified `repo@sha256:...` reference
+ *    `./sign.ts`'s `assertDigestRef`/`./verify.ts` already require, built
+ *    from `ctx.component` and the transcript digest, so a `sign`/
+ *    `attest-provenance`/`verify` step composed after `run-agent` wires
+ *    `imageRef: "@RunAgent.attestationRef"` and needs **zero code changes**
+ *    to any of those three verbs — resolving design point 4 of #1943 exactly
+ *    as anticipated. The honest caveat, stated plainly rather than left
+ *    implicit: `attestationRef` is *shaped* like an OCI digest reference, but
+ *    is not by itself a real, registry-resolvable one — `run-agent`'s turn
+ *    output is never pushed anywhere by this module. A deployment that wants
+ *    a genuine `cosign sign`/`cosign verify` round trip against real
+ *    Rekor/Fulcio needs a registry-backed publish step ahead of `sign`
+ *    (mirroring `publish-image`'s `uri`, ./publish.ts) — out of this issue's
+ *    scope, and not needed for the offline contract this issue asks for
+ *    (injected `ProcessRunner`, no real `cosign`/registry ever touched).
+ *    `toRunAgentArchiveEntry` below folds the same digest into a
+ *    `BuildArchiveEntry` (`kind: "asset"`, ./build-archive.ts) per design
+ *    point 2, for a caller building a full archive manifest.
+ *  - **Predicate-type decision, made (not left open).** Reuses the existing
+ *    `predicateType: "https://slsa.dev/provenance/v1"` unchanged — does
+ *    *not* mint a `run-agent`-specific predicate type. `buildDefinition
+ *    .buildType` is the field SLSA v1 actually designates for "what kind of
+ *    recipe produced this" (`RUN_AGENT_BUILD_TYPE` below,
+ *    `"https://chant.dev/agent-turn/v1"`, the same role
+ *    `./sign.ts`'s `DEFAULT_BUILD_TYPE` plays for `docker-build`), so a
+ *    second, parallel `predicateType` taxonomy would duplicate what
+ *    `buildType` already discriminates. This is also what makes the "zero
+ *    code changes to `verify.ts`" claim above literally true:
+ *    `buildVerifyAttestationArgs` hardcodes `--type slsaprovenance1` — a
+ *    minted `predicateType` would have broken that interop outright, forcing
+ *    a `verify.ts` change this issue's design point 4 explicitly hoped to
+ *    avoid.
+ *  - **Fountain-supplied facts, honestly scoped.** `buildRunAgentProvenanceStatement`
+ *    below folds `input.agent` into `externalParameters` (the one *declared*
+ *    fact `RunAgentInput` actually carries today) and `spriteId`/
+ *    `checkpointId`/`turn.status`/`turn.exitCode` into `internalParameters`
+ *    (what actually happened). `model`/`runtime`/`Environment.networking_type`
+ *    /`allowed_hosts` are not included — populating them honestly needs
+ *    fountain `Agent`/`Environment` resolution against `/api/agents`, which
+ *    this module's own doc comment already marks out of scope ("Real `agent`
+ *    name/id -> `Agent.runtime` resolution ... is out of this issue's
+ *    scope"). Adding those keys later is additive (merged into
+ *    `externalParameters`, never replacing it), not a shape break.
+ */
+import { contentDigest } from "../../content-digest.js";
+import { buildProvenanceStatement } from "./sign.js";
+/**
+ * Thrown by `defaultSpriteActivities()`'s methods when a caller never injects
+ * a real (or fake) `SpriteActivities` — the default remains this
+ * not-wired-yet placeholder even after #1942 wires `run()`/`rollback()`'s
+ * sequencing logic, because *some* concrete backend still has to be supplied
+ * for that logic to have anything to call. `lexicons/fly/src/components/
+ * run-agent.ts`'s adapter (the real backend, over this lexicon's own sprite
+ * lifecycle activities) or the offline `sprites-fake`/`sprites-emulator` path
+ * are what a caller injects instead. A caller that supplies its own
+ * `SpriteActivities` never hits this class.
+ */
+export class SpriteActivitiesNotWiredError extends Error {
+    constructor(method) {
+        super(`SpriteActivities.${method}: not wired to a real sprite backend yet — sprite lifecycle wiring is #1942 ` +
+            `(epic #1564 phase 2). Inject a real or fake ("sprites-fake"/"sprites-emulator") implementation to ` +
+            `exercise "run-agent" end to end.`);
+        this.method = method;
+        this.name = "SpriteActivitiesNotWiredError";
+    }
+}
+/** Phase 1's placeholder default: every method throws `SpriteActivitiesNotWiredError`. See that class's doc comment. */
+export function defaultSpriteActivities() {
+    const notWired = (method) => async () => {
+        throw new SpriteActivitiesNotWiredError(method);
+    };
+    return {
+        create: notWired("create"),
+        checkpoint: notWired("checkpoint"),
+        exec: notWired("exec"),
+        restore: notWired("restore"),
+        destroy: notWired("destroy"),
+        writeFile: notWired("writeFile"),
+        readFile: notWired("readFile"),
+    };
+}
+// ── capability ───────────────────────────────────────────────────────────
+/**
+ * Build the `run-agent` capability. `sprites` is the injectable
+ * `SpriteActivities` seam (default: `defaultSpriteActivities()`, the
+ * not-wired-yet placeholder — see that function's doc comment) so unit tests
+ * never touch a real/emulated sprite, mirroring `createDockerBuildCapability`'s
+ * `executor: CloudExecutor` parameter (./build.ts). The fly lexicon's
+ * `flyRunAgentCapability` (`lexicons/fly/src/components/run-agent.ts`) is
+ * this same factory called with its real `SpriteActivities` adapter.
+ *
+ * `run()`: `sprites.create` (skipped when reusing `workspace.spriteName`) ->
+ * `sprites.checkpoint` (`comment: workspace.checkpointComment ?? "pre-run"`)
+ * -> `sprites.writeFile` to stage the prompt -> `sprites.exec` the runtime
+ * command (`buildRuntimeCommand`) -> `sprites.readFile` to collect the sole
+ * artifact -> `sprites.destroy`, only for a freshly created sprite whose turn
+ * completed. See this module's doc comment for the exec-throw resolution,
+ * the destroy-vs-leave-alive rule, and the rollback-identity design.
+ *
+ * `rollback()`: `sprites.restore({ id: spriteId, checkpoint: checkpointId })`
+ * — the sole compensation, restoring to the exact pre-run checkpoint `run()`
+ * recorded (see this module's doc comment, "Rollback identity"). Prefers the
+ * `output` parameter's `spriteId`/`checkpointId` (the durable-safe channel,
+ * #1944) over the in-process `WeakMap`, falls back to
+ * `sprites.restore({ id: spriteId, comment })` only when neither source has a
+ * checkpoint id, and degrades to an explicit no-op when there is no sprite id
+ * to restore at all. No hand-written inverse action otherwise; "the
+ * environment is the transaction."
+ *
+ * `rollbackPolicy: "native"` is set explicitly (not left to
+ * ../capability.ts's `rollback`-method inference) so the design commitment
+ * reads directly off this capability's declaration: a mutating `run-agent`
+ * step never needs a `noRollback` opt-out for COMP003
+ * (../lint/rules/comp/comp003-mutating-no-rollback.ts).
+ */
+export function createRunAgentCapability(sprites = defaultSpriteActivities()) {
+    // Keyed by the exact `input` object `run()` was called with — a fallback
+    // for a caller that never threads `output` through to `rollback()` (see
+    // this module's doc comment, "Rollback identity"). The durable-safe path
+    // is `output.spriteId`/`output.checkpointId`, already part of
+    // `RunAgentOutput` (#1943) and threaded by every current caller (#1944).
+    const stateByInput = new WeakMap();
+    return {
+        kind: "run-agent",
+        rollbackPolicy: "native",
+        async run(ctx, input) {
+            const reused = Boolean(input.workspace.spriteName);
+            const spriteId = input.workspace.spriteName ?? generateSpriteName(ctx);
+            if (!reused) {
+                await sprites.create({ name: spriteId, image: input.workspace.image });
+            }
+            const checkpointComment = input.workspace.checkpointComment ?? "pre-run";
+            const { checkpointId } = await sprites.checkpoint({ id: spriteId, comment: checkpointComment });
+            // Recorded as early as possible: even if a later step throws (a genuine
+            // infra failure, triggering saga rollback), `rollback()` still finds
+            // the sprite id and exact checkpoint it needs to restore.
+            stateByInput.set(input, { spriteId, checkpointId });
+            await sprites.writeFile({ id: spriteId, path: PROMPT_PATH, content: input.task.prompt, mkdir: true });
+            const startedAt = new Date().toISOString();
+            // No try/catch here by design (see this module's doc comment, "The
+            // exec-throw finding"): `sprites.exec` resolves with `exitCode` for any
+            // ordinary command outcome and rejects only for a genuine infra
+            // failure, which should propagate and trigger saga rollback.
+            const execResult = await sprites.exec({ id: spriteId, cmd: buildRuntimeCommand(input.agent) });
+            const turn = {
+                status: execResult.exitCode === 0 ? "completed" : "failed",
+                exitCode: execResult.exitCode,
+                startedAt,
+                endedAt: new Date().toISOString(),
+            };
+            const artifacts = await collectArtifacts(sprites, spriteId);
+            // Destroy only on a normal-return success. A failed turn (status
+            // "failed") leaves the sprite alive — no saga rollback runs for it
+            // (run() returned, it didn't throw), so this is the caller's own
+            // window to inspect the sprite or explicitly call rollback().
+            if (!reused && turn.status === "completed") {
+                await sprites.destroy({ id: spriteId });
+            }
+            // #1943: the transcript digest — see this module's doc comment ("Hash
+            // basis") for the exact fields/order this is computed over.
+            // execResult.stdout/stderr never outlive this call: they are folded
+            // into the digest right here and discarded, never stored on `turn` or
+            // anywhere else in `RunAgentOutput`.
+            const transcriptDigest = computeTranscriptDigest({
+                agent: input.agent,
+                prompt: input.task.prompt,
+                images: input.task.images,
+                turn,
+                stdout: execResult.stdout,
+                stderr: execResult.stderr,
+                artifacts,
+            });
+            const sourceRef = input.sourceRef ? `${input.sourceRef}@${transcriptDigest}` : transcriptDigest;
+            const provenance = {
+                sourceRef,
+                artifactDigest: artifacts.files[0]?.digest ?? EMPTY_DIGEST,
+            };
+            const attestationRef = `${ctx.component}/run-agent@${transcriptDigest}`;
+            return { spriteId, checkpointId, turn, artifacts, provenance, attestationRef };
+        },
+        async rollback(_ctx, input, output) {
+            // The durable-safe channel first (#1944): `output` is the exact value
+            // this step's own `run()` returned, threaded through by every current
+            // caller (../driver.ts locally, and a hosting runtime across whatever
+            // process boundary it puts between the two) — it
+            // survives even when `rollback()` is called with a freshly-rebuilt
+            // `input` object the in-process WeakMap below has never seen. Falls
+            // back to the WeakMap for a caller that predates/never threads
+            // `output` (see this module's doc comment, "Rollback identity").
+            const state = stateByInput.get(input);
+            const spriteId = output?.spriteId ?? state?.spriteId ?? input.workspace.spriteName;
+            if (!spriteId) {
+                // No identity from any source (output, in-process record, or
+                // "workspace.spriteName"): there is nothing to identify which sprite
+                // to restore. Degrade explicitly rather than throwing into a
+                // swallowed catch, the same pattern
+                // ../../lexicons/aws/src/components/host-delivery.ts's code-deploy
+                // rollback uses (`if (!deploymentId) return;`).
+                return;
+            }
+            // Restore the exact pre-run checkpoint when either source recorded
+            // one — wins over comment (see "Rollback identity"), and is the only
+            // safe choice on a reused sprite where two runs can share the same
+            // default "pre-run" comment.
+            const checkpointId = output?.checkpointId ?? state?.checkpointId;
+            if (checkpointId) {
+                await sprites.restore({ id: spriteId, checkpoint: checkpointId });
+                return;
+            }
+            // Fallback: no checkpoint id from either source (e.g.
+            // workspace.spriteName-only, no output, no in-process run() record) —
+            // resolve by comment, same as before.
+            const comment = input.workspace.checkpointComment ?? "pre-run";
+            await sprites.restore({ id: spriteId, comment });
+        },
+    };
+}
+// ── run() helpers ────────────────────────────────────────────────────────
+/** The conventional path `run()` writes the staged prompt to and reads the sole artifact from — the same `/work/*` convention `examples/sprites-agent-task/ops/agent-task.op.ts`'s Stage/Collect phases use. */
+const PROMPT_PATH = "/work/prompt";
+const OUTPUT_PATH = "/work/output";
+/** `sha256:<hex>` over a string: ../../content-digest.ts's `contentDigest`, the same digest ./build-archive.ts uses. */
+const sha256Digest = contentDigest;
+const EMPTY_DIGEST = sha256Digest("");
+/**
+ * Compute the transcript digest that becomes (the digest component of)
+ * `provenance.sourceRef` and `attestationRef` — see this module's doc
+ * comment, "Hash basis," for the precise field list/order and the rationale
+ * for hashing rather than embedding each free-text field. Exported so a
+ * caller (or a test) can independently recompute/verify the same digest from
+ * the same run() inputs/outputs, without reaching into this module's private
+ * `run()` closure.
+ */
+export function computeTranscriptDigest(params) {
+    const basis = {
+        agent: params.agent,
+        promptDigest: sha256Digest(params.prompt),
+        images: (params.images ?? []).map((img) => ({ mediaType: img.media_type, digest: sha256Digest(img.data) })),
+        status: params.turn.status,
+        exitCode: params.turn.exitCode,
+        stdoutDigest: sha256Digest(params.stdout),
+        stderrDigest: sha256Digest(params.stderr),
+        artifacts: [...params.artifacts.files]
+            // Code-point ordering, not localeCompare: the digest must be identical
+            // across machines regardless of ICU/locale configuration.
+            .sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))
+            .map((f) => ({ path: f.path, digest: f.digest })),
+        diffDigest: sha256Digest(params.artifacts.diff ?? ""),
+    };
+    return sha256Digest(JSON.stringify(basis));
+}
+/** The trailing `sha256:<hex>` transcript digest a `provenance.sourceRef`/`attestationRef` ends in — see this module's doc comment, "sourceRef folding." */
+const TRANSCRIPT_DIGEST_PATTERN = /sha256:[0-9a-f]{64}$/i;
+/**
+ * Recover the bare transcript digest (`sha256:<hex>`) from a
+ * `provenance.sourceRef` or `attestationRef` string, regardless of what (if
+ * anything) precedes it — see this module's doc comment, "sourceRef
+ * folding," for why anchoring on the fixed `sha256:[0-9a-f]{64}` suffix
+ * pattern is unambiguous even when `input.sourceRef` itself contains `@`/`:`.
+ */
+export function extractTranscriptDigest(sourceRef) {
+    const match = TRANSCRIPT_DIGEST_PATTERN.exec(sourceRef);
+    if (!match) {
+        throw new Error(`extractTranscriptDigest: "${sourceRef}" does not end in a "sha256:<hex>" transcript digest`);
+    }
+    return match[0];
+}
+/**
+ * `run-agent`'s SLSA `buildDefinition.buildType` — the recipe-kind URI this
+ * module's doc comment ("Predicate-type decision, made") settles on in place
+ * of minting a new `predicateType`. Mirrors ./sign.ts's own
+ * `DEFAULT_BUILD_TYPE` for `docker-build`.
+ */
+export const RUN_AGENT_BUILD_TYPE = "https://chant.dev/agent-turn/v1";
+/**
+ * Fold a `RunAgentOutput` into a `BuildArchiveEntry` (#1943 design point 2,
+ * ./build-archive.ts) — `kind: "asset"`, content-addressed by the same
+ * transcript digest `attestationRef` carries. Returns a bare entry (no
+ * `reproducibility` assigned); pass it through `addArchiveEntry` for the
+ * kind-appropriate `"best-effort"` default (./reproducibility.ts), the same
+ * as any other `asset` entry.
+ */
+export function toRunAgentArchiveEntry(component, output) {
+    return {
+        kind: "asset",
+        path: `run-agent/${component}/${output.spriteId}-turn.json`,
+        digest: extractTranscriptDigest(output.provenance.sourceRef),
+        mediaType: "application/json",
+        provenance: output.provenance,
+    };
+}
+/**
+ * Build the in-toto SLSA provenance statement for a completed turn, reusing
+ * ./sign.ts's `buildProvenanceStatement` unmodified in behavior for every
+ * existing (image) caller — `predicateType` stays
+ * `"https://slsa.dev/provenance/v1"`, only `buildType` and the
+ * `external`/`internalParameters` merge fields (#1943's minimal, documented
+ * extension to `BuildProvenanceStatementInput`) differ. See this module's
+ * doc comment, "Fountain-supplied facts, honestly scoped," for exactly what
+ * is (and is not yet) folded in. The returned statement's `subject` is
+ * `output.attestationRef` — sign+attach it the same way `attest-provenance`
+ * already does for any other digest-qualified reference.
+ */
+export function buildRunAgentProvenanceStatement(input, output, builderId, opts) {
+    return buildProvenanceStatement({
+        imageRef: output.attestationRef,
+        provenance: output.provenance,
+        builderId,
+        buildType: RUN_AGENT_BUILD_TYPE,
+        externalParameters: { agent: input.agent },
+        internalParameters: {
+            spriteId: output.spriteId,
+            checkpointId: output.checkpointId,
+            turnStatus: output.turn.status,
+            turnExitCode: output.turn.exitCode,
+        },
+        finishedOn: opts?.finishedOn ?? output.turn.endedAt ?? undefined,
+        invocationId: opts?.invocationId,
+    });
+}
+/**
+ * Map `RunAgentInput.agent` to the one-shot, non-interactive command that
+ * reads the staged prompt (`PROMPT_PATH`) and runs it inside the sprite. Each
+ * known `RunAgentRuntime` gets its real CLI invocation; any other value is
+ * passed through verbatim as a literal command — a real-world escape hatch
+ * for a custom binary already present in the sprite image, and how this
+ * module's own tests drive a scripted failure/success against the offline
+ * fake without needing a real CLI. See this module's doc comment ("Still
+ * open, left for later phases") for why no fountain resolution happens here.
+ */
+export function buildRuntimeCommand(agent) {
+    switch (agent) {
+        case "claude":
+            return `claude -p "$(cat ${PROMPT_PATH})" --output-format json`;
+        case "codex":
+            return `codex exec "$(cat ${PROMPT_PATH})"`;
+        case "gemini":
+            return `gemini -p "$(cat ${PROMPT_PATH})"`;
+        case "opencode":
+            return `opencode run "$(cat ${PROMPT_PATH})"`;
+        default:
+            return agent;
+    }
+}
+/** Deterministic-enough default sprite name when `workspace.spriteName` is omitted — not required to be reproducible across calls (see this module's doc comment on rollback identity: the `WeakMap` is what makes rollback work, not the name shape). */
+function generateSpriteName(ctx) {
+    const suffix = Math.random().toString(36).slice(2, 10);
+    return `run-agent-${ctx.component}-${suffix}`.replace(/[^a-zA-Z0-9._-]/g, "-");
+}
+/**
+ * Match the "not found" error shape `lexicons/fly/src/op/activities/
+ * sprite-fs.ts`'s `spriteReadFile` throws for a 404 specifically (`sprite
+ * <id> read <path>: not found`) — distinct from that same module's >=300
+ * `"... failed (<status>): ..."` shape, which is a genuine infra failure. The
+ * match is narrow on purpose, mirroring how `lexicons/fly/src/components/
+ * run-agent.ts`'s `parseSpriteExecFailure` only reclassifies the one thrown
+ * shape it recognizes and lets everything else through.
+ */
+function isArtifactNotFoundError(err) {
+    return err instanceof Error && /^sprite .+ read .+: not found$/.test(err.message);
+}
+/**
+ * Read `OUTPUT_PATH` as the turn's sole artifact, when present. Only a
+ * "not found" read (no artifact was ever written — e.g. a failed turn that
+ * never got that far) is treated as "no artifact"; any other error (a
+ * genuine transport/infra failure, or a real "failed (<status>)" from the
+ * sprite filesystem API) is rethrown so it propagates as a `run()` rejection
+ * and triggers saga rollback, instead of being silently swallowed into an
+ * empty `artifacts.files`.
+ */
+async function collectArtifacts(sprites, spriteId) {
+    try {
+        const { content } = await sprites.readFile({ id: spriteId, path: OUTPUT_PATH });
+        return { files: [{ path: OUTPUT_PATH, digest: sha256Digest(content) }] };
+    }
+    catch (err) {
+        if (isArtifactNotFoundError(err))
+            return { files: [] };
+        throw err;
+    }
+}
+/** Default `run-agent` capability, backed by the not-wired-yet placeholder `SpriteActivities`. */
+export const runAgentCapability = createRunAgentCapability();