@intentius/chant-lexicon-fly 0.124.31 → 0.124.32

package/dist/components/fly-release.js

@@ -0,0 +1,335 @@
+/**
+ * `fly-release` and `fly-rollback`: a component deploying to Fly with this
+ * lexicon alone (#2736, ws-056), in place of chud's `Chud::FlySite`.
+ *
+ * A component declares its App and Machine as this lexicon's resources, builds
+ * them (`chant build --lexicon fly -o <plan>`), and deploys with one step:
+ *
+ * ```ts
+ * { kind: "fly-release", plan: "dist/fly.json", digest: "@app.publish.digest",
+ *   image: "@app.publish.uri", migrations: [{ name: "001_init.sql", command: "node migrate.js 001_init.sql" }] }
+ * ```
+ *
+ * `fly-release` runs the site steps in order, as the Machines activities
+ * (../op/activities/machine-release.ts):
+ *
+ * 1. upload and start: apply the plan with the Machine serving the release,
+ *    its digest and commit in the Machine's metadata, and the commit in its
+ *    `APP_REVISION` env var (#2834, as chud's fly-site.mjs set it), so the
+ *    app's own `/health` can report it. A caller's `env.APP_REVISION`
+ *    overrides it. `fly-rollback` restores it for free: it puts back the
+ *    whole recorded config, env included. A Machine the build stamped with
+ *    telemetry attribution (#3060) also gets the release's `service.version`
+ *    and `vcs.ref.head.revision` in its `OTEL_RESOURCE_ATTRIBUTES` (#3061,
+ *    ws-081; see {@link releaseResourceAttributes});
+ * 2. migrate: each migration runs inside the Machine once per environment,
+ *    witnessed by a receipt in chant's lifecycle receipt store
+ *    (`@intentius/chant/op/lifecycle-receipt-store`), then the Machine restarts
+ *    on the migrated data;
+ * 3. verify: the Machine is started with this release, and its health
+ *    endpoint answers when a URL is given;
+ * 4. on a failure after the Machine changed, restore: the config it replaced
+ *    goes back (or, on a first release, the Machine is stopped), and the step
+ *    fails.
+ *
+ * Its output carries `uri` and `digest`, so `chant run --components` records
+ * the release in the ledger, and the Machine's metadata carries the same
+ * digest, which `chant components status --live` compares with it.
+ *
+ * Each release's Machine config is kept on the lifecycle branch
+ * (../release-store.ts). `fly-rollback` puts back the config of the release
+ * the serving one replaced (or the digest it is given), which is also the
+ * saga compensation `fly-release` declares. Given the source tree of that
+ * release (#2800), it checks the archive against its digest before any flaps
+ * call and refuses a recorded config that does not carry exactly that tree.
+ */
+import { createHash } from "node:crypto";
+import { findMachine, flyMachineExec, flyMachineRelease, flyMachineRestart, flyMachineRestore, flyMachineStop, flyMachineVerify, readMachineRelease, releaseTarget, } from "../op/activities/machine-release.js";
+import { defaultFlyHttp, parsePlan, resolveEndpoint } from "../op/activities/fly-apply.js";
+import { readFileSync } from "node:fs";
+import { releaseAttributesSuffix } from "@intentius/chant/telemetry-attribution";
+/** Most bytes of files, base64, a release puts in a Machine's config (as chud's fly-site.mjs capped them). */
+export const SOURCE_FILES_LIMIT = 1024 * 1024;
+/** Where a source tree goes on the Machine, without a trailing slash. */
+const intoOf = (source) => (source.into ?? "/srv/app").replace(/\/+$/, "");
+/** A source tree's files as a Machine config carries them, once its archive is the approved one. */
+async function sourceTreeFiles(source, kind) {
+    const { readSourceArchive } = await import("@intentius/chant/op/source-archive");
+    const into = intoOf(source);
+    const files = readSourceArchive(source).map((f) => ({
+        guest_path: `${into}/${f.path}`,
+        raw_value: f.data.toString("base64"),
+        ...(f.executable ? { mode: 0o755 } : {}),
+    }));
+    if (files.length === 0)
+        throw new Error(`${kind}: ${source.archive} holds no files`);
+    return files;
+}
+/** A source tree as Machine files and the start command, once its archive is the approved one. */
+export async function sourceMachineFiles(source) {
+    const into = intoOf(source);
+    const files = await sourceTreeFiles(source, "fly-release");
+    const bytes = files.reduce((n, f) => n + f.raw_value.length, 0);
+    if (bytes > SOURCE_FILES_LIMIT) {
+        throw new Error(`fly-release: the source tree is ${Math.round(bytes / 1024)} KiB encoded; a Machine's config carries at most ${SOURCE_FILES_LIMIT / 1024} KiB of files. Ship a larger app as an image (\`image\`).`);
+    }
+    const start = typeof source.start === "string" ? source.start : source.start.map(shellQuote).join(" ");
+    return { files, cmd: ["sh", "-c", `cd ${shellQuote(into)} && exec ${start}`] };
+}
+const shellQuote = (v) => (/^[A-Za-z0-9_./:=@%+-]+$/.test(v) ? v : `'${v.replaceAll("'", "'\\''")}'`);
+async function defaultConfigStore(ctx) {
+    const { lifecycleMachineConfigStore } = await import("../release-store.js");
+    return lifecycleMachineConfigStore(ctx.env);
+}
+async function defaultReceiptStore(ctx) {
+    const { lifecycleReceiptStore } = await import("@intentius/chant/op/lifecycle-receipt-store");
+    return lifecycleReceiptStore({ environment: ctx.env });
+}
+async function defaultHeadCommit() {
+    const { getHeadCommit } = await import("@intentius/chant/lifecycle/git");
+    return getHeadCommit();
+}
+const sha256 = (s) => `sha256:${createHash("sha256").update(s).digest("hex")}`;
+/** The receipt a migration fires under on an app. */
+export function migrationReceipt(app, migration) {
+    const command = typeof migration.command === "string" ? migration.command : JSON.stringify(migration.command);
+    return {
+        ref: { name: `fly-migration:${app}/${migration.name}`, effect: "fly-migrate", flavor: "hash", inputs: { app, migration: migration.name } },
+        expectation: migration.sha ?? sha256(command),
+    };
+}
+/**
+ * A stamped Machine's `OTEL_RESOURCE_ATTRIBUTES` with the release's attributes
+ * (#3061, ws-081), or undefined when the build did not stamp it (no
+ * `chant.decl` key) or the release knows neither attribute.
+ *
+ * A Machine's env values are literal, so the deploy writes the full value in
+ * place of a `CHANT_RELEASE_ATTRIBUTES` reference the platform would expand.
+ * The release's keys replace the same keys in the declared value, as the
+ * suffix appended last does on Compose and Kubernetes: a digest-pinned image
+ * gave the build a `service.version`, and the release may run another image.
+ */
+export function releaseResourceAttributes(declared, release) {
+    if (typeof declared !== "string")
+        return undefined;
+    const pairs = declared.split(",").filter((kv) => kv !== "");
+    const key = (kv) => kv.split("=")[0].trim();
+    if (!pairs.some((kv) => key(kv) === "chant.decl"))
+        return undefined;
+    const added = releaseAttributesSuffix(release).split(",").filter((kv) => kv !== "");
+    if (added.length === 0)
+        return undefined;
+    const replaced = new Set(added.map(key));
+    return [...pairs.filter((kv) => !replaced.has(key(kv))), ...added].join(",");
+}
+function loadTarget(planPath, machine) {
+    const plan = parsePlan(readFileSync(planPath, "utf8"));
+    return { plan, target: releaseTarget(plan, machine) };
+}
+const uriOf = (app, machine) => `fly://${app}/${machine}`;
+/** Build the `fly-release` capability. */
+export function createFlyReleaseCapability(deps = {}) {
+    const log = deps.log ?? ((line) => console.error(line));
+    const httpFor = () => deps.http ?? defaultFlyHttp();
+    async function rollBack(ctx, input, output) {
+        if (!output)
+            return;
+        const http = httpFor();
+        const target = { app: output.app, machine: output.machine.name, endpoint: input.endpoint };
+        if (!output.previous) {
+            await flyMachineStop({ ...target, wait: input.wait }, undefined, http);
+            log(`fly-release: nothing served before ${output.digest}; stopped ${output.app}/${output.machine.name}`);
+            return;
+        }
+        const store = await (deps.configStore ?? defaultConfigStore)(ctx);
+        const config = await store.read({ app: output.app, machine: output.machine.name, digest: output.previous.digest });
+        if (!config) {
+            throw new Error(`fly-release: no recorded Machine config for ${output.previous.digest} on ${output.app}/${output.machine.name}; nothing to roll back to`);
+        }
+        await flyMachineRestore({ ...target, config, wait: input.wait }, undefined, http);
+        log(`fly-release: rolled ${output.app}/${output.machine.name} back to ${output.previous.digest}`);
+    }
+    return {
+        kind: "fly-release",
+        rollbackPolicy: "native",
+        async run(ctx, input) {
+            if (!input.digest)
+                throw new Error("fly-release: a release needs its digest");
+            const http = httpFor();
+            const { plan, target } = loadTarget(input.plan, input.machine);
+            const gitSha = input.gitSha ?? (await (deps.headCommit ?? defaultHeadCommit)());
+            const configs = await (deps.configStore ?? defaultConfigStore)(ctx);
+            // The tree is checked against its digest before the Machine changes.
+            const source = input.source ? await sourceMachineFiles(input.source) : undefined;
+            // APP_REVISION carries the commit into the Machine's env, as chud's
+            // fly-site.mjs did (chant#2834), so the app's own /health can report
+            // it. A caller's own APP_REVISION (input.env) wins over the commit.
+            // A stamped Machine's resource attributes name the same release as its
+            // metadata (#3061, ws-081), unless the caller sets its own.
+            const declaredEnv = target.request.body.config?.env;
+            const attributes = releaseResourceAttributes(declaredEnv?.OTEL_RESOURCE_ATTRIBUTES, { version: input.digest, revision: gitSha });
+            const env = {
+                APP_REVISION: gitSha,
+                ...(attributes !== undefined ? { OTEL_RESOURCE_ATTRIBUTES: attributes } : {}),
+                ...(input.env ?? {}),
+            };
+            const released = await flyMachineRelease({
+                plan,
+                machine: input.machine,
+                release: { digest: input.digest, gitSha, ...(input.release ? { release: input.release } : {}) },
+                image: input.image,
+                env,
+                ...(source ? { files: source.files, cmd: source.cmd } : {}),
+                endpoint: input.endpoint,
+                wait: input.wait,
+            }, undefined, http);
+            const where = { app: released.app, machine: released.machine.name, endpoint: input.endpoint };
+            log(`fly-release: ${released.app}/${released.machine.name} ${released.action}, serving ${input.digest}`);
+            // The config the Machine served before is kept too, so a Machine
+            // released before chant recorded configs can still be rolled back to.
+            const replaced = released.previous?.release;
+            const previousRelease = replaced && replaced.digest !== input.digest
+                ? replaced
+                : released.release.previousDigest
+                    ? { digest: released.release.previousDigest }
+                    : null;
+            if (replaced && previousRelease?.digest === replaced.digest && !(await configs.read({ app: released.app, machine: released.machine.name, digest: previousRelease.digest }))) {
+                await configs.write({ app: released.app, machine: released.machine.name, digest: previousRelease.digest }, released.previous.config);
+            }
+            const migrations = [];
+            try {
+                if (input.migrations?.length) {
+                    const receipts = await (deps.receiptStore ?? defaultReceiptStore)(ctx);
+                    for (const migration of input.migrations) {
+                        const { ref, expectation } = migrationReceipt(released.app, migration);
+                        if ((await receipts.read(ref)) === expectation) {
+                            migrations.push({ name: migration.name, fired: false });
+                            continue;
+                        }
+                        log(`fly-release: migrating ${migration.name} on ${released.app}/${released.machine.name}`);
+                        await flyMachineExec({ ...where, command: migration.command }, undefined, http);
+                        // The receipt is written last, on success only: a failed migration fires again next run.
+                        await receipts.write(ref, expectation);
+                        migrations.push({ name: migration.name, fired: true });
+                    }
+                    if (migrations.some((m) => m.fired))
+                        await flyMachineRestart({ ...where, wait: input.wait }, undefined, http);
+                }
+                await flyMachineVerify({ ...where, digest: input.digest, ...(input.verify ?? {}) }, undefined, http, deps.fetch);
+            }
+            catch (err) {
+                // Restore: the Machine changed, so put back what it served (or stop it
+                // when it served nothing), then fail the step.
+                try {
+                    if (released.previous) {
+                        await flyMachineRestore({ ...where, config: released.previous.config, wait: input.wait }, undefined, http);
+                        log(`fly-release: restored ${released.app}/${released.machine.name} to ${previousRelease?.digest ?? "its previous config"}`);
+                    }
+                    else {
+                        await flyMachineStop({ ...where, wait: input.wait }, undefined, http);
+                        log(`fly-release: nothing had been released on ${released.app}/${released.machine.name}; stopped it`);
+                    }
+                }
+                catch (restoreErr) {
+                    log(`fly-release: restore failed: ${restoreErr instanceof Error ? restoreErr.message : String(restoreErr)}`);
+                }
+                throw err;
+            }
+            await configs.write({ app: released.app, machine: released.machine.name, digest: input.digest }, released.config);
+            return {
+                uri: uriOf(released.app, released.machine.name),
+                digest: input.digest,
+                ...(gitSha ? { gitSha } : {}),
+                app: released.app,
+                machine: released.machine,
+                previous: previousRelease,
+                migrations,
+            };
+        },
+        rollback: rollBack,
+    };
+}
+/** Build the `fly-rollback` capability. */
+export function createFlyRollbackCapability(deps = {}) {
+    const log = deps.log ?? ((line) => console.error(line));
+    const httpFor = () => deps.http ?? defaultFlyHttp();
+    async function recordedConfig(ctx, app, machine, digest) {
+        const store = await (deps.configStore ?? defaultConfigStore)(ctx);
+        const config = await store.read({ app, machine, digest });
+        if (!config)
+            throw new Error(`fly-rollback: no recorded Machine config for ${digest} on ${app}/${machine}`);
+        return config;
+    }
+    async function restoreTo(ctx, input, app, machine, digest, config, serving) {
+        config ?? (config = await recordedConfig(ctx, app, machine, digest));
+        const http = httpFor();
+        // Already serving it (a rerun after the rollback finished): leave the Machine as it is.
+        if (serving !== digest)
+            await flyMachineRestore({ app, machine, config, endpoint: input.endpoint, wait: input.wait }, undefined, http);
+        await flyMachineVerify({ app, machine, digest, endpoint: input.endpoint, ...(input.verify ?? {}) }, undefined, http, deps.fetch);
+        return readMachineRelease(config.metadata);
+    }
+    return {
+        kind: "fly-rollback",
+        rollbackPolicy: "native",
+        async run(ctx, input) {
+            // The tree is checked against its digest before any flaps call.
+            const tree = input.source ? await sourceTreeFiles(input.source, "fly-rollback") : undefined;
+            const http = httpFor();
+            const { target } = loadTarget(input.plan, input.machine);
+            const live = await findMachine({ base: resolveEndpoint(input) }, target.app, target.name, http);
+            if (!live)
+                throw new Error(`fly-rollback: no machine ${target.name} on app ${target.app}`);
+            const serving = readMachineRelease(live.config?.metadata);
+            const to = input.to ?? serving?.previousDigest;
+            if (!to)
+                throw new Error(`fly-rollback: ${target.app}/${target.name} serves ${serving?.digest ?? "no release"}, with no release before it to roll back to`);
+            const config = await recordedConfig(ctx, target.app, target.name, to);
+            if (tree) {
+                const differs = treeDifference(config, tree, intoOf(input.source));
+                if (differs) {
+                    throw new Error(`fly-rollback: the Machine config recorded for ${to} does not carry the tree ${input.source.digest} (${differs}); refusing to restore it`);
+                }
+            }
+            const restored = await restoreTo(ctx, input, target.app, target.name, to, config, serving?.digest);
+            log(serving?.digest === to
+                ? `fly-rollback: ${target.app}/${target.name} already serves ${to}`
+                : `fly-rollback: ${target.app}/${target.name} serves ${to} again (was ${serving?.digest ?? "no release"})`);
+            return {
+                uri: uriOf(target.app, target.name),
+                digest: to,
+                ...(restored?.gitSha ? { gitSha: restored.gitSha } : {}),
+                app: target.app,
+                machine: { id: live.id, name: target.name },
+                previous: serving ?? null,
+            };
+        },
+        async rollback(ctx, input, output) {
+            if (!output?.previous)
+                return;
+            await restoreTo(ctx, input, output.app, output.machine.name, output.previous.digest);
+        },
+    };
+}
+/**
+ * How a recorded Machine config's files under `into` differ from a source
+ * tree, or undefined when they are the same files with the same bytes. Pure.
+ */
+export function treeDifference(config, tree, into) {
+    const prefix = `${into}/`;
+    const recorded = new Map((config.files ?? []).filter((f) => f.guest_path.startsWith(prefix)).map((f) => [f.guest_path, f.raw_value]));
+    for (const f of tree) {
+        const bytes = recorded.get(f.guest_path);
+        if (bytes === undefined)
+            return `${f.guest_path} is not in it`;
+        if (bytes !== f.raw_value)
+            return `${f.guest_path} has other bytes`;
+        recorded.delete(f.guest_path);
+    }
+    const extra = [...recorded.keys()][0];
+    return extra ? `it also carries ${extra}` : undefined;
+}
+/** The default `fly-release` capability. */
+export const flyReleaseCapability = createFlyReleaseCapability();
+/** The default `fly-rollback` capability. */
+export const flyRollbackCapability = createFlyRollbackCapability();

