@intentius/chant-lexicon-fly 0.46.0 → 0.50.0

package/dist/components/capability-plugin.d.ts

@@ -0,0 +1,6 @@
+import { type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+export declare const FLY_VERB_FAMILIES: {
+    readonly agentExecution: readonly ["run-agent"];
+};
+export declare const flyCapabilityPlugin: CapabilityPlugin;
+//# sourceMappingURL=capability-plugin.d.ts.map

package/dist/components/capability-plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-plugin.d.ts","sourceRoot":"","sources":["../../src/components/capability-plugin.ts"],"names":[],"mappings":"AAeA,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,+CAA+C,CAAC;AAGzG,eAAO,MAAM,iBAAiB;;CAEpB,CAAC;AAEX,eAAO,MAAM,mBAAmB,EAAE,gBAajC,CAAC"}

package/dist/components/index.d.ts

@@ -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";
+//# sourceMappingURL=index.d.ts.map

package/dist/components/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/components/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,aAAa,CAAC"}

package/dist/components/run-agent.d.ts

@@ -0,0 +1,92 @@
+/**
+ * `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 type { Capability } from "@intentius/chant/components/capability";
+import { type RunAgentInput, type RunAgentOutput, type SpriteActivities } from "@intentius/chant/components/verbs/run-agent";
+/**
+ * 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 declare function parseSpriteExecFailure(err: unknown): {
+    exitCode: number;
+    output: string;
+} | undefined;
+/**
+ * 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 declare function createFlySpriteActivities(): SpriteActivities;
+/** Build the `run-agent` capability over the real fly sprite backend. */
+export declare function createFlyRunAgentCapability(): Capability<RunAgentInput, RunAgentOutput>;
+/** Default `run-agent` capability, backed by the real `SpriteActivities` adapter above — what `flyCapabilityPlugin` (./capability-plugin.ts) registers. */
+export declare const flyRunAgentCapability: Capability<RunAgentInput, RunAgentOutput>;
+//# sourceMappingURL=run-agent.d.ts.map

package/dist/components/run-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-agent.d.ts","sourceRoot":"","sources":["../../src/components/run-agent.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wCAAwC,CAAC;AACzE,OAAO,EAEL,KAAK,aAAa,EAClB,KAAK,cAAc,EACnB,KAAK,gBAAgB,EACtB,MAAM,6CAA6C,CAAC;AAIrD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,sBAAsB,CAAC,GAAG,EAAE,OAAO,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAAG,SAAS,CAOrG;AAED;;;;;;;GAOG;AACH,wBAAgB,yBAAyB,IAAI,gBAAgB,CA8B5D;AAED,yEAAyE;AACzE,wBAAgB,2BAA2B,IAAI,UAAU,CAAC,aAAa,EAAE,cAAc,CAAC,CAEvF;AAED,2JAA2J;AAC3J,eAAO,MAAM,qBAAqB,EAAE,UAAU,CAAC,aAAa,EAAE,cAAc,CAAiC,CAAC"}

package/dist/composites/fly-deploy.d.ts

@@ -23,7 +23,7 @@
  * `FLY_API_TOKEN`).
  */
 import type { OpResource } from "@intentius/chant/op";
-import type { ActivityStep } from "@intentius/chant/op";
+import type { ActivityStep, NamedActivityStep } from "@intentius/chant/op";
 /** The local mudflaps endpoint the deploy Op targets by default. */
 export declare const LOCAL_FLAPS_ENDPOINT = "http://localhost:4280";
 /** Options accepted by the mudflaps lifecycle step builders. */
