@intentius/chant-lexicon-fly 0.16.0 → 0.18.0

package/src/op/activities/sprites-fake.ts

@@ -0,0 +1,314 @@
+/**
+ * In-process Sprites fake (#762, #766, S7) — a fake of the faithful Sprites API
+ * surface for offline, Docker-free integration tests.
+ *
+ * It models the lifecycle state machine and checkpoint/restore semantics, not
+ * real Firecracker VMs or real code execution (that fidelity is out of scope).
+ * A sprite's filesystem is a `Record<string, string>`; `exec` runs a small
+ * scripted interpreter that can write/modify an `fs` key so checkpoint/restore
+ * is observable; `checkpoint` deep-copies `fs` under a version id; `restore`
+ * replaces `fs` with that copy. Started in-process by a test and reached via
+ * `SPRITES_BASE_URL`, so the same activities that hit real Sprites hit the fake.
+ *
+ * The wire surface matches the released `spritzer:0.3.1` image so the CI
+ * fake-based test and the docker test exercise the same protocol:
+ *  - `exec` over the control WebSocket with `[StreamID][payload]` binary framing;
+ *  - `POST /checkpoint` (singular) returning NDJSON progress + a `complete` event;
+ *  - `GET /checkpoints` returning a bare array of `{ id, comment, create_time, is_auto }`;
+ *  - `POST /checkpoints/{id}/restore` returning NDJSON.
+ * Checkpoint ids are server versions (`v1`, `v2`, ...).
+ */
+
+import { createServer, type Server, type IncomingMessage, type ServerResponse } from "node:http";
+import type { Duplex } from "node:stream";
+import { WebSocketServer, type WebSocket } from "ws";
+
+type SpriteStatus = "starting" | "running" | "paused" | "destroyed";
+
+interface StoredCheckpoint {
+  id: string;
+  comment: string;
+  create_time: string;
+  is_auto: boolean;
+  fs: Record<string, string>;
+}
+
+interface SpriteState {
+  id: string;
+  status: SpriteStatus;
+  url: string;
+  /** Filesystem model: path → contents. */
+  fs: Record<string, string>;
+  /** Checkpoints in creation order; each holds a full copy of `fs` at that time. */
+  checkpoints: StoredCheckpoint[];
+  /** Monotonic version counter for `v<N>` ids. */
+  version: number;
+  policy?: unknown;
+}
+
+interface ExecResult {
+  stdout: string;
+  stderr: string;
+  exitCode: number;
+}
+
+/**
+ * Run one command against a sprite's `fs`. Not a real shell: it recognizes a
+ * small set of forms so a test (and the example `guarded-task` Op) can write a
+ * key, then overwrite/fail it, and prove restore rewinds. Segments split on
+ * `;` run in order; the exit code is the last segment's (shell `;` semantics).
+ */
+export function fakeExec(sprite: SpriteState, cmd: string): ExecResult {
+  let stdout = "";
+  let stderr = "";
+  let exitCode = 0;
+
+  for (const raw of cmd.split(";")) {
+    const seg = raw.trim();
+    if (!seg) continue;
+
+    let m: RegExpMatchArray | null;
+    if ((m = seg.match(/^echo\s+(.+?)\s*>\s*(\S+)$/))) {
+      sprite.fs[m[2]] = unquote(m[1]);
+      exitCode = 0;
+    } else if ((m = seg.match(/^echo\s+(.+)$/))) {
+      stdout += `${unquote(m[1])}\n`;
+      exitCode = 0;
+    } else if ((m = seg.match(/^cat\s+(\S+)$/))) {
+      stdout += sprite.fs[m[1]] ?? "";
+      exitCode = 0;
+    } else if ((m = seg.match(/^rm\s+(?:-f\s+)?(\S+)$/))) {
+      delete sprite.fs[m[1]];
+      exitCode = 0;
+    } else if (seg === "false") {
+      exitCode = 1;
+    } else if (seg === "true") {
+      exitCode = 0;
+    } else if (seg === "./risky.sh") {
+      // A scripted failing job: mutates the workspace, then exits non-zero, so
+      // the example guarded-task Op demonstrates checkpoint-as-compensation.
+      sprite.fs["/work/output"] = "partial-corrupt";
+      stderr += "risky.sh: failed\n";
+      exitCode = 1;
+    } else {
+      // Unknown command → echo it back (a no-op success), never real execution.
+      stdout += `${seg}\n`;
+      exitCode = 0;
+    }
+  }
+
+  return { stdout, stderr, exitCode };
+}
+
+function unquote(s: string): string {
+  const t = s.trim();
+  if ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'"))) {
+    return t.slice(1, -1);
+  }
+  return t;
+}
+
+/** A full copy of an `fs` map. Values are strings, so a shallow spread copies them. */
+function copyFs(fs: Record<string, string>): Record<string, string> {
+  return { ...fs };
+}
+
+// Stream ids for the non-PTY exec framing (mirror sprites.ts).
+const STREAM_STDOUT = 1;
+const STREAM_STDERR = 2;
+const STREAM_EXIT = 3;
+
+function frame(stream: number, payload: Buffer): Buffer {
+  return Buffer.concat([Buffer.of(stream), payload]);
+}
+
+async function readBody(req: IncomingMessage): Promise<unknown> {
+  const chunks: Buffer[] = [];
+  for await (const c of req) chunks.push(c as Buffer);
+  if (chunks.length === 0) return undefined;
+  const text = Buffer.concat(chunks).toString("utf8");
+  if (!text) return undefined;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Start the in-process Sprites fake on an ephemeral port. Returns its base
+ * `url` (feed it to `SPRITES_BASE_URL`) and a `close()`.
+ */
+export function createSpritesFake(): Promise<{ url: string; close(): Promise<void> }> {
+  const sprites = new Map<string, SpriteState>();
+
+  const server: Server = createServer((req, res) => {
+    void handle(req, res).catch((err) => {
+      res.writeHead(500, { "content-type": "application/json" });
+      res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+    });
+  });
+
+  // The control WebSocket exec endpoint. noServer + a manual `upgrade` handler so
+  // the same http server serves both the REST/NDJSON routes and the exec socket.
+  const wss = new WebSocketServer({ noServer: true });
+
+  server.on("upgrade", (req: IncomingMessage, socket: Duplex, head: Buffer) => {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const m = url.pathname.match(/^\/v1\/sprites\/([^/]+)\/exec\/?$/);
+    if (!m) {
+      socket.destroy();
+      return;
+    }
+    const id = decodeURIComponent(m[1]);
+    wss.handleUpgrade(req, socket, head, (ws) => runExec(ws, sprites.get(id), url));
+  });
+
+  function runExec(ws: WebSocket, sprite: SpriteState | undefined, url: URL): void {
+    if (!sprite || sprite.status === "destroyed") {
+      ws.send(frame(STREAM_STDERR, Buffer.from(`no sprite\n`)));
+      ws.send(frame(STREAM_EXIT, Buffer.of(127)));
+      ws.close();
+      return;
+    }
+    // argv arrives as repeated `cmd` params; reconstruct the script the small
+    // interpreter understands (the tokens round-trip for the space-separated
+    // command forms the example Ops use).
+    const argv = url.searchParams.getAll("cmd");
+    const script = argv.join(" ");
+    const result = fakeExec(sprite, script);
+    if (result.stdout) ws.send(frame(STREAM_STDOUT, Buffer.from(result.stdout)));
+    if (result.stderr) ws.send(frame(STREAM_STDERR, Buffer.from(result.stderr)));
+    ws.send(frame(STREAM_EXIT, Buffer.of(result.exitCode & 0xff)));
+    ws.close();
+  }
+
+  async function handle(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    const method = req.method ?? "GET";
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    const path = url.pathname;
+    const host = req.headers.host ?? "localhost";
+    const send = (status: number, body: unknown): void => {
+      res.writeHead(status, { "content-type": "application/json" });
+      res.end(JSON.stringify(body ?? {}));
+    };
+    // NDJSON progress stream: an `info` line then a terminal `complete` line.
+    const sendNdjson = (status: number, events: Array<Record<string, unknown>>): void => {
+      res.writeHead(status, { "content-type": "application/x-ndjson" });
+      res.end(events.map((e) => JSON.stringify(e)).join("\n") + "\n");
+    };
+
+    // POST /v1/sprites — create.
+    if (method === "POST" && /^\/v1\/sprites\/?$/.test(path)) {
+      const body = ((await readBody(req)) ?? {}) as { name?: string; policy?: unknown };
+      const id = body.name;
+      if (!id) return send(400, { error: "name is required" });
+      const sprite: SpriteState = {
+        id,
+        status: "running",
+        url: `http://${host}/s/${encodeURIComponent(id)}`,
+        fs: {},
+        checkpoints: [],
+        version: 0,
+        policy: body.policy,
+      };
+      sprites.set(id, sprite);
+      return send(201, { id: sprite.id, url: sprite.url });
+    }
+
+    const m = path.match(/^\/v1\/sprites\/([^/]+)(\/checkpoint|\/checkpoints(?:\/([^/]+)(\/restore)?)?)?\/?$/);
+    if (m) {
+      const id = decodeURIComponent(m[1]);
+      const sub = m[2];
+      const cpId = m[3] ? decodeURIComponent(m[3]) : undefined;
+      const isRestore = Boolean(m[4]);
+      const sprite = sprites.get(id);
+      if (!sprite || sprite.status === "destroyed") return send(404, { error: `no sprite ${id}` });
+
+      // POST /v1/sprites/{id}/checkpoint — snapshot fs under a new version id.
+      if (method === "POST" && sub === "/checkpoint") {
+        const body = ((await readBody(req)) ?? {}) as { comment?: string };
+        sprite.version += 1;
+        const cp: StoredCheckpoint = {
+          id: `v${sprite.version}`,
+          comment: body.comment ?? "",
+          create_time: new Date().toISOString(),
+          is_auto: false,
+          fs: copyFs(sprite.fs),
+        };
+        sprite.checkpoints.push(cp);
+        // Mirror real Sprites: `{type, data}` progress lines carrying the
+        // version id in the message text, not a structured field.
+        return sendNdjson(200, [
+          { type: "info", data: "Creating checkpoint..." },
+          { type: "info", data: "Checkpoint created successfully" },
+          { type: "info", data: `  ID: ${cp.id}` },
+          { type: "complete", data: `Checkpoint ${cp.id} created successfully` },
+        ]);
+      }
+
+      // GET /v1/sprites/{id}/checkpoints — bare array (auto excluded).
+      if (method === "GET" && sub === "/checkpoints" && !cpId) {
+        return send(
+          200,
+          sprite.checkpoints
+            .filter((c) => !c.is_auto)
+            .map((c) => ({ id: c.id, comment: c.comment, create_time: c.create_time, is_auto: c.is_auto })),
+        );
+      }
+
+      // GET /v1/sprites/{id}/checkpoints/{cp} — a single checkpoint.
+      if (method === "GET" && cpId && !isRestore) {
+        const cp = sprite.checkpoints.find((c) => c.id === cpId);
+        if (!cp) return send(404, { error: `no checkpoint ${cpId} for sprite ${id}` });
+        return send(200, { id: cp.id, comment: cp.comment, create_time: cp.create_time });
+      }
+
+      // POST /v1/sprites/{id}/checkpoints/{cp}/restore — replace fs with the snapshot.
+      if (method === "POST" && cpId && isRestore) {
+        const cp = sprite.checkpoints.find((c) => c.id === cpId);
+        if (!cp) return send(404, { error: `no checkpoint ${cpId} for sprite ${id}` });
+        sprite.fs = copyFs(cp.fs);
+        sprite.status = "running";
+        return sendNdjson(200, [
+          { type: "info", data: `Restoring checkpoint ${cpId}...` },
+          { type: "complete", data: `Checkpoint ${cpId} restored successfully` },
+        ]);
+      }
+
+      // DELETE /v1/sprites/{id}
+      if (method === "DELETE" && !sub) {
+        sprite.status = "destroyed";
+        return send(200, {});
+      }
+
+      // GET /v1/sprites/{id} — inspection (fs + checkpoint ids), used by tests/verify.
+      if (method === "GET" && !sub) {
+        return send(200, {
+          id: sprite.id,
+          status: sprite.status,
+          url: sprite.url,
+          fs: sprite.fs,
+          checkpoints: sprite.checkpoints.map((c) => c.id),
+        });
+      }
+    }
+
+    return send(404, { error: `not found: ${method} ${path}` });
+  }
+
+  return new Promise((resolve) => {
+    server.listen(0, "127.0.0.1", () => {
+      const addr = server.address();
+      const port = typeof addr === "object" && addr ? addr.port : 0;
+      resolve({
+        url: `http://127.0.0.1:${port}`,
+        close: () =>
+          new Promise<void>((res, rej) => {
+            wss.close();
+            server.close((err) => (err ? rej(err) : res()));
+          }),
+      });
+    });
+  });
+}

package/src/op/activities/sprites.docker.integration.test.ts

@@ -0,0 +1,99 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import {
+  loadActivities,
+  runOpLocally,
+  OpRunFailure,
+  phase,
+  spriteCreate,
+  spriteExec,
+  spriteCheckpoint,
+  spriteRestore,
+  spriteDestroy,
+  type ActivityFn,
+  type ActivityProfile,
+  type OpConfig,
+} from "@intentius/chant/op";
+import { spritesUp, spritesDown } from "./sprites-emulator";
+
+// The checkpoint-as-compensation loop against the REAL spritzer image
+// (ghcr.io/intentius/spritzer), booted via `spritesUp` — the twin of fly's
+// mudflaps integration test. Proves the image is wire-compatible with the
+// in-process fake the CI test uses. Docker required; deterministically skipped
+// in CI (GitHub runners have Docker, so relying on absence would pull the image
+// on every run). Run locally, or opt in with SPRITES_DOCKER=1.
+
+const CONTAINER = "chant-spritzer-it";
+const PORT = 4292;
+const PROFILES: Record<string, ActivityProfile> = {
+  longInfra: { startToCloseTimeout: "5m", retry: { maximumAttempts: 3, initialInterval: "50ms", backoffCoefficient: 1 } },
+  fastIdempotent: { startToCloseTimeout: "5m", retry: { maximumAttempts: 2, initialInterval: "50ms", backoffCoefficient: 1 } },
+};
+
+let available = false;
+let endpoint = "";
+let activities: Map<string, ActivityFn>;
+let prevBaseUrl: string | undefined;
+
+async function inspect(id: string): Promise<{ status: string; fs: Record<string, string>; checkpoints: string[] }> {
+  const res = await fetch(`${endpoint}/v1/sprites/${id}`);
+  return (await res.json()) as { status: string; fs: Record<string, string>; checkpoints: string[] };
+}
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.SPRITES_DOCKER) {
+    available = false;
+    return;
+  }
+  try {
+    const up = await spritesUp({ name: CONTAINER, port: PORT, timeoutMs: 30_000 });
+    endpoint = up.endpoint;
+    prevBaseUrl = process.env.SPRITES_BASE_URL;
+    process.env.SPRITES_BASE_URL = endpoint;
+    activities = await loadActivities(["fly"]);
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 60_000);
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  if (available) await spritesDown({ name: CONTAINER });
+});
+
+describe("sprites against the live spritzer image (#786)", () => {
+  test("guarded-task: Run fails, onFailure Restore rewinds the sprite to the checkpoint", async (ctx) => {
+    if (!available) ctx.skip();
+    const op: OpConfig = {
+      name: "guarded-task",
+      overview: "checkpoint, run a risky step, restore on failure",
+      taskQueue: "sprites",
+      phases: [
+        phase("Create", [spriteCreate({ name: "guard-1" })]),
+        phase("Seed", [spriteExec({ id: "guard-1", cmd: "echo good > /state" })]),
+        phase("Checkpoint", [spriteCheckpoint({ id: "guard-1", comment: "pre-run" })]),
+        phase("Run", [spriteExec({ id: "guard-1", cmd: "echo bad > /state; false" })]),
+        phase("Destroy", [spriteDestroy({ id: "guard-1" })]),
+      ],
+      onFailure: [phase("Restore", [spriteRestore({ id: "guard-1", comment: "pre-run" })])],
+    };
+
+    let failure: OpRunFailure | undefined;
+    try {
+      await runOpLocally(op, activities, PROFILES);
+    } catch (err) {
+      failure = err as OpRunFailure;
+    }
+    expect(failure).toBeInstanceOf(OpRunFailure); // the risky Run failed
+    const records = failure!.result.records;
+    expect(records.find((r) => r.phase === "Run")?.status).toBe("fail");
+    // Compensation ran against the live image.
+    const restore = records.find((r) => r.phase === "Restore");
+    expect(restore?.fn).toBe("spriteRestore");
+    expect(restore?.status).toBe("ok");
+
+    const state = await inspect("guard-1");
+    expect(state.fs["/state"]).toBe("good"); // rewound past the "bad" write
+  });
+});