package/dist/components/index.js

@@ -0,0 +1,10 @@
+/**
+ * The fly lexicon's component/release surface: the `run-agent` capability,
+ * its real `SpriteActivities` adapter, and the `flyCapabilityPlugin` core
+ * loads when a project declares `lexicons: ["fly"]` (#1942). Component
+ * authors reach these from `@intentius/chant-lexicon-fly/components`, the way
+ * AWS and helm verbs come from their lexicons' `/components` entries.
+ */
+export { flyCapabilityPlugin, FLY_VERB_FAMILIES } from "./capability-plugin.js";
+export { flyRunAgentCapability, createFlyRunAgentCapability, createFlySpriteActivities, parseSpriteExecFailure, } from "./run-agent.js";
+export { flyReleaseCapability, flyRollbackCapability, createFlyReleaseCapability, createFlyRollbackCapability, migrationReceipt, } from "./fly-release.js";

package/dist/components/run-agent.js

@@ -0,0 +1,133 @@
+/**
+ * `run-agent`'s fly-lexicon adapter (#1942, epic #1564 phase 2) — the real
+ * `SpriteActivities` implementation
+ * (`@intentius/chant/components/verbs/run-agent`) over this lexicon's own
+ * sprite lifecycle activities (`../op/activities/sprites.ts` +
+ * `../op/activities/sprite-fs.ts`), and the `run-agent` capability built over
+ * it. Registered through this lexicon's own `CapabilityPlugin`
+ * (`./capability-plugin.ts`) the same way aws contributes `cfn-deploy` and
+ * helm contributes `helm-upgrade` (docs/components/cloud-boundary) — core's
+ * `createRunAgentCapability` (the sequencing logic: create-or-reuse,
+ * checkpoint, stage, exec, collect, destroy/leave-alive, restore-by-comment)
+ * stays cloud-agnostic in `@intentius/chant`, structurally independent of
+ * this package; this module is the one piece with the hard dependency on the
+ * real sprite wire protocol.
+ *
+ * **The exec-throw finding (pre-merge review of #1946, recorded on #1942).**
+ * The real `spriteExec` (`../op/activities/sprites.ts`) throws on any
+ * non-zero exit — by design, so a *scripted Op phase*
+ * (`examples/sprites-agent-task/ops/guarded-task.op.ts`) fails and triggers
+ * its `onFailure` compensation. But `run-agent`'s `RunAgentOutput.turn.status`
+ * includes `"failed"` as a first-class, non-throwing result — an ordinary
+ * failed agent turn (the model's diff didn't compile, its tests failed,
+ * whatever the exit code means) is not an infrastructure failure and should
+ * not by itself unwind the saga (checkpoint restore is for "the sprite
+ * backend broke," not "the agent's output wasn't good"). Resolved here as
+ * **option (a)** from the review comment: `exec()` below wraps the real
+ * `spriteExec` in a try/catch and reclassifies a thrown non-zero-exit error
+ * back into a resolved `{ stdout, stderr, exitCode }`
+ * (`parseSpriteExecFailure`), so `SpriteActivities.exec` always resolves for
+ * an ordinary command outcome — exactly the contract core's `run()`
+ * (`packages/core/src/components/verbs/run-agent.ts`) assumes and relies on
+ * (it deliberately has *no* try/catch of its own around `sprites.exec`). A
+ * genuine transport/infra failure — the WebSocket erroring, connection
+ * refused, an aborted signal — does not match the reclassification pattern
+ * and still rejects, so core's saga-unwind path is preserved for *real*
+ * failures.
+ *
+ * Option (b) — accept that ordinary failures throw, and drop `"failed"` from
+ * `turn.status`'s reachable states — was rejected: it would make every
+ * failed agent turn indistinguishable from a genuine sprite outage, forcing
+ * a checkpoint-restore rollback for what is often just an unsuccessful
+ * attempt, which is not what "the environment is the transaction" is meant
+ * to protect against, and it would leave `RunAgentOutput.turn.status:
+ * "failed"` a dead, unreachable branch of a type #1941 deliberately shipped
+ * as reachable.
+ *
+ * **Fidelity note.** The real `spriteExec`'s thrown message carries only
+ * `stderr || stdout` combined (see its own doc comment in `sprites.ts`), not
+ * both streams separately — the reclassified result therefore folds that
+ * combined text into `stderr` and leaves `stdout` empty on the failure path.
+ * This is a known, documented loss versus a real non-throwing exec; recovering
+ * full stream fidelity would mean reimplementing the WebSocket exec framing
+ * here rather than reusing `spriteExec`, which is out of this issue's scope
+ * (core's module doc calls adapting the existing activities "a thin wrapper,
+ * not a rewrite").
+ */
+import { createRunAgentCapability, } from "@intentius/chant/components/verbs/run-agent";
+import { spriteCreate, spriteCheckpoint, spriteExec, spriteRestore, spriteDestroy } from "../op/activities/sprites.js";
+import { spriteWriteFile, spriteReadFile } from "../op/activities/sprite-fs.js";
+/**
+ * Parse the exit code + combined output text out of the real `spriteExec`'s
+ * thrown message shape: `sprite <id> exec "<cmd>" exited <code>: <text>`
+ * (see `../op/activities/sprites.ts`'s `spriteExec`). Returns `undefined` for
+ * any other error shape — a genuine transport/infra failure the caller
+ * should let propagate. Exported for direct unit testing of the
+ * reclassification the module doc above describes as option (a).
+ *
+ * The leading `[\s\S]*` is greedy on purpose: `spriteExec`'s message echoes
+ * the raw `cmd` verbatim before the real ` exited <code>: ` marker
+ * (`exec "<cmd>" exited ...`), so a crafted command whose text itself
+ * contains that exact substring must not be mistaken for the marker. A
+ * greedy prefix backtracks from the end of the string, so it always anchors
+ * to the *last* occurrence — the genuine marker `spriteExec` appended — never
+ * a leftmost false match inside the echoed `cmd`.
+ */
+export function parseSpriteExecFailure(err) {
+    if (!(err instanceof Error))
+        return undefined;
+    const m = err.message.match(/^[\s\S]* exited (\d+): ([\s\S]*)$/);
+    if (!m)
+        return undefined;
+    const exitCode = Number(m[1]);
+    if (!Number.isFinite(exitCode))
+        return undefined;
+    return { exitCode, output: m[2] };
+}
+/**
+ * The real `SpriteActivities` implementation: a thin wrapper over this
+ * lexicon's own sprite lifecycle + filesystem activities, matching
+ * `@intentius/chant/components/verbs/run-agent`'s injectable seam exactly
+ * (see that module's doc comment — "adapting them is a thin wrapper, not a
+ * rewrite"). `exec()` is the one method that is not a bare pass-through — see
+ * this module's doc comment for why.
+ */
+export function createFlySpriteActivities() {
+    return {
+        async create(args, signal) {
+            return spriteCreate({ name: args.name, image: args.image }, signal);
+        },
+        async checkpoint(args, signal) {
+            return spriteCheckpoint({ id: args.id, comment: args.comment }, signal);
+        },
+        async exec(args, signal) {
+            try {
+                return await spriteExec({ id: args.id, cmd: args.cmd, timeoutMs: args.timeoutMs }, signal);
+            }
+            catch (err) {
+                const parsed = parseSpriteExecFailure(err);
+                if (!parsed)
+                    throw err; // a genuine transport/infra failure — propagate it.
+                return { stdout: "", stderr: parsed.output, exitCode: parsed.exitCode };
+            }
+        },
+        async restore(args, signal) {
+            await spriteRestore({ id: args.id, checkpoint: args.checkpoint, comment: args.comment }, signal);
+        },
+        async destroy(args, signal) {
+            await spriteDestroy({ id: args.id }, signal);
+        },
+        async writeFile(args, signal) {
+            await spriteWriteFile({ id: args.id, path: args.path, content: args.content, mkdir: args.mkdir }, signal);
+        },
+        async readFile(args, signal) {
+            return spriteReadFile({ id: args.id, path: args.path }, signal);
+        },
+    };
+}
+/** Build the `run-agent` capability over the real fly sprite backend. */
+export function createFlyRunAgentCapability() {
+    return createRunAgentCapability(createFlySpriteActivities());
+}
+/** Default `run-agent` capability, backed by the real `SpriteActivities` adapter above — what `flyCapabilityPlugin` (./capability-plugin.ts) registers. */
+export const flyRunAgentCapability = createFlyRunAgentCapability();

