@intentius/chant-lexicon-fly 0.49.0 → 0.50.0

package/src/components/run-agent.ts

@@ -0,0 +1,139 @@
+/**
+ * `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 {
+  createRunAgentCapability,
+  type RunAgentInput,
+  type RunAgentOutput,
+  type SpriteActivities,
+} from "@intentius/chant/components/verbs/run-agent";
+import { spriteCreate, spriteCheckpoint, spriteExec, spriteRestore, spriteDestroy } from "../op/activities/sprites";
+import { spriteWriteFile, spriteReadFile } from "../op/activities/sprite-fs";
+
+/**
+ * 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: unknown): { exitCode: number; output: string } | undefined {
+  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(): SpriteActivities {
+  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(): Capability<RunAgentInput, RunAgentOutput> {
+  return createRunAgentCapability(createFlySpriteActivities());
+}
+
+/** Default `run-agent` capability, backed by the real `SpriteActivities` adapter above — what `flyCapabilityPlugin` (./capability-plugin.ts) registers. */
+export const flyRunAgentCapability: Capability<RunAgentInput, RunAgentOutput> = createFlyRunAgentCapability();

package/src/composites/fly-deploy.ts

@@ -25,7 +25,7 @@
 
 import { Op, phase, build, activity, httpCheck } from "@intentius/chant/op";
 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 const LOCAL_FLAPS_ENDPOINT = "http://localhost:4280";