@@ -47,9 +47,9 @@ export interface FlapsStepOpts {
  * `flapsUp` activity (#740). Defaults to the `longInfra` profile (the image may
  * pull); override via `opts.profile`.
  */
-export declare const flapsUp: (opts?: FlapsStepOpts) => ActivityStep;
+export declare const flapsUp: (opts?: FlapsStepOpts) => NamedActivityStep;
 /** Stop and remove the local mudflaps container. Resolves to the `flapsDown` activity. Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
-export declare const flapsDown: (opts?: FlapsStepOpts) => ActivityStep;
+export declare const flapsDown: (opts?: FlapsStepOpts) => NamedActivityStep;
 /** Options for the flaps apply step (mirror `FlyApplyArgs`, minus `planPath`). */
 export interface FlyApplyStepOpts {
     /** flaps endpoint override (D3). Default: `FLY_FLAPS_BASE_URL` env, else real Fly. */
@@ -69,7 +69,7 @@ export interface FlyApplyStepOpts {
  * App + Machine, wait each machine to `started`, prune owned-only when asked.
  * Defaults to the `longInfra` profile (override via `opts.profile`).
  */
-export declare const flyApplyStep: (planPath: string, opts?: FlyApplyStepOpts) => ActivityStep;
+export declare const flyApplyStep: (planPath: string, opts?: FlyApplyStepOpts) => NamedActivityStep;
 /** Options for {@link flyDeploy}. */
 export interface FlyDeployOpts {
     /** Op name (the `chant run <name>` target). Default: `fly`. */

package/dist/composites/fly-deploy.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fly-deploy.d.ts","sourceRoot":"","sources":["../../src/composites/fly-deploy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAExD,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,aAAa,KAAG,YAG9C,CAAC;AAEF,kKAAkK;AAClK,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,KAAG,YAGhD,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,iCAAiC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,EAAE,OAAO,gBAAgB,KAAG,YAGxE,CAAC;AAEF,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,aAAkB,GAAG,YAAY,CAAC,OAAO,UAAU,CAAC,CAyCnF"}
+{"version":3,"file":"fly-deploy.d.ts","sourceRoot":"","sources":["../../src/composites/fly-deploy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE3E,oEAAoE;AACpE,eAAO,MAAM,oBAAoB,0BAA0B,CAAC;AAE5D,gEAAgE;AAChE,MAAM,WAAW,aAAa;IAC5B,iDAAiD;IACjD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,+BAA+B;IAC/B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kCAAkC;IAClC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,iCAAiC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,OAAO,GAAI,OAAO,aAAa,KAAG,iBAG9C,CAAC;AAEF,kKAAkK;AAClK,eAAO,MAAM,SAAS,GAAI,OAAO,aAAa,KAAG,iBAGhD,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,gBAAgB;IAC/B,sFAAsF;IACtF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,gFAAgF;IAChF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,2CAA2C;IAC3C,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,iCAAiC;IACjC,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAC;CACnC;AAED;;;;;GAKG;AACH,eAAO,MAAM,YAAY,GAAI,UAAU,MAAM,EAAE,OAAO,gBAAgB,KAAG,iBAGxE,CAAC;AAEF,qCAAqC;AACrC,MAAM,WAAW,aAAa;IAC5B,+DAA+D;IAC/D,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,wBAAwB;IACxB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,gFAAgF;IAChF,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,oFAAoF;IACpF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,qDAAqD;IACrD,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB;;;;OAIG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,2EAA2E;IAC3E,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CAChC;AAED;;;;GAIG;AACH,wBAAgB,SAAS,CAAC,IAAI,GAAE,aAAkB,GAAG,YAAY,CAAC,OAAO,UAAU,CAAC,CAyCnF"}

package/dist/index.d.ts

@@ -1,9 +1,10 @@
 export { flyPlugin } from "./plugin.js";
+export { flyCapabilityPlugin, FLY_VERB_FAMILIES } from "./components/capability-plugin.js";
 export { flySerializer } from "./serializer.js";
 export { Fly, Region, OrgSlug, AppName, PseudoParameter } from "./pseudo.js";
 export { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership.js";
 export { flyDeploy, flapsUp, flapsDown, flyApplyStep, LOCAL_FLAPS_ENDPOINT } from "./composites/fly-deploy.js";
 export type { FlyDeployOpts, FlyApplyStepOpts, FlapsStepOpts } from "./composites/fly-deploy.js";
-export { spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy, spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove, spriteApplyNetworkPolicy, spriteApplyServices, spriteTaskCreate, spriteTaskRefresh, spriteTaskRelease, spritesUp, spritesDown, } from "@intentius/chant/op";
+export { spriteCreate, spriteExec, spriteCheckpoint, spriteRestore, listCheckpoints, spriteDestroy, spriteWriteFile, spriteReadFile, spriteListDir, spriteRemove, spriteApplyNetworkPolicy, spriteApplyServices, spriteTaskCreate, spriteTaskRefresh, spriteTaskRelease, spritesUp, spritesDown, } from "./op/builders.js";
 export * from "./generated/index.js";
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAGrC,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7C,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG1E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAK1D,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC5G,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAM9F,OAAO,EACL,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,EACd,aAAa,EACb,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,WAAW,GACZ,MAAM,qBAAqB,CAAC;AAK7B,cAAc,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AAKrC,OAAO,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AAGxF,OAAO,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAI7C,OAAO,EAAE,GAAG,EAAE,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,UAAU,CAAC;AAG1E,OAAO,EAAE,2BAA2B,EAAE,MAAM,aAAa,CAAC;AAK1D,OAAO,EAAE,SAAS,EAAE,OAAO,EAAE,SAAS,EAAE,YAAY,EAAE,oBAAoB,EAAE,MAAM,yBAAyB,CAAC;AAC5G,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,aAAa,EAAE,MAAM,yBAAyB,CAAC;AAY9F,OAAO,EACL,YAAY,EACZ,UAAU,EACV,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,aAAa,EACb,eAAe,EACf,cAAc,EACd,aAAa,EACb,YAAY,EACZ,wBAAwB,EACxB,mBAAmB,EACnB,gBAAgB,EAChB,iBAAiB,EACjB,iBAAiB,EACjB,SAAS,EACT,WAAW,GACZ,MAAM,eAAe,CAAC;AAKvB,cAAc,mBAAmB,CAAC"}

package/dist/integrity.json

@@ -1,7 +1,7 @@
 {
   "algorithm": "sha256",
   "artifacts": {
-    "manifest.json": "87eb08737e0b05d0dff013f5a3474cf9da153f6727ee8d15f637ce7f286031a4",
+    "manifest.json": "b0f8ad61d227846aa9e9b009f914ad9de0fcead8b25762b428fbdd4925e7de02",
     "meta.json": "e46e65ba7544fafc6dbb3fd48b841904b5ae6f7cb4d517a940ed68b01626c097",
     "types/index.d.ts": "a76090adb6eda33a2c07a074183299a59e953b48dd3f2020d7ef11278d59341e",
     "rules/guest-sizing.ts": "bc749d218df8f3cc3d8fbe388205ae96e6b204ae0d6d77e8bf82cb936cc53ff6",
@@ -15,5 +15,5 @@
     "skills/chant-fly-ops.md": "b8eef6504e203133e6a35c83aabb08404eec95060705395515a0046d42269cf1",
     "skills/chant-fly-sprites.md": "89ba52db63a71a17eab483d99233a4ae67f5d34920445010e750f81c95200b4e"
   },
-  "composite": "6e0ad16fc43da2edad2bc8bfa9a6a42ced592d6b8871914af192c11099fdb8ee"
+  "composite": "df763245c52d1694a647ca5974652d679f8ba0e130735c48305180e98657881e"
 }

package/dist/manifest.json

@@ -1,6 +1,6 @@
 {
   "name": "fly",
-  "version": "0.46.0",
+  "version": "0.50.0",
   "chantVersion": ">=0.1.0",
   "namespace": "Fly"
 }

package/dist/op/builders.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Typed step-builder wrappers for this lexicon's sprite activities (chant
+ * #1288 Stage 2 — "regenerate the step builders as fully typed wrappers").
+ * Core's own sprite builders (`spriteCreate`, `spriteExec`, ...) already
+ * carry an inline object-literal type in `packages/core/src/op/builders.ts`
+ * — but that inline type is a hand-restated MIRROR of this lexicon's own
+ * `Sprite*Args` interfaces (`./activities/sprites.ts`,
+ * `./activities/sprite-fs.ts`, `./activities/sprite-tasks.ts`,
+ * `./activities/sprite-config.ts`, `./activities/sprites-emulator.ts`),
+ * exactly the duplication Stage 2 exists to eliminate. `opts`'s type in
+ * every wrapper below IS the activity's own `*Args` interface (via
+ * `WithStepRefs`) — never restated — so it stays in sync with the
+ * implementation by construction.
+ *
+ * There's no cross-package layering problem here (unlike `kubectlApply`/
+ * `helmInstall`): this package already owns both the activities and (per
+ * `./composites/fly-deploy.ts`'s existing `flapsUp`/`flapsDown`/
+ * `flyApplyStep` precedent, #744) the step-builder layer. So — matching how
+ * `lexicons/temporal/src/op/builders.ts` handles ITS OWN activities — this
+ * module REPLACES (not adds alongside) the sprite builders this package's
+ * `src/index.ts` used to re-export from `@intentius/chant/op`: same names,
+ * same import path (`@intentius/chant-lexicon-fly`), so an existing
+ * `import { spriteCreate } from "@intentius/chant-lexicon-fly"` call site
+ * gains authoring-time types and `StepOutputRef`/`.out` support with no
+ * change. `core`'s own originals are untouched, for anyone still importing
+ * `@intentius/chant/op` directly.
+ */
+import { type NamedActivityStep, type WithStepRefs } from "@intentius/chant/op";
+import type { ActivityStep } from "@intentius/chant/op";
+import type { SpriteCreateArgs, SpriteExecArgs, SpriteCheckpointArgs, SpriteRestoreArgs, ListCheckpointsArgs, SpriteDestroyArgs } from "./activities/sprites.js";
+import type { SpriteWriteFileArgs, SpriteReadFileArgs, SpriteListDirArgs, SpriteRemoveArgs } from "./activities/sprite-fs.js";
+import type { SpriteApplyNetworkPolicyArgs, SpriteApplyServicesArgs } from "./activities/sprite-config.js";
+import type { SpriteTaskCreateArgs, SpriteTaskRefreshArgs, SpriteTaskReleaseArgs } from "./activities/sprite-tasks.js";
+import type { SpritesUpArgs, SpritesDownArgs } from "./activities/sprites-emulator.js";
+type StepOpts = {
+    profile?: ActivityStep["profile"];
+};
+/** Create a sprite — the fully typed twin of core's `spriteCreate`. Defaults to the `longInfra` profile. */
+export declare const spriteCreate: (args: WithStepRefs<SpriteCreateArgs> & StepOpts) => NamedActivityStep;
+/** Run a command in a sprite — the fully typed twin of core's `spriteExec`. Defaults to the `longInfra` profile. */
+export declare const spriteExec: (args: WithStepRefs<SpriteExecArgs> & StepOpts) => NamedActivityStep;
+/** Checkpoint a sprite — the fully typed twin of core's `spriteCheckpoint`. Defaults to the `longInfra` profile. */
+export declare const spriteCheckpoint: (args: WithStepRefs<SpriteCheckpointArgs> & StepOpts) => NamedActivityStep;
+/** Restore a sprite — the fully typed twin of core's `spriteRestore`. Defaults to the `longInfra` profile. */
+export declare const spriteRestore: (args: WithStepRefs<SpriteRestoreArgs> & StepOpts) => NamedActivityStep;
+/** List a sprite's checkpoints — the fully typed twin of core's `listCheckpoints`. Defaults to the `fastIdempotent` profile. */
+export declare const listCheckpoints: (args: WithStepRefs<ListCheckpointsArgs> & StepOpts) => NamedActivityStep;
+/** Destroy a sprite — the fully typed twin of core's `spriteDestroy`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteDestroy: (args: WithStepRefs<SpriteDestroyArgs> & StepOpts) => NamedActivityStep;
+/** Write a file into a sprite — the fully typed twin of core's `spriteWriteFile`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteWriteFile: (args: WithStepRefs<SpriteWriteFileArgs> & StepOpts) => NamedActivityStep;
+/** Read a file from a sprite — the fully typed twin of core's `spriteReadFile`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteReadFile: (args: WithStepRefs<SpriteReadFileArgs> & StepOpts) => NamedActivityStep;
+/** List a directory in a sprite — the fully typed twin of core's `spriteListDir`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteListDir: (args: WithStepRefs<SpriteListDirArgs> & StepOpts) => NamedActivityStep;
+/** Remove a path in a sprite — the fully typed twin of core's `spriteRemove`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteRemove: (args: WithStepRefs<SpriteRemoveArgs> & StepOpts) => NamedActivityStep;
+/** Reconcile a sprite's outbound network policy — the fully typed twin of core's `spriteApplyNetworkPolicy`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteApplyNetworkPolicy: (args: WithStepRefs<SpriteApplyNetworkPolicyArgs> & StepOpts) => NamedActivityStep;
+/** Reconcile a sprite's background services — the fully typed twin of core's `spriteApplyServices`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteApplyServices: (args: WithStepRefs<SpriteApplyServicesArgs> & StepOpts) => NamedActivityStep;
+/** Create a keep-alive task — the fully typed twin of core's `spriteTaskCreate`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteTaskCreate: (args: WithStepRefs<SpriteTaskCreateArgs> & StepOpts) => NamedActivityStep;
+/** Refresh a keep-alive task's expiry — the fully typed twin of core's `spriteTaskRefresh`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteTaskRefresh: (args: WithStepRefs<SpriteTaskRefreshArgs> & StepOpts) => NamedActivityStep;
+/** Release a keep-alive task — the fully typed twin of core's `spriteTaskRelease`. Defaults to the `fastIdempotent` profile. */
+export declare const spriteTaskRelease: (args: WithStepRefs<SpriteTaskReleaseArgs> & StepOpts) => NamedActivityStep;
+/** Boot a local spritzer (Fly Sprites API emulator) — the fully typed twin of core's `spritesUp`. Defaults to the `longInfra` profile. */
+export declare const spritesUp: (args?: WithStepRefs<SpritesUpArgs> & StepOpts) => NamedActivityStep;
+/** Stop and remove the local spritzer container — the fully typed twin of core's `spritesDown`. Defaults to the `fastIdempotent` profile. */
+export declare const spritesDown: (args?: WithStepRefs<SpritesDownArgs> & StepOpts) => NamedActivityStep;
+export {};
+//# sourceMappingURL=builders.d.ts.map

package/dist/op/builders.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"builders.d.ts","sourceRoot":"","sources":["../../src/op/builders.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,OAAO,EAAY,KAAK,iBAAiB,EAAE,KAAK,YAAY,EAAE,MAAM,qBAAqB,CAAC;AAC1F,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC;AACxD,OAAO,KAAK,EAAE,gBAAgB,EAAE,cAAc,EAAE,oBAAoB,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AAC9J,OAAO,KAAK,EAAE,mBAAmB,EAAE,kBAAkB,EAAE,iBAAiB,EAAE,gBAAgB,EAAE,MAAM,wBAAwB,CAAC;AAC3H,OAAO,KAAK,EAAE,4BAA4B,EAAE,uBAAuB,EAAE,MAAM,4BAA4B,CAAC;AACxG,OAAO,KAAK,EAAE,oBAAoB,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AACpH,OAAO,KAAK,EAAE,aAAa,EAAE,eAAe,EAAE,MAAM,+BAA+B,CAAC;AAEpF,KAAK,QAAQ,GAAG;IAAE,OAAO,CAAC,EAAE,YAAY,CAAC,SAAS,CAAC,CAAA;CAAE,CAAC;AA6BtD,4GAA4G;AAC5G,eAAO,MAAM,YAAY,uDAPuB,iBAOqC,CAAC;AACtF,oHAAoH;AACpH,eAAO,MAAM,UAAU,qDATyB,iBAS+B,CAAC;AAChF,oHAAoH;AACpH,eAAO,MAAM,gBAAgB,2DAXmB,iBAWiD,CAAC;AAClG,8GAA8G;AAC9G,eAAO,MAAM,aAAa,wDAbsB,iBAawC,CAAC;AACzF,gIAAgI;AAChI,eAAO,MAAM,eAAe,0DAfoB,iBAemD,CAAC;AACpG,mHAAmH;AACnH,eAAO,MAAM,aAAa,wDAjBsB,iBAiB6C,CAAC;AAC9F,+HAA+H;AAC/H,eAAO,MAAM,eAAe,0DAnBoB,iBAmBmD,CAAC;AACpG,6HAA6H;AAC7H,eAAO,MAAM,cAAc,yDArBqB,iBAqBgD,CAAC;AACjG,+HAA+H;AAC/H,eAAO,MAAM,aAAa,wDAvBsB,iBAuB6C,CAAC;AAC9F,2HAA2H;AAC3H,eAAO,MAAM,YAAY,uDAzBuB,iBAyB0C,CAAC;AAC3F,0JAA0J;AAC1J,eAAO,MAAM,wBAAwB,mEA3BW,iBA2B8E,CAAC;AAC/H,iJAAiJ;AACjJ,eAAO,MAAM,mBAAmB,8DA7BgB,iBA6B+D,CAAC;AAChH,8HAA8H;AAC9H,eAAO,MAAM,gBAAgB,2DA/BmB,iBA+BsD,CAAC;AACvG,yIAAyI;AACzI,eAAO,MAAM,iBAAiB,4DAjCkB,iBAiCyD,CAAC;AAC1G,gIAAgI;AAChI,eAAO,MAAM,iBAAiB,4DAnCkB,iBAmCyD,CAAC;AAE1G,0IAA0I;AAC1I,eAAO,MAAM,SAAS,GAAI,OAAM,YAAY,CAAC,aAAa,CAAC,GAAG,QAAa,KAAG,iBACnB,CAAC;AAC5D,6IAA6I;AAC7I,eAAO,MAAM,WAAW,GAAI,OAAM,YAAY,CAAC,eAAe,CAAC,GAAG,QAAa,KAAG,iBACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/chant-lexicon-fly",
-  "version": "0.46.0",
+  "version": "0.50.0",
   "type": "module",
   "files": [
     "src/",
@@ -25,6 +25,11 @@
       "types": "./dist/detect.d.ts",
       "default": "./src/detect.ts"
     },
+    "./components": {
+      "development": "./src/components/index.ts",
+      "types": "./dist/components/index.d.ts",
+      "default": "./src/components/index.ts"
+    },
     "./op/activities": {
       "development": "./src/op/activities/index.ts",
       "types": "./dist/op/activities/index.d.ts",
@@ -57,7 +62,7 @@
     "typescript": "^5.9.3"
   },
   "peerDependencies": {
-    "@intentius/chant": "^0.46.0",
+    "@intentius/chant": "^0.50.0",
     "typescript": "^5.9.3"
   },
   "description": "Fly.io Machines lexicon for chant — declarative IaC in TypeScript",

package/src/components/capability-plugin.test.ts

@@ -0,0 +1,30 @@
+import { describe, test, expect } from "vitest";
+import { flyCapabilityPlugin, FLY_VERB_FAMILIES } from "./capability-plugin";
+import { isCapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { readFileSync } from "node:fs";
+
+describe("flyCapabilityPlugin", () => {
+  test("satisfies the CapabilityPlugin contract", () => {
+    expect(isCapabilityPlugin(flyCapabilityPlugin)).toBe(true);
+    expect(flyCapabilityPlugin.capabilities().map((c) => c.kind)).toContain("run-agent");
+  });
+
+  test("the plugin's version is the lexicon package's own, not a literal (#1505)", () => {
+    const { version } = JSON.parse(
+      readFileSync(new URL("../../package.json", import.meta.url), "utf-8"),
+    ) as { version: string };
+    expect(flyCapabilityPlugin.version).toBe(version);
+    expect(flyCapabilityPlugin.version).not.toBe("1.0.0");
+  });
+
+  test("declares run-agent under its own FLY_VERB_FAMILIES, not core's starter set", () => {
+    expect(FLY_VERB_FAMILIES.agentExecution).toEqual(["run-agent"]);
+    expect(flyCapabilityPlugin.families?.()).toEqual(FLY_VERB_FAMILIES);
+  });
+
+  test("the registered capability declares rollbackPolicy \"native\" with a real rollback", () => {
+    const runAgent = flyCapabilityPlugin.capabilities().find((c) => c.kind === "run-agent");
+    expect(runAgent?.rollbackPolicy).toBe("native");
+    expect(typeof runAgent?.rollback).toBe("function");
+  });
+});

package/src/components/capability-plugin.ts

@@ -0,0 +1,36 @@
+/**
+ * `flyCapabilityPlugin` — the fly lexicon's capability plugin (#1942, epic
+ * #1564 phase 2).
+ *
+ * One leaf so far: `run-agent`, the sprite-lifecycle-backed agent-turn verb
+ * (`./run-agent.ts`). Contributed through core's `CapabilityPlugin` contract
+ * the same way aws contributes `cfn-deploy` and helm contributes
+ * `helm-upgrade` (docs/components/cloud-boundary) — a project declaring
+ * `lexicons: ["fly"]` gets `run-agent` registered automatically when it runs
+ * components. Deliberately *not* part of core's always-on starter set
+ * (`packages/core/src/components/starter-plugin.ts`) — `run-agent` opts a
+ * project in via this lexicon the same way every other cloud-shaped leaf
+ * does, rather than shipping to every project by default.
+ */
+import type { Capability } from "@intentius/chant/components/capability";
+import { ownPackageVersion, type CapabilityPlugin } from "@intentius/chant/components/capability-plugin";
+import { flyRunAgentCapability } from "./run-agent";
+
+export const FLY_VERB_FAMILIES = {
+  agentExecution: ["run-agent"],
+} as const;
+
+export const flyCapabilityPlugin: CapabilityPlugin = {
+  name: "fly",
+  // The lexicon package's own version (mirrors aws/helm's #1505 fix — a
+  // getter so the package.json read happens on first access, not at import time).
+  get version(): string {
+    return ownPackageVersion(import.meta.url);
+  },
+  capabilities(): Array<Capability<never, unknown>> {
+    return [flyRunAgentCapability as Capability<never, unknown>];
+  },
+  families(): Record<string, readonly string[]> {
+    return FLY_VERB_FAMILIES;
+  },
+};

package/src/components/index.ts

@@ -0,0 +1,14 @@
+/**
+ * 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";
+export {
+  flyRunAgentCapability,
+  createFlyRunAgentCapability,
+  createFlySpriteActivities,
+  parseSpriteExecFailure,
+} from "./run-agent";