package/dist/composites/catalog.js

@@ -0,0 +1,176 @@
+export const compositeCatalog = [
+    {
+        "name": "FlyOtelCollector",
+        "lexicon": "fly",
+        "description": "Create a FlyOtelCollector composite.",
+        "bundles": [
+            "Machine"
+        ],
+        "params": [
+            {
+                "name": "name",
+                "type": "string",
+                "required": false,
+                "description": "Machine name (default: \"otel-collector\")."
+            },
+            {
+                "name": "app",
+                "type": "string | Declarable",
+                "required": false,
+                "description": "The app the machine belongs to, as an app name."
+            },
+            {
+                "name": "region",
+                "type": "string | Declarable",
+                "required": false,
+                "description": "Region (default: `Fly.Region`, which the build resolves from `FLY_REGION`)."
+            },
+            {
+                "name": "image",
+                "type": "string",
+                "required": false,
+                "description": "Collector image (default: the contrib image at the otel lexicon's pinned collector version)."
+            },
+            {
+                "name": "config",
+                "type": "Iterable<Declarable>",
+                "required": false,
+                "description": "The collector config, as otel lexicon entities (components and pipelines)."
+            },
+            {
+                "name": "exporters",
+                "type": "OTelComponent<\"exporter\", string, any>[]",
+                "required": false,
+                "description": "Exporters for the default config (default: one `debug` exporter)."
+            },
+            {
+                "name": "signals",
+                "type": "Signal[]",
+                "required": false,
+                "description": "Signals the default config has pipelines for (default: traces, metrics and logs)."
+            },
+            {
+                "name": "cpuKind",
+                "type": "string",
+                "required": false,
+                "description": "Guest CPU kind (default: \"shared\")."
+            },
+            {
+                "name": "cpus",
+                "type": "number",
+                "required": false,
+                "description": "Guest CPUs (default: 1)."
+            },
+            {
+                "name": "memoryMb",
+                "type": "number",
+                "required": false,
+                "description": "Guest memory in MB (default: 512)."
+            },
+            {
+                "name": "defaults",
+                "type": "{ machine?: Partial<Record<string, unknown>>; }",
+                "required": false,
+                "description": "Per-member defaults for fine-grained overrides."
+            }
+        ]
+    },
+    {
+        "name": "FlySite",
+        "lexicon": "fly",
+        "description": "Create a FlySite composite.",
+        "bundles": [
+            "App",
+            "IPAddress",
+            "Machine",
+            "Secret",
+            "Volume"
+        ],
+        "params": [
+            {
+                "name": "app",
+                "type": "string",
+                "required": true,
+                "description": "The App's name."
+            },
+            {
+                "name": "org",
+                "type": "string | Declarable",
+                "required": false,
+                "description": "The owning org (default: `Fly.OrgSlug`, which the build resolves from `FLY_ORG`)."
+            },
+            {
+                "name": "region",
+                "type": "string | Declarable",
+                "required": false,
+                "description": "Region of the Machine and the Volume (default: `Fly.Region`, from `FLY_REGION`)."
+            },
+            {
+                "name": "machine",
+                "type": "string",
+                "required": false,
+                "description": "The Machine's name (default: \"web\")."
+            },
+            {
+                "name": "image",
+                "type": "string",
+                "required": true,
+                "description": "The image the Machine runs until a release replaces it."
+            },
+            {
+                "name": "port",
+                "type": "number",
+                "required": false,
+                "description": "The port the app listens on inside the Machine (default: 8080)."
+            },
+            {
+                "name": "env",
+                "type": "Record<string, string>",
+                "required": false,
+                "description": "The Machine's env."
+            },
+            {
+                "name": "cpuKind",
+                "type": "string",
+                "required": false,
+                "description": "Guest CPU kind (default: \"shared\")."
+            },
+            {
+                "name": "cpus",
+                "type": "number",
+                "required": false,
+                "description": "Guest CPUs (default: 1)."
+            },
+            {
+                "name": "memoryMb",
+                "type": "number",
+                "required": false,
+                "description": "Guest memory in MB (default: 256)."
+            },
+            {
+                "name": "volume",
+                "type": "{ name: string; sizeGb: number; path: string }",
+                "required": false,
+                "description": "A Volume for the app's data, mounted at `path`."
+            },
+            {
+                "name": "ip",
+                "type": "\"shared_v4\" | \"v4\" | \"v6\"",
+                "required": false,
+                "description": "A public IP of this type (for example \"shared_v4\")."
+            },
+            {
+                "name": "secrets",
+                "type": "Record<string, string | undefined>",
+                "required": false,
+                "description": "The app's Secrets, by name."
+            },
+            {
+                "name": "defaults",
+                "type": "{ app?: Partial<Record<string, unknown>>; machine?: Partial<Record<string, unknown>>; volume?: Partial<Record<string,...",
+                "required": false,
+                "description": "Per-member defaults for fine-grained overrides."
+            }
+        ]
+    }
+];