@@ -52,13 +52,13 @@ export interface FlapsStepOpts {
  * `flapsUp` activity (#740). Defaults to the `longInfra` profile (the image may
  * pull); override via `opts.profile`.
  */
-export const flapsUp = (opts?: FlapsStepOpts): ActivityStep => {
+export const flapsUp = (opts?: FlapsStepOpts): NamedActivityStep => {
   const { profile, ...args } = opts ?? {};
   return activity("flapsUp", args as Record<string, unknown>, profile ?? "longInfra");
 };
 
 /** Stop and remove the local mudflaps container. Resolves to the `flapsDown` activity. Defaults to the `fastIdempotent` profile (override via `opts.profile`). */
-export const flapsDown = (opts?: FlapsStepOpts): ActivityStep => {
+export const flapsDown = (opts?: FlapsStepOpts): NamedActivityStep => {
   const { profile, ...args } = opts ?? {};
   return activity("flapsDown", args as Record<string, unknown>, profile ?? "fastIdempotent");
 };
@@ -83,7 +83,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 const flyApplyStep = (planPath: string, opts?: FlyApplyStepOpts): ActivityStep => {
+export const flyApplyStep = (planPath: string, opts?: FlyApplyStepOpts): NamedActivityStep => {
   const { profile, ...rest } = opts ?? {};
   return activity("flyApply", { planPath, ...(rest as Record<string, unknown>) }, profile ?? "longInfra");
 };

package/src/index.ts

@@ -1,6 +1,11 @@
 // Plugin
 export { flyPlugin } from "./plugin";
 
+// Component/release capabilities — run-agent, the sprite-lifecycle leaf
+// contributed to core's capability-plugin seam (#1942). Core loads
+// `flyCapabilityPlugin` when a project's chant.config lists this lexicon.
+export { flyCapabilityPlugin, FLY_VERB_FAMILIES } from "./components/capability-plugin";
+
 // Serializer
 export { flySerializer } from "./serializer";
 
@@ -17,10 +22,16 @@ export { FLY_METADATA_OWNERSHIP_KEYS } from "./ownership";
 export { flyDeploy, flapsUp, flapsDown, flyApplyStep, LOCAL_FLAPS_ENDPOINT } from "./composites/fly-deploy";
 export type { FlyDeployOpts, FlyApplyStepOpts, FlapsStepOpts } from "./composites/fly-deploy";
 
-// Sprite Op step builders (re-exported from core for single-import convenience).
-// These author `activity("spriteCreate", ...)` steps; `loadActivities(["fly"])`
-// binds them to the implementations in ./op/activities/sprites.ts. The `spritesUp`
-// /`spritesDown` builders boot/tear down the spritzer emulator as modeled steps.
+// Sprite Op step builders. chant #1288 Stage 2: these author
+// `activity("spriteCreate", ...)` steps with authoring-time types derived
+// from this lexicon's own `Sprite*Args` interfaces (`./op/builders.ts`),
+// replacing the hand-restated inline types core's same-named builders used
+// to carry — same names, same import path, so an existing
+// `import { spriteCreate } from "@intentius/chant-lexicon-fly"` call site
+// gains real derived types with no change. `loadActivities(["fly"])` binds
+// the `fn` strings to the implementations in `./op/activities/sprites.ts`
+// etc. The `spritesUp`/`spritesDown` builders boot/tear down the spritzer
+// emulator as modeled steps.
 export {
   spriteCreate,
   spriteExec,
@@ -39,7 +50,7 @@ export {
   spriteTaskRelease,
   spritesUp,
   spritesDown,
-} from "@intentius/chant/op";
+} from "./op/builders";
 
 // Generated resources — export everything from generated index.
 // Provides `App`, `Machine`, `Volume`, and the property types

package/src/op/builders.test.ts

@@ -0,0 +1,73 @@
+/**
+ * Typed step-builder wrappers (chant #1288 Stage 2) — see
+ * `lexicons/k8s/src/op/builders.test.ts`'s module doc for what's asserted
+ * and why. Unlike the positional-arg lexicons, the sprite family takes one
+ * whole args object (matching core's original inline-typed signature), so
+ * only `profile` is extracted from that object — `id` is left alone
+ * (verified below): it's a required DOMAIN field on most of these (the
+ * target sprite), not step-authoring sugar, so `.out`-by-id is out of scope
+ * here (see `./builders.ts`'s module doc).
+ */
+
+import { describe, test, expect } from "vitest";
+import {
+  spriteCreate as spriteCreateOld,
+  spriteExec as spriteExecOld,
+  spriteWriteFile as spriteWriteFileOld,
+  spritesUp as spritesUpOld,
+  spritesDown as spritesDownOld,
+  stepOutput,
+} from "@intentius/chant/op";
+import { spriteCreate, spriteExec, spriteWriteFile, spritesUp, spritesDown } from "./builders";
+
+describe("fly typed sprite step builders (#1288 Stage 2)", () => {
+  test("spriteCreate: identical ActivityStep to core's original", () => {
+    expect(spriteCreate({ name: "sandbox" })).toEqual(spriteCreateOld({ name: "sandbox" }));
+    const args = { name: "sandbox", image: "custom:latest", size: "shared-cpu-1x" };
+    expect(spriteCreate(args)).toEqual(spriteCreateOld(args));
+  });
+
+  test("spriteExec: identical ActivityStep to core's original", () => {
+    const args = { id: "sandbox", cmd: "npm test", timeoutMs: 60_000 };
+    expect(spriteExec(args)).toEqual(spriteExecOld(args));
+  });
+
+  test("spriteWriteFile: identical ActivityStep to core's original", () => {
+    const args = { id: "sandbox", path: "/app/config.json", content: "{}" };
+    expect(spriteWriteFile(args)).toEqual(spriteWriteFileOld(args));
+  });
+
+  test("spritesUp/spritesDown: identical ActivityStep to core's original, including the no-arg default", () => {
+    expect(spritesUp()).toEqual(spritesUpOld());
+    expect(spritesUp({ port: 4291 })).toEqual(spritesUpOld({ port: 4291 }));
+    expect(spritesDown()).toEqual(spritesDownOld());
+  });
+
+  test("spriteCreate: accepts a StepOutputRef in a typed slot", () => {
+    const ref = stepOutput("resolve-image", "image");
+    const step = spriteCreate({ name: "sandbox", image: ref });
+    expect(step.args?.image).toBe(ref);
+  });
+
+  test("spriteExec: `id` (the target sprite, a domain field) lands in args, not the step's own id", () => {
+    const step = spriteExec({ id: "sandbox", cmd: "npm test" });
+    expect(step.args?.id).toBe("sandbox");
+    expect(step.id).toBeUndefined();
+  });
+});
+
+// ── Compile-time-only: authoring-time type errors (never executed) ──────────
+function _typeChecksOnly(): void {
+  // @ts-expect-error — name is required (the activity fails without it).
+  spriteCreate({});
+
+  // @ts-expect-error — "sandbox_id" is not a key of SpriteExecArgs (the field is `id`).
+  spriteExec({ sandbox_id: "sandbox", cmd: "npm test" });
+
+  // @ts-expect-error — timeoutMs must be a number.
+  spriteExec({ id: "sandbox", cmd: "npm test", timeoutMs: "60000" });
+
+  // @ts-expect-error — spritesUp's port must be a number.
+  spritesUp({ port: "4290" });
+}
+void _typeChecksOnly;

package/src/op/builders.ts

@@ -0,0 +1,102 @@
+/**
+ * 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 { activity, 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";
+import type { SpriteWriteFileArgs, SpriteReadFileArgs, SpriteListDirArgs, SpriteRemoveArgs } from "./activities/sprite-fs";
+import type { SpriteApplyNetworkPolicyArgs, SpriteApplyServicesArgs } from "./activities/sprite-config";
+import type { SpriteTaskCreateArgs, SpriteTaskRefreshArgs, SpriteTaskReleaseArgs } from "./activities/sprite-tasks";
+import type { SpritesUpArgs, SpritesDownArgs } from "./activities/sprites-emulator";
+
+type StepOpts = { profile?: ActivityStep["profile"] };
+
+/**
+ * Build one whole-args typed sprite step builder — `args` IS the activity's
+ * own `*Args` type, `profile` routed off it, never restated. Only `profile`
+ * is extracted, deliberately NOT a step-authoring `id` the way the other
+ * lexicons' wrappers offer: `id` is itself a REQUIRED domain field on nearly
+ * every `Sprite*Args` here (the target sprite's id — `spriteExec`,
+ * `spriteWriteFile`, `spriteTaskCreate`, ...), so stripping an `id` key off
+ * the flat args object the way `takeProfileAndId` does elsewhere would
+ * silently steal the sprite id into the step's `id` and drop it from `args`
+ * — the exact silent-wrong-value failure class chant #1288 exists to catch,
+ * not reproduce. `.out`-by-id (#1290) is out of scope for the sprite family
+ * through this convenience layer, exactly as it was through core's original
+ * builders; an author who needs it authors `activity("spriteExec", args, {
+ * id: "..." })` directly. `Args` is deliberately unconstrained: a named
+ * interface without an explicit index signature (every `Sprite*Args` here)
+ * is not assignable to `Record<string, unknown>` structurally, even though
+ * every field it does declare is — the `as Record<string, unknown>` cast
+ * below is a type ASSERTION (permissive), not an assignment, so it doesn't
+ * need the constraint.
+ */
+function spriteStep<Args>(fn: string, defaultProfile: NonNullable<ActivityStep["profile"]>) {
+  return (args: WithStepRefs<Args> & StepOpts): NamedActivityStep => {
+    const { profile, ...rest } = args as { profile?: ActivityStep["profile"] } & Record<string, unknown>;
+    return activity(fn, rest, profile ?? defaultProfile);
+  };
+}
+
+/** Create a sprite — the fully typed twin of core's `spriteCreate`. Defaults to the `longInfra` profile. */
+export const spriteCreate = spriteStep<SpriteCreateArgs>("spriteCreate", "longInfra");
+/** Run a command in a sprite — the fully typed twin of core's `spriteExec`. Defaults to the `longInfra` profile. */
+export const spriteExec = spriteStep<SpriteExecArgs>("spriteExec", "longInfra");
+/** Checkpoint a sprite — the fully typed twin of core's `spriteCheckpoint`. Defaults to the `longInfra` profile. */
+export const spriteCheckpoint = spriteStep<SpriteCheckpointArgs>("spriteCheckpoint", "longInfra");
+/** Restore a sprite — the fully typed twin of core's `spriteRestore`. Defaults to the `longInfra` profile. */
+export const spriteRestore = spriteStep<SpriteRestoreArgs>("spriteRestore", "longInfra");
+/** List a sprite's checkpoints — the fully typed twin of core's `listCheckpoints`. Defaults to the `fastIdempotent` profile. */
+export const listCheckpoints = spriteStep<ListCheckpointsArgs>("listCheckpoints", "fastIdempotent");
+/** Destroy a sprite — the fully typed twin of core's `spriteDestroy`. Defaults to the `fastIdempotent` profile. */
+export const spriteDestroy = spriteStep<SpriteDestroyArgs>("spriteDestroy", "fastIdempotent");
+/** Write a file into a sprite — the fully typed twin of core's `spriteWriteFile`. Defaults to the `fastIdempotent` profile. */
+export const spriteWriteFile = spriteStep<SpriteWriteFileArgs>("spriteWriteFile", "fastIdempotent");
+/** Read a file from a sprite — the fully typed twin of core's `spriteReadFile`. Defaults to the `fastIdempotent` profile. */
+export const spriteReadFile = spriteStep<SpriteReadFileArgs>("spriteReadFile", "fastIdempotent");
+/** List a directory in a sprite — the fully typed twin of core's `spriteListDir`. Defaults to the `fastIdempotent` profile. */
+export const spriteListDir = spriteStep<SpriteListDirArgs>("spriteListDir", "fastIdempotent");
+/** Remove a path in a sprite — the fully typed twin of core's `spriteRemove`. Defaults to the `fastIdempotent` profile. */
+export const spriteRemove = spriteStep<SpriteRemoveArgs>("spriteRemove", "fastIdempotent");
+/** Reconcile a sprite's outbound network policy — the fully typed twin of core's `spriteApplyNetworkPolicy`. Defaults to the `fastIdempotent` profile. */
+export const spriteApplyNetworkPolicy = spriteStep<SpriteApplyNetworkPolicyArgs>("spriteApplyNetworkPolicy", "fastIdempotent");
+/** Reconcile a sprite's background services — the fully typed twin of core's `spriteApplyServices`. Defaults to the `fastIdempotent` profile. */
+export const spriteApplyServices = spriteStep<SpriteApplyServicesArgs>("spriteApplyServices", "fastIdempotent");
+/** Create a keep-alive task — the fully typed twin of core's `spriteTaskCreate`. Defaults to the `fastIdempotent` profile. */
+export const spriteTaskCreate = spriteStep<SpriteTaskCreateArgs>("spriteTaskCreate", "fastIdempotent");
+/** Refresh a keep-alive task's expiry — the fully typed twin of core's `spriteTaskRefresh`. Defaults to the `fastIdempotent` profile. */
+export const spriteTaskRefresh = spriteStep<SpriteTaskRefreshArgs>("spriteTaskRefresh", "fastIdempotent");
+/** Release a keep-alive task — the fully typed twin of core's `spriteTaskRelease`. Defaults to the `fastIdempotent` profile. */
+export const spriteTaskRelease = spriteStep<SpriteTaskReleaseArgs>("spriteTaskRelease", "fastIdempotent");
+
+/** Boot a local spritzer (Fly Sprites API emulator) — the fully typed twin of core's `spritesUp`. Defaults to the `longInfra` profile. */
+export const spritesUp = (args: WithStepRefs<SpritesUpArgs> & StepOpts = {}): NamedActivityStep =>
+  spriteStep<SpritesUpArgs>("spritesUp", "longInfra")(args);
+/** Stop and remove the local spritzer container — the fully typed twin of core's `spritesDown`. Defaults to the `fastIdempotent` profile. */
+export const spritesDown = (args: WithStepRefs<SpritesDownArgs> & StepOpts = {}): NamedActivityStep =>
+  spriteStep<SpritesDownArgs>("spritesDown", "fastIdempotent")(args);