@intentius/chant-lexicon-fly 0.17.0 → 0.18.1

package/src/op/activities/sprites.ts

@@ -0,0 +1,527 @@
+/**
+ * Sprites lifecycle activities (#762, #766) — imperative, checkpointable sandbox
+ * primitives ([sprites.dev](https://sprites.dev)) as chant Op activities, wired
+ * to the faithful Sprites API.
+ *
+ * Unlike a resource lexicon, Sprites have no desired state to reconcile: they
+ * are runtime-orchestration primitives (the same category as `k3dUp` /
+ * `httpCheck`). Most activities are a direct call over an injectable HTTP client
+ * (`SpritesHttp`); `spriteExec` is the exception — it speaks the control
+ * WebSocket exec protocol (non-PTY stream framing, per superfly/sprites-go), so
+ * it opens a `ws` connection instead. Exported pure helpers (endpoint
+ * resolution, the exec frame accumulator, NDJSON parsers, the comment picker)
+ * keep the logic unit-testable without a socket or an HTTP server.
+ *
+ * The headline capability is checkpoint-as-compensation (S5): an Op checkpoints
+ * before a risky phase and, on failure, `spriteRestore`s the labeled checkpoint
+ * instead of unwinding with an inverse action — the environment itself is the
+ * transaction.
+ *
+ * S3: endpoint override via `SPRITES_BASE_URL` (an explicit `endpoint` arg wins,
+ * then the env, then the real Sprites base), so the same Op targets real Sprites
+ * or the in-process fake with no code change.
+ */
+
+import WebSocket from "ws";
+
+export const DEFAULT_SPRITES_BASE_URL = "https://api.sprites.dev";
+
+// ── Pure helpers (unit-testable without http/ws) ──────────────────────────────
+
+/**
+ * Resolve the Sprites base URL (S3): an explicit `endpoint` arg wins, then the
+ * `SPRITES_BASE_URL` env, then the real-Sprites default. The trailing slash is
+ * stripped so `${base}/v1/...` never doubles up. Pure — mirrors fly's
+ * `resolveEndpoint`.
+ */
+export function resolveSpritesEndpoint(
+  args: { endpoint?: string } = {},
+  env: NodeJS.ProcessEnv = process.env,
+): string {
+  const base = args.endpoint || env.SPRITES_BASE_URL || DEFAULT_SPRITES_BASE_URL;
+  return base.replace(/\/$/, "");
+}
+
+const spritesUrl = (base: string): string => `${base}/v1/sprites`;
+const spriteUrl = (base: string, id: string): string => `${spritesUrl(base)}/${encodeURIComponent(id)}`;
+// Create uses REST JSON; exec is the control WebSocket below; checkpoints are NDJSON.
+const spriteCheckpointUrl = (base: string, id: string): string => `${spriteUrl(base, id)}/checkpoint`;
+const spriteCheckpointsUrl = (base: string, id: string): string => `${spriteUrl(base, id)}/checkpoints`;
+const spriteCheckpointRestoreUrl = (base: string, id: string, cp: string): string =>
+  `${spriteCheckpointsUrl(base, id)}/${encodeURIComponent(cp)}/restore`;
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Exec stream framing (non-PTY control WebSocket) ────────────────────────────
+//
+// Every WebSocket message is a binary frame `[StreamID:1 byte][payload]`. The
+// client with no stdin sends a single `[4]` (StreamStdinEOF); the server writes
+// stdout as `[1]<bytes>`, stderr as `[2]<bytes>`, then `[3]<exitcodebyte>` and
+// closes. See superfly/sprites-go websocket.go/exec.go.
+export const STREAM_STDIN = 0;
+export const STREAM_STDOUT = 1;
+export const STREAM_STDERR = 2;
+export const STREAM_EXIT = 3;
+export const STREAM_STDIN_EOF = 4;
+
+function toBytes(data: unknown): Uint8Array {
+  if (data instanceof Uint8Array) return data;
+  if (data instanceof ArrayBuffer) return new Uint8Array(data);
+  if (Array.isArray(data)) return Buffer.concat(data.map((d) => toBytes(d) as Buffer));
+  if (typeof data === "string") return new TextEncoder().encode(data);
+  return new Uint8Array(0);
+}
+
+/**
+ * Accumulate a stream of exec frames into `{ stdout, stderr, exitCode }`. Pure
+ * and socket-free so the framing is unit-testable: feed `[1]"hi\n"`, `[3]\x00`
+ * and get `{ stdout: "hi\n", exitCode: 0 }`. Per-stream payloads are collected
+ * as bytes and decoded once, so a multi-byte character split across frames is
+ * preserved. The exit code is the first byte of the `[3]` frame (0 when absent).
+ */
+export function accumulateExecFrames(frames: Iterable<Uint8Array>): SpriteExecResult {
+  const outChunks: Uint8Array[] = [];
+  const errChunks: Uint8Array[] = [];
+  let exitCode = 0;
+  for (const frame of frames) {
+    if (!frame || frame.length === 0) continue;
+    const stream = frame[0];
+    const payload = frame.subarray(1);
+    if (stream === STREAM_STDOUT) outChunks.push(payload);
+    else if (stream === STREAM_STDERR) errChunks.push(payload);
+    else if (stream === STREAM_EXIT) exitCode = payload.length > 0 ? payload[0] : 0;
+  }
+  const dec = new TextDecoder();
+  return {
+    stdout: dec.decode(concat(outChunks)),
+    stderr: dec.decode(concat(errChunks)),
+    exitCode,
+  };
+}
+
+function concat(chunks: Uint8Array[]): Uint8Array {
+  if (chunks.length === 0) return new Uint8Array(0);
+  if (chunks.length === 1) return chunks[0];
+  return Buffer.concat(chunks.map((c) => Buffer.from(c.buffer, c.byteOffset, c.byteLength)));
+}
+
+/**
+ * Tokenize a command string into an argv, respecting single/double quotes so
+ * `sh -c "exit 7"` becomes `["sh", "-c", "exit 7"]`. Each element is sent as a
+ * `cmd` query param; `path` is `argv[0]`. Pure.
+ */
+export function splitCommand(cmd: string): string[] {
+  const argv: string[] = [];
+  let cur = "";
+  let has = false;
+  let inSingle = false;
+  let inDouble = false;
+  for (const ch of cmd) {
+    if (inSingle) {
+      if (ch === "'") inSingle = false;
+      else cur += ch;
+      continue;
+    }
+    if (inDouble) {
+      if (ch === '"') inDouble = false;
+      else cur += ch;
+      continue;
+    }
+    if (ch === "'") {
+      inSingle = true;
+      has = true;
+    } else if (ch === '"') {
+      inDouble = true;
+      has = true;
+    } else if (ch === " " || ch === "\t" || ch === "\n") {
+      if (has) {
+        argv.push(cur);
+        cur = "";
+        has = false;
+      }
+    } else {
+      cur += ch;
+      has = true;
+    }
+  }
+  if (has) argv.push(cur);
+  return argv;
+}
+
+/**
+ * Build the `wss://.../exec?cmd=...&path=...&stdin=false&cc=true` URL for a
+ * command (http→ws, https→wss). Pure.
+ */
+export function spriteExecWsUrl(base: string, id: string, cmd: string): string {
+  const wsBase = base.replace(/^http(s?):\/\//i, (_m, s: string) => `ws${s}://`);
+  const argv = splitCommand(cmd);
+  const params = new URLSearchParams();
+  for (const a of argv) params.append("cmd", a);
+  params.set("path", argv[0] ?? "");
+  params.set("stdin", "false");
+  params.set("cc", "true");
+  return `${wsBase}/v1/sprites/${encodeURIComponent(id)}/exec?${params.toString()}`;
+}
+
+// ── Checkpoint NDJSON + comment picker ─────────────────────────────────────────
+
+/**
+ * Parse a checkpoint create NDJSON body (line-delimited JSON progress events)
+ * and capture the created version id. Real Sprites tags each event with a
+ * `type` and a human `data` string — the version id rides inside the text
+ * ("  ID: v1" and "Checkpoint v1 created successfully"), not a structured
+ * field. The in-process fake mirrors that. An older shape (`{event, id}`) is
+ * still honored so a structured id always wins. Pure; blank/unparseable lines
+ * are skipped; `checkpointId` is "" when the stream carries no id.
+ */
+export function parseCheckpointNdjson(text: string): SpriteCheckpointResult {
+  let structuredId = "";
+  let textId = "";
+  for (const line of text.split("\n")) {
+    const t = line.trim();
+    if (!t) continue;
+    const obj = safeJson(t) as
+      | { event?: string; type?: string; id?: string; data?: string }
+      | undefined;
+    if (!obj) continue;
+    const kind = obj.event ?? obj.type;
+    // Structured id (older emulator shape) — always preferred when present.
+    if (kind === "complete" && typeof obj.id === "string" && obj.id) structuredId = obj.id;
+    // Otherwise mine the version id out of the message text. The "  ID: v1"
+    // detail line and the "Checkpoint v1 created successfully" completion line
+    // both carry it; either is enough.
+    if (typeof obj.data === "string") {
+      const fromId = obj.data.match(/(?:^|\s)ID:\s*(\S+)/);
+      if (fromId) textId = fromId[1];
+      const fromComplete = obj.data.match(/Checkpoint\s+(\S+)\s+created/i);
+      if (fromComplete) textId = fromComplete[1];
+    }
+  }
+  return { checkpointId: structuredId || textId };
+}
+
+/**
+ * Pick the newest checkpoint whose `comment` matches, so a comment-tagged
+ * restore rewinds to the most recent labeled snapshot. Newest is by
+ * `create_time`; array order breaks ties (the list is chronological). Pure.
+ */
+export function pickCheckpointByComment(list: Checkpoint[], comment: string): Checkpoint | undefined {
+  return newestOf(list.filter((c) => c.comment === comment));
+}
+
+function newestOf(list: Checkpoint[]): Checkpoint | undefined {
+  let best: Checkpoint | undefined;
+  for (const c of list) {
+    if (!best || compareCreateTime(c, best) >= 0) best = c;
+  }
+  return best;
+}
+
+function compareCreateTime(a: Checkpoint, b: Checkpoint): number {
+  const ta = Date.parse(a.create_time);
+  const tb = Date.parse(b.create_time);
+  if (Number.isNaN(ta) || Number.isNaN(tb)) return 0;
+  return ta - tb;
+}
+
+// ── Activity contracts (the stable interface the Ops/emulator target) ──────────
+
+export interface SpriteCreateArgs {
+  /** Caller-chosen name, used as the sprite `id` (S4). Every later activity keys on it. */
+  name: string;
+  /** Base image for the sandbox. */
+  image?: string;
+  /** Sandbox size (vCPU/memory class). */
+  size?: string;
+  /** Network / execution policy passed through to the sprite. */
+  policy?: unknown;
+  /** Endpoint override (S3). Default: `SPRITES_BASE_URL`, else real Sprites. */
+  endpoint?: string;
+  /** Bearer token. Default: `SPRITES_API_TOKEN`. The fake ignores it. */
+  token?: string;
+}
+
+export interface SpriteCreateResult {
+  id: string;
+  url: string;
+}
+
+export interface SpriteExecArgs {
+  /** Target sprite id (the `name` passed to `spriteCreate`). */
+  id: string;
+  /** Command to run inside the sprite (tokenized into argv, quotes respected). */
+  cmd: string;
+  /** Per-exec timeout in ms. */
+  timeoutMs?: number;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+export interface SpriteCheckpointArgs {
+  id: string;
+  /** Caller-chosen checkpoint comment (S4); a comment-tagged `spriteRestore` matches it. */
+  comment?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteCheckpointResult {
+  /** The server checkpoint version (e.g. `v3`) captured from the `complete` event. */
+  checkpointId: string;
+}
+
+export interface Checkpoint {
+  id: string;
+  comment: string;
+  create_time: string;
+  is_auto: boolean;
+}
+
+export interface SpriteRestoreArgs {
+  id: string;
+  /** Explicit checkpoint id (e.g. `v3`); wins over `comment`. */
+  checkpoint?: string;
+  /** Restore the newest checkpoint carrying this comment. */
+  comment?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface ListCheckpointsArgs {
+  id: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteDestroyArgs {
+  id: string;
+  endpoint?: string;
+  token?: string;
+}
+
+/** Build the `POST /v1/sprites` body. Pure. */
+export function spriteCreateBody(args: SpriteCreateArgs): Record<string, unknown> {
+  return {
+    name: args.name,
+    ...(args.image !== undefined ? { image: args.image } : {}),
+    ...(args.size !== undefined ? { size: args.size } : {}),
+    ...(args.policy !== undefined ? { policy: args.policy } : {}),
+  };
+}
+
+/** Parse the create response; the caller-chosen `name` is the id fallback (S4). Pure. */
+export function parseCreateResponse(text: string, name: string): SpriteCreateResult {
+  const b = safeJson(text) as { id?: string; url?: string } | undefined;
+  return { id: b?.id ?? name, url: b?.url ?? "" };
+}
+
+// ── HTTP ───────────────────────────────────────────────────────────────────────
+
+/**
+ * Injectable HTTP client — mirrors fly's `FlyHttp`. Tests inject a fake; the
+ * default hits `fetch`. Used by create/destroy/checkpoint/list/restore; exec
+ * goes over the control WebSocket instead.
+ */
+export type SpritesHttp = (
+  method: string,
+  url: string,
+  body?: unknown,
+  headers?: Record<string, string>,
+  signal?: AbortSignal,
+) => Promise<{ status: number; text: string }>;
+
+/**
+ * Default `fetch`-based client. Sends `Authorization: Bearer <token>` when a
+ * token is set (real Sprites); the fake ignores it. The token defaults to
+ * `SPRITES_API_TOKEN` at call time. `fetchImpl` is injectable for tests.
+ */
+export function defaultSpritesHttp(token?: string, fetchImpl: typeof fetch = fetch): SpritesHttp {
+  return async (method, url, body, headers, signal) => {
+    const h: Record<string, string> = { ...headers };
+    if (body !== undefined) h["content-type"] = "application/json";
+    const tok = token ?? process.env.SPRITES_API_TOKEN;
+    if (tok) h["authorization"] = `Bearer ${tok}`;
+    const res = await fetchImpl(url, {
+      method,
+      headers: Object.keys(h).length ? h : undefined,
+      body: body === undefined ? undefined : JSON.stringify(body),
+      signal,
+    });
+    return { status: res.status, text: await res.text() };
+  };
+}
+
+// ── Activities (ActivityFn: (args, signal?) => Promise<unknown>) ──────────────
+
+/** Create a sprite with the caller-chosen `name` as its id (S4). `POST /v1/sprites`. */
+export async function spriteCreate(
+  args: SpriteCreateArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteCreateResult> {
+  const base = resolveSpritesEndpoint(args);
+  const res = await http("POST", spritesUrl(base), spriteCreateBody(args), undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.name} create failed (${res.status}): ${res.text}`);
+  const result = parseCreateResponse(res.text, args.name);
+  console.log(`created: sprite/${result.id} (${base})`);
+  return result;
+}
+
+/**
+ * Run a command in the sprite over the control WebSocket (non-PTY stream
+ * framing, per superfly/sprites-go). Connects to `wss://.../exec`, sends a
+ * single `[4]` (stdin EOF), accumulates stdout/stderr frames, and reads the
+ * exit code from the `[3]` frame. A non-zero exit is a failed activity (it
+ * throws) so a risky step fails its phase and triggers `onFailure`
+ * compensation (S5).
+ */
+export async function spriteExec(args: SpriteExecArgs, signal?: AbortSignal): Promise<SpriteExecResult> {
+  const base = resolveSpritesEndpoint(args);
+  const url = spriteExecWsUrl(base, args.id, args.cmd);
+  const token = args.token ?? process.env.SPRITES_API_TOKEN;
+  const headers: Record<string, string> = {};
+  if (token) headers.Authorization = `Bearer ${token}`;
+
+  const result = await new Promise<SpriteExecResult>((resolve, reject) => {
+    const frames: Uint8Array[] = [];
+    const ws = new WebSocket(url, { headers });
+    let settled = false;
+    const finish = (fn: () => void): void => {
+      if (settled) return;
+      settled = true;
+      if (signal) signal.removeEventListener("abort", onAbort);
+      fn();
+    };
+    const onAbort = (): void => {
+      try {
+        ws.terminate();
+      } catch {
+        /* already closed */
+      }
+      finish(() => reject(new Error(`sprite ${args.id} exec aborted`)));
+    };
+    if (signal) {
+      if (signal.aborted) return onAbort();
+      signal.addEventListener("abort", onAbort);
+    }
+    ws.on("open", () => {
+      // No stdin: signal EOF immediately (belt and braces with stdin=false).
+      ws.send(Uint8Array.of(STREAM_STDIN_EOF));
+    });
+    ws.on("message", (data) => {
+      const bytes = toBytes(data);
+      frames.push(bytes);
+      if (bytes.length > 0 && bytes[0] === STREAM_EXIT) {
+        try {
+          ws.close();
+        } catch {
+          /* closing already */
+        }
+      }
+    });
+    ws.on("error", (err) => finish(() => reject(err)));
+    ws.on("close", () => finish(() => resolve(accumulateExecFrames(frames))));
+  });
+
+  if (result.exitCode !== 0) {
+    throw new Error(
+      `sprite ${args.id} exec "${args.cmd}" exited ${result.exitCode}: ${result.stderr || result.stdout}`,
+    );
+  }
+  return result;
+}
+
+/**
+ * Checkpoint the sprite. `POST /v1/sprites/{id}/checkpoint` (singular); the
+ * `comment` key is omitted when empty. The response is an NDJSON progress
+ * stream; the created version id is mined from the message text (see
+ * `parseCheckpointNdjson`).
+ */
+export async function spriteCheckpoint(
+  args: SpriteCheckpointArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteCheckpointResult> {
+  const base = resolveSpritesEndpoint(args);
+  const body = args.comment ? { comment: args.comment } : undefined;
+  const res = await http("POST", spriteCheckpointUrl(base, args.id), body, undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} checkpoint failed (${res.status}): ${res.text}`);
+  const result = parseCheckpointNdjson(res.text);
+  console.log(`checkpoint: sprite/${args.id} @${result.checkpointId} (${base})`);
+  return result;
+}
+
+/**
+ * List a sprite's checkpoints. `GET /v1/sprites/{id}/checkpoints` → a bare array
+ * `[{ id, comment, create_time, is_auto }]` (auto checkpoints excluded by
+ * default on the server).
+ */
+export async function listCheckpoints(
+  args: ListCheckpointsArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<Checkpoint[]> {
+  const base = resolveSpritesEndpoint(args);
+  const res = await http("GET", spriteCheckpointsUrl(base, args.id), undefined, undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} list checkpoints failed (${res.status}): ${res.text}`);
+  const parsed = safeJson(res.text);
+  return Array.isArray(parsed) ? (parsed as Checkpoint[]) : [];
+}
+
+/**
+ * Restore the sprite to a checkpoint (S5, the compensation path). Resolution
+ * order: an explicit `checkpoint` id wins; otherwise the newest checkpoint
+ * carrying `comment`; otherwise the newest checkpoint overall. Restore is
+ * `POST /v1/sprites/{id}/checkpoints/{cp}/restore` and returns an NDJSON stream.
+ */
+export async function spriteRestore(
+  args: SpriteRestoreArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<Record<string, never>> {
+  const base = resolveSpritesEndpoint(args);
+  let target = args.checkpoint;
+  if (!target) {
+    const list = await listCheckpoints({ ...args }, signal, http);
+    const picked =
+      args.comment !== undefined ? pickCheckpointByComment(list, args.comment) : newestOf(list);
+    if (!picked) {
+      const which = args.comment !== undefined ? `comment "${args.comment}"` : "any checkpoint";
+      throw new Error(`sprite ${args.id} restore: no checkpoint matching ${which}`);
+    }
+    target = picked.id;
+  }
+  const res = await http("POST", spriteCheckpointRestoreUrl(base, args.id, target), undefined, undefined, signal);
+  if (res.status >= 300) {
+    throw new Error(`sprite ${args.id} restore to "${target}" failed (${res.status}): ${res.text}`);
+  }
+  console.log(`restored: sprite/${args.id} to ${target} (${base})`);
+  return {};
+}
+
+/** Destroy the sprite (idempotent; a 404 means it is already gone). `DELETE /v1/sprites/{id}`. */
+export async function spriteDestroy(
+  args: SpriteDestroyArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<Record<string, never>> {
+  const base = resolveSpritesEndpoint(args);
+  const res = await http("DELETE", spriteUrl(base, args.id), undefined, undefined, signal);
+  if (res.status >= 300 && res.status !== 404) {
+    throw new Error(`sprite ${args.id} destroy failed (${res.status}): ${res.text}`);
+  }
+  console.log(`destroyed: sprite/${args.id} (${base})`);
+  return {};
+}

package/src/plugin.ts

@@ -133,6 +133,19 @@ export const flyPlugin: LexiconPlugin = {
         },
       ],
     },
+    {
+      file: "chant-fly-sprites.md",
+      name: "chant-fly-sprites",
+      description: "Run an agent task in a Sprite as a chant Op — create, exec, checkpoint, restore, destroy, with checkpoint-as-compensation",
+      triggers: [
+        { type: "context" as const, value: "sprite" },
+        { type: "context" as const, value: "sprites.dev" },
+        { type: "context" as const, value: "agent sandbox" },
+        { type: "context" as const, value: "checkpoint compensation" },
+      ],
+      parameters: [],
+      examples: [],
+    },
   ]),
 
   mcpTools() {

package/src/skills/chant-fly-sprites.md

@@ -0,0 +1,104 @@
+---
+skill: chant-temporal-sprites
+description: Run an agent task in a Sprite as a chant Op — create, exec, checkpoint, restore, and destroy, with checkpoint-as-compensation
+user-invocable: true
+---
+
+# Run an Agent Task in a Sprite
+
+[Sprites](https://sprites.dev) are stateful, checkpointable sandboxes. Unlike a resource lexicon, a Sprite has no desired state to reconcile: it is a runtime-orchestration primitive, the same category as `k3dUp` or `httpCheck`. So the sprite lifecycle lives in chant's Op and activity layer, not in a declarative resource type.
+
+This is the direct-API, Op-driven way to drive a Sprite: a structured, replayable activity sequence that a chant Op can checkpoint and roll back. It sits alongside the Sprites SDKs and CLI rather than replacing them, and it is not an MCP wrapper.
+
+## The five activities
+
+Each activity is a direct REST call over an injectable HTTP client, imported from `@intentius/chant-lexicon-fly` (Sprites are a Fly product, so they live in the fly lexicon alongside Machines):
+
+| Activity | What it does |
+|----------|--------------|
+| `spriteCreate` | Create a sandbox. The caller-chosen `name` becomes the sprite `id` that every later activity keys on |
+| `spriteExec` | Run a command inside the sprite. A non-zero exit throws, so the phase fails and any `onFailure` compensation runs |
+| `spriteCheckpoint` | Snapshot the sprite under a caller-chosen `label` |
+| `spriteRestore` | Rewind the sprite to a labeled checkpoint |
+| `spriteDestroy` | Destroy the sprite (idempotent; an already-gone sprite is a no-op) |
+
+The sprite `id` and the checkpoint `label` are static strings the Op author writes, so nothing has to be threaded from a prior phase's output.
+
+## The happy path
+
+Compose the activities into an Op as phases:
+
+```ts
+import { Op, phase } from "@intentius/chant-lexicon-temporal";
+import { spriteCreate, spriteCheckpoint, spriteExec, spriteDestroy }
+  from "@intentius/chant-lexicon-fly";
+
+export default Op({
+  name: "agent-task",
+  overview: "Create a sprite, checkpoint, run the task, verify, destroy",
+  taskQueue: "sprites",
+  phases: [
+    phase("Create", [spriteCreate({ name: "task-1", image: "sprites/base:latest" })]),
+    phase("Checkpoint", [spriteCheckpoint({ id: "task-1", label: "pre-run" })]),
+    phase("Run", [spriteExec({ id: "task-1", cmd: "echo hello > /work/output" })]),
+    phase("Verify", [spriteExec({ id: "task-1", cmd: "cat /work/output" })]),
+    phase("Destroy", [spriteDestroy({ id: "task-1" })]),
+  ],
+});
+```
+
+There is no `build` phase and no serialized plan: the activities run in sequence. Run it with `chant run agent-task`.
+
+## Checkpoint-as-compensation
+
+The reason Sprites map onto chant Ops so well is rollback. A VM checkpoint is a fast transactional boundary. An Op checkpoints before a risky phase and, on failure, restores the labeled checkpoint instead of running an inverse action. The environment itself is the transaction, so there is nothing to unwind by hand.
+
+Put the `spriteRestore` in the Op's `onFailure`, referencing the same label the `Checkpoint` phase wrote:
+
+```ts
+import { Op, phase } from "@intentius/chant-lexicon-temporal";
+import { spriteCreate, spriteCheckpoint, spriteExec, spriteDestroy, spriteRestore }
+  from "@intentius/chant-lexicon-fly";
+
+export default Op({
+  name: "guarded-task",
+  overview: "Checkpoint, run a risky step, restore on failure",
+  taskQueue: "sprites",
+  phases: [
+    phase("Create",     [spriteCreate({ name: "task-1" })]),
+    phase("Checkpoint", [spriteCheckpoint({ id: "task-1", label: "pre-run" })]),
+    phase("Run",        [spriteExec({ id: "task-1", cmd: "./risky.sh" })]),
+    phase("Destroy",    [spriteDestroy({ id: "task-1" })]),
+  ],
+  onFailure: [
+    phase("Restore", [spriteRestore({ id: "task-1", checkpoint: "pre-run" })]),
+  ],
+});
+```
+
+When the `Run` phase's command exits non-zero, `spriteExec` throws, the phase fails, and the Op-level `onFailure` `Restore` rewinds the sprite to its `pre-run` checkpoint.
+
+## Targeting the emulator or real Sprites
+
+The activities resolve their endpoint in this order: an explicit `endpoint` arg, then `SPRITES_BASE_URL`, then the real Sprites base. The same Op targets an emulator or real Sprites with no code change. The default `fetch` client adds `Authorization: Bearer ${SPRITES_API_TOKEN}` when a token is set; the emulator ignores it.
+
+```bash
+# Point at a self-hosted or in-process emulator.
+export SPRITES_BASE_URL=http://127.0.0.1:9000
+chant run agent-task
+```
+
+```bash
+# Real Sprites: drop the override and set a token.
+unset SPRITES_BASE_URL
+export SPRITES_API_TOKEN=...
+chant run agent-task
+```
+
+The offline, Docker-free emulator that CI runs against is `createSpritesFake()` in this lexicon (`src/op/activities/sprites-fake.ts`); the activities and their tests live alongside it in `sprites.ts`. The local-emulator flow is the one to develop against.
+
+The real Sprites REST surface is provisional (S6, tracked in #766): the endpoint constants may still move to match the official API. The activity input and output contracts (the `Args` and `Result` shapes shown above) are the stable interface the Ops and the emulator are written against, so build your Ops on those.
+
+## Where it fits
+
+The runnable starter is [`examples/sprites-agent-task`](../../examples/sprites-agent-task), which ships both Ops above. Run `chant run agent-task` for the happy path and `chant run guarded-task` to watch the checkpoint-as-compensation rollback. `guarded-task` exits non-zero on purpose: the `Run` phase fails, the `onFailure` `Restore` runs, and the sprite is back at `pre-run`.