package/src/op/activities/sprites.integration.test.ts

@@ -0,0 +1,158 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import {
+  loadActivities,
+  runOpLocally,
+  OpRunFailure,
+  phase,
+  spriteCreate,
+  spriteExec,
+  spriteCheckpoint,
+  spriteRestore,
+  spriteDestroy,
+  type ActivityFn,
+  type ActivityProfile,
+  type OpConfig,
+} from "@intentius/chant/op";
+import { createSpritesFake } from "./sprites-fake";
+
+// End-to-end against the in-process fake (S7) — no Docker, runs in CI. The
+// activities resolve by name through `loadActivities(["fly"])` and reach
+// the fake via `SPRITES_BASE_URL`. Fast profiles so retry loops run in ms.
+
+const PROFILES: Record<string, ActivityProfile> = {
+  longInfra: { startToCloseTimeout: "5m", retry: { maximumAttempts: 3, initialInterval: "1ms", backoffCoefficient: 1 } },
+  fastIdempotent: { startToCloseTimeout: "5m", retry: { maximumAttempts: 2, initialInterval: "1ms", backoffCoefficient: 1 } },
+};
+
+let fake: { url: string; close(): Promise<void> };
+let activities: Map<string, ActivityFn>;
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  fake = await createSpritesFake();
+  // Prove endpoint override via the env (S3): the same Op targets the fake with
+  // no code change. Activities read SPRITES_BASE_URL when no `endpoint` arg is set.
+  prevBaseUrl = process.env.SPRITES_BASE_URL;
+  process.env.SPRITES_BASE_URL = fake.url;
+  activities = await loadActivities(["fly"]);
+});
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  await fake?.close();
+});
+
+/** Read a sprite's live state (fs + checkpoints) from the fake. */
+async function inspect(id: string): Promise<{ status: string; fs: Record<string, string>; checkpoints: string[] }> {
+  const res = await fetch(`${fake.url}/v1/sprites/${id}`);
+  return (await res.json()) as { status: string; fs: Record<string, string>; checkpoints: string[] };
+}
+
+describe("sprite activities resolve by name (S2)", () => {
+  test("loadActivities([\"fly\"]) exposes the five sprite activities", () => {
+    for (const fn of ["spriteCreate", "spriteExec", "spriteCheckpoint", "spriteRestore", "spriteDestroy"]) {
+      expect(typeof activities.get(fn)).toBe("function");
+    }
+  });
+});
+
+describe("agent-task happy path", () => {
+  test("Create → Checkpoint → Run → Verify → Destroy runs green end to end", async () => {
+    const op: OpConfig = {
+      name: "agent-task",
+      overview: "happy path",
+      taskQueue: "sprites",
+      phases: [
+        phase("Create", [spriteCreate({ name: "task-1" })]),
+        phase("Checkpoint", [spriteCheckpoint({ id: "task-1", comment: "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" })]),
+      ],
+    };
+    const result = await runOpLocally(op, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(result.records.map((r) => r.fn)).toEqual([
+      "spriteCreate",
+      "spriteCheckpoint",
+      "spriteExec",
+      "spriteExec",
+      "spriteDestroy",
+    ]);
+    expect(result.records.every((r) => r.status === "ok")).toBe(true);
+  });
+
+  test("exec mutates the sprite fs (checkpoint/restore observability)", async () => {
+    const op: OpConfig = {
+      name: "agent-write",
+      overview: "state observability",
+      phases: [
+        phase("Create", [spriteCreate({ name: "obs-1" })]),
+        phase("Run", [spriteExec({ id: "obs-1", cmd: "echo hello > /work/output" })]),
+      ],
+    };
+    await runOpLocally(op, activities, PROFILES);
+    const state = await inspect("obs-1");
+    expect(state.fs).toEqual({ "/work/output": "hello" });
+  });
+});
+
+describe("guarded-task — checkpoint-as-compensation (S5)", () => {
+  test("Run fails → onFailure Restore runs → fs is rewound to the pre-run checkpoint", async () => {
+    const op: OpConfig = {
+      name: "guarded-task",
+      overview: "checkpoint, run a risky step, restore on failure",
+      taskQueue: "sprites",
+      phases: [
+        phase("Create", [spriteCreate({ name: "guard-1" })]),
+        phase("Seed", [spriteExec({ id: "guard-1", cmd: "echo good > /state" })]),
+        phase("Checkpoint", [spriteCheckpoint({ id: "guard-1", comment: "pre-run" })]),
+        // Overwrites the good state, then fails — the risky phase.
+        phase("Run", [spriteExec({ id: "guard-1", cmd: "echo bad > /state; false" })]),
+        phase("Destroy", [spriteDestroy({ id: "guard-1" })]),
+      ],
+      onFailure: [phase("Restore", [spriteRestore({ id: "guard-1", comment: "pre-run" })])],
+    };
+
+    let failure: OpRunFailure | undefined;
+    try {
+      await runOpLocally(op, activities, PROFILES);
+    } catch (err) {
+      failure = err as OpRunFailure;
+    }
+
+    // The Op failed at the risky Run and never reached Destroy.
+    expect(failure).toBeInstanceOf(OpRunFailure);
+    const records = failure!.result.records;
+    const run = records.find((r) => r.phase === "Run");
+    expect(run?.status).toBe("fail");
+    expect(records.some((r) => r.phase === "Destroy")).toBe(false);
+
+    // Compensation ran: onFailure Restore executed and succeeded.
+    const restore = records.find((r) => r.phase === "Restore");
+    expect(restore?.fn).toBe("spriteRestore");
+    expect(restore?.status).toBe("ok");
+
+    // The environment is the transaction: fs is back to the checkpoint state.
+    const state = await inspect("guard-1");
+    expect(state.fs).toEqual({ "/state": "good" });
+    expect(state.status).toBe("running");
+  });
+
+  test("control: without onFailure the risky write is NOT rewound (fs stays corrupt)", async () => {
+    const op: OpConfig = {
+      name: "unguarded-task",
+      overview: "no compensation",
+      phases: [
+        phase("Create", [spriteCreate({ name: "unguard-1" })]),
+        phase("Seed", [spriteExec({ id: "unguard-1", cmd: "echo good > /state" })]),
+        phase("Checkpoint", [spriteCheckpoint({ id: "unguard-1", comment: "pre-run" })]),
+        phase("Run", [spriteExec({ id: "unguard-1", cmd: "echo bad > /state; false" })]),
+      ],
+    };
+    await expect(runOpLocally(op, activities, PROFILES)).rejects.toBeInstanceOf(OpRunFailure);
+    const state = await inspect("unguard-1");
+    expect(state.fs).toEqual({ "/state": "bad" });
+  });
+});

package/src/op/activities/sprites.real.test.ts

@@ -0,0 +1,56 @@
+import { describe, test, expect } from "vitest";
+import { spriteCreate, spriteExec, spriteDestroy, resolveSpritesEndpoint } from "./sprites";
+
+// Real Sprites smoke test (#766), gated on `SPRITES_API_TOKEN`. Runs the WS exec
+// client against the live control WebSocket at api.sprites.dev: create a
+// uniquely-named sprite, exec `echo hi` (assert stdout + exit 0), exec
+// `sh -c "exit 7"` (assert the exit code surfaces as 7), then destroy in a
+// finally. Skips cleanly when the token is absent. The token is read from the
+// environment only — never hardcode it.
+
+const TOKEN = process.env.SPRITES_API_TOKEN;
+const BASE = resolveSpritesEndpoint();
+
+/** Poll the sprite until it reports `running` (or give up after `timeoutMs`). */
+async function waitRunning(name: string, timeoutMs = 90_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const res = await fetch(`${BASE}/v1/sprites/${encodeURIComponent(name)}`, {
+      headers: { authorization: `Bearer ${TOKEN}` },
+    });
+    if (res.ok) {
+      const b = (await res.json().catch(() => ({}))) as { status?: string };
+      if (b.status === "running") return;
+    }
+    await new Promise((r) => setTimeout(r, 2000));
+  }
+}
+
+describe("real Sprites exec over the control WebSocket (gated on SPRITES_API_TOKEN)", () => {
+  test.skipIf(!TOKEN)(
+    "echo hi → exit 0; sh -c \"exit 7\" → exit 7",
+    async () => {
+      const name = `chant-it-${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 8)}`;
+      try {
+        await spriteCreate({ name });
+        await waitRunning(name);
+
+        const ok = await spriteExec({ id: name, cmd: "echo hi" });
+        expect(ok.exitCode).toBe(0);
+        expect(ok.stdout).toContain("hi");
+
+        // A non-zero exit throws; capture the surfaced exit code.
+        let code: number | undefined;
+        try {
+          await spriteExec({ id: name, cmd: 'sh -c "exit 7"' });
+        } catch (err) {
+          code = Number((err as Error).message.match(/exited (\d+)/)?.[1]);
+        }
+        expect(code).toBe(7);
+      } finally {
+        await spriteDestroy({ id: name }).catch(() => {});
+      }
+    },
+    120_000,
+  );
+});