@intentius/chant-lexicon-fly 0.17.0 → 0.18.0

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,
+  );
+});

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

@@ -0,0 +1,296 @@
+import { describe, test, expect } from "vitest";
+import {
+  resolveSpritesEndpoint,
+  DEFAULT_SPRITES_BASE_URL,
+  accumulateExecFrames,
+  parseCheckpointNdjson,
+  pickCheckpointByComment,
+  splitCommand,
+  spriteExecWsUrl,
+  defaultSpritesHttp,
+  spriteCreate,
+  spriteCheckpoint,
+  spriteRestore,
+  listCheckpoints,
+  spriteDestroy,
+  type SpritesHttp,
+  type Checkpoint,
+} from "./sprites";
+
+const enc = new TextEncoder();
+
+/** Build one exec frame `[stream][payload]`. */
+function frame(stream: number, payload?: string | number[]): Uint8Array {
+  const body = typeof payload === "string" ? enc.encode(payload) : Uint8Array.from(payload ?? []);
+  return Uint8Array.from([stream, ...body]);
+}
+
+// A recording HTTP stub: captures every call and answers from a callback.
+function recorder(answer: (method: string, url: string, body?: unknown) => { status: number; text: string }) {
+  const calls: Array<{ method: string; url: string; body?: unknown; headers?: Record<string, string> }> = [];
+  const http: SpritesHttp = async (method, url, body, headers) => {
+    calls.push({ method, url, body, headers });
+    return answer(method, url, body);
+  };
+  return { http, calls };
+}
+
+// ── Exec frame accumulator (the WS framing, socket-free) ──────────────────────
+
+describe("accumulateExecFrames", () => {
+  test("stdout then exit 0", () => {
+    expect(accumulateExecFrames([frame(1, "hi\n"), frame(3, [0])])).toEqual({
+      stdout: "hi\n",
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+
+  test("stderr then exit 1", () => {
+    expect(accumulateExecFrames([frame(2, "err"), frame(3, [1])])).toEqual({
+      stdout: "",
+      stderr: "err",
+      exitCode: 1,
+    });
+  });
+
+  test("concatenates multiple stdout frames and ignores stdin/eof frames", () => {
+    const frames = [frame(1, "foo"), frame(0), frame(1, "bar"), frame(2, "warn"), frame(4), frame(3, [7])];
+    expect(accumulateExecFrames(frames)).toEqual({ stdout: "foobar", stderr: "warn", exitCode: 7 });
+  });
+
+  test("no exit frame defaults exitCode to 0; empty frames are skipped", () => {
+    expect(accumulateExecFrames([new Uint8Array(0), frame(1, "x")])).toEqual({
+      stdout: "x",
+      stderr: "",
+      exitCode: 0,
+    });
+  });
+
+  test("a multi-byte character split across two stdout frames decodes intact", () => {
+    // "€" is E2 82 AC; split after the first byte across two frames.
+    expect(accumulateExecFrames([frame(1, [0xe2]), frame(1, [0x82, 0xac]), frame(3, [0])]).stdout).toBe("€");
+  });
+});
+
+// ── Checkpoint NDJSON parsing ─────────────────────────────────────────────────
+
+describe("parseCheckpointNdjson", () => {
+  test("mines the version id from real Sprites' message text (type/data shape)", () => {
+    // Verbatim shape from api.sprites.dev: no structured id field — the version
+    // rides inside the "  ID: v1" detail line and the completion message.
+    const body = [
+      '{"type":"info","data":"Creating checkpoint...","time":"2026-07-12T05:01:17Z"}',
+      '{"type":"info","data":"Checkpoint created successfully"}',
+      '{"type":"info","data":"  ID: v1"}',
+      '{"type":"info","data":"  Path: checkpoints/v1"}',
+      '{"type":"complete","data":"Checkpoint v1 created successfully"}',
+    ].join("\n");
+    expect(parseCheckpointNdjson(body)).toEqual({ checkpointId: "v1" });
+  });
+
+  test("honors a structured id from the older {event, id} shape", () => {
+    const body = '{"event":"info","message":"checkpointing"}\n{"event":"complete","id":"v3"}\n';
+    expect(parseCheckpointNdjson(body)).toEqual({ checkpointId: "v3" });
+  });
+
+  test("blank and unparseable lines are skipped; no id → empty", () => {
+    expect(parseCheckpointNdjson('\n{"event":"info"}\nnot-json\n')).toEqual({ checkpointId: "" });
+  });
+});
+
+// ── Comment picker (newest match) ─────────────────────────────────────────────
+
+describe("pickCheckpointByComment", () => {
+  const list: Checkpoint[] = [
+    { id: "v1", comment: "pre-run", create_time: "2026-01-01T00:00:00.000Z", is_auto: false },
+    { id: "v2", comment: "other", create_time: "2026-01-01T00:00:01.000Z", is_auto: false },
+    { id: "v3", comment: "pre-run", create_time: "2026-01-01T00:00:02.000Z", is_auto: false },
+  ];
+
+  test("returns the newest checkpoint carrying the comment", () => {
+    expect(pickCheckpointByComment(list, "pre-run")?.id).toBe("v3");
+  });
+
+  test("returns undefined when nothing matches", () => {
+    expect(pickCheckpointByComment(list, "nope")).toBeUndefined();
+  });
+});
+
+// ── Endpoint resolution (S3) ──────────────────────────────────────────────────
+
+describe("resolveSpritesEndpoint (S3)", () => {
+  test("explicit arg wins and trailing slash is stripped", () => {
+    expect(resolveSpritesEndpoint({ endpoint: "http://localhost:9000/" }, {} as NodeJS.ProcessEnv)).toBe(
+      "http://localhost:9000",
+    );
+  });
+
+  test("SPRITES_BASE_URL env when no arg", () => {
+    expect(resolveSpritesEndpoint({}, { SPRITES_BASE_URL: "http://fake:9000" } as NodeJS.ProcessEnv)).toBe(
+      "http://fake:9000",
+    );
+  });
+
+  test("arg beats env", () => {
+    expect(
+      resolveSpritesEndpoint({ endpoint: "http://arg:1" }, { SPRITES_BASE_URL: "http://env:2" } as NodeJS.ProcessEnv),
+    ).toBe("http://arg:1");
+  });
+
+  test("default is real Sprites", () => {
+    expect(resolveSpritesEndpoint({}, {} as NodeJS.ProcessEnv)).toBe(DEFAULT_SPRITES_BASE_URL);
+  });
+});
+
+// ── Command tokenizing + exec WS url ──────────────────────────────────────────
+
+describe("splitCommand", () => {
+  test("splits on whitespace and respects quotes", () => {
+    expect(splitCommand("echo hi")).toEqual(["echo", "hi"]);
+    expect(splitCommand('sh -c "exit 7"')).toEqual(["sh", "-c", "exit 7"]);
+    expect(splitCommand("echo bad > /state; false")).toEqual(["echo", "bad", ">", "/state;", "false"]);
+  });
+});
+
+describe("spriteExecWsUrl", () => {
+  test("http → ws with cmd/path/stdin/cc params", () => {
+    const url = new URL(spriteExecWsUrl("http://x:9000", "task-1", "echo hi"));
+    expect(url.protocol).toBe("ws:");
+    expect(url.pathname).toBe("/v1/sprites/task-1/exec");
+    expect(url.searchParams.getAll("cmd")).toEqual(["echo", "hi"]);
+    expect(url.searchParams.get("path")).toBe("echo");
+    expect(url.searchParams.get("stdin")).toBe("false");
+    expect(url.searchParams.get("cc")).toBe("true");
+  });
+
+  test("https → wss", () => {
+    expect(spriteExecWsUrl("https://api.sprites.dev", "s", "ls").startsWith("wss://api.sprites.dev/")).toBe(true);
+  });
+});
+
+// ── Activity request shapes (injected SpritesHttp; no real sockets) ───────────
+
+describe("spriteCreate", () => {
+  test("POSTs /v1/sprites with the name and parses { id, url }", async () => {
+    const { http, calls } = recorder(() => ({
+      status: 201,
+      text: JSON.stringify({ id: "sprite-1", url: "http://h/s/task-1" }),
+    }));
+    const res = await spriteCreate({ name: "task-1", endpoint: "http://x:9000", image: "base:1" }, undefined, http);
+    expect(res).toEqual({ id: "sprite-1", url: "http://h/s/task-1" });
+    expect(calls[0].method).toBe("POST");
+    expect(calls[0].url).toBe("http://x:9000/v1/sprites");
+    expect(calls[0].body).toEqual({ name: "task-1", image: "base:1" });
+  });
+});
+
+describe("spriteCheckpoint", () => {
+  test("POSTs the singular /checkpoint with the comment and reads the NDJSON complete id", async () => {
+    const { http, calls } = recorder(() => ({
+      status: 200,
+      text: '{"event":"info"}\n{"event":"complete","id":"v5"}\n',
+    }));
+    const res = await spriteCheckpoint({ id: "task-1", comment: "pre-run", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual({ checkpointId: "v5" });
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1/checkpoint");
+    expect(calls[0].body).toEqual({ comment: "pre-run" });
+  });
+
+  test("omits the comment key when empty", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: '{"event":"complete","id":"v1"}\n' }));
+    await spriteCheckpoint({ id: "task-1", endpoint: "http://x" }, undefined, http);
+    expect(calls[0].body).toBeUndefined();
+  });
+});
+
+describe("listCheckpoints", () => {
+  test("GETs the plural /checkpoints and returns the array", async () => {
+    const list = [{ id: "v1", comment: "pre-run", create_time: "2026-01-01T00:00:00.000Z", is_auto: false }];
+    const { http, calls } = recorder(() => ({ status: 200, text: JSON.stringify(list) }));
+    const res = await listCheckpoints({ id: "task-1", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual(list);
+    expect(calls[0].method).toBe("GET");
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1/checkpoints");
+  });
+});
+
+describe("spriteRestore", () => {
+  test("explicit checkpoint id → POST /checkpoints/{id}/restore", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: '{"event":"complete","id":"v2"}\n' }));
+    const res = await spriteRestore({ id: "task-1", checkpoint: "v2", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual({});
+    expect(calls).toHaveLength(1);
+    expect(calls[0].method).toBe("POST");
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1/checkpoints/v2/restore");
+  });
+
+  test("comment → list, pick newest match, then restore that id", async () => {
+    const list: Checkpoint[] = [
+      { id: "v1", comment: "pre-run", create_time: "2026-01-01T00:00:00.000Z", is_auto: false },
+      { id: "v4", comment: "pre-run", create_time: "2026-01-01T00:00:09.000Z", is_auto: false },
+    ];
+    const { http, calls } = recorder((method) =>
+      method === "GET"
+        ? { status: 200, text: JSON.stringify(list) }
+        : { status: 200, text: '{"event":"complete","id":"v4"}\n' },
+    );
+    await spriteRestore({ id: "task-1", comment: "pre-run", endpoint: "http://x" }, undefined, http);
+    expect(calls[0].method).toBe("GET");
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1/checkpoints");
+    expect(calls[1].url).toBe("http://x/v1/sprites/task-1/checkpoints/v4/restore");
+  });
+
+  test("throws when no checkpoint carries the comment", async () => {
+    const { http } = recorder(() => ({ status: 200, text: "[]" }));
+    await expect(
+      spriteRestore({ id: "task-1", comment: "nope", endpoint: "http://x" }, undefined, http),
+    ).rejects.toThrow(/no checkpoint matching comment "nope"/);
+  });
+});
+
+describe("spriteDestroy", () => {
+  test("DELETEs /v1/sprites/{id}", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: "{}" }));
+    await spriteDestroy({ id: "task-1", endpoint: "http://x" }, undefined, http);
+    expect(calls[0].method).toBe("DELETE");
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1");
+  });
+
+  test("a 404 is idempotent (already gone), not an error", async () => {
+    const { http } = recorder(() => ({ status: 404, text: "gone" }));
+    await expect(spriteDestroy({ id: "task-1", endpoint: "http://x" }, undefined, http)).resolves.toEqual({});
+  });
+});
+
+// ── Bearer header on the default client ───────────────────────────────────────
+
+describe("defaultSpritesHttp bearer header", () => {
+  test("sends Authorization: Bearer <token> when a token is set", async () => {
+    const seen: Array<Record<string, string> | undefined> = [];
+    const fakeFetch = (async (_url: string, init: { headers?: Record<string, string> }) => {
+      seen.push(init.headers);
+      return { status: 200, text: async () => "{}" } as unknown as Response;
+    }) as unknown as typeof fetch;
+    const http = defaultSpritesHttp("secret-token", fakeFetch);
+    await http("GET", "http://x/v1/sprites/task-1");
+    expect(seen[0]?.authorization).toBe("Bearer secret-token");
+  });
+
+  test("no Authorization header when no token is set", async () => {
+    const seen: Array<Record<string, string> | undefined> = [];
+    const fakeFetch = (async (_url: string, init: { headers?: Record<string, string> }) => {
+      seen.push(init?.headers);
+      return { status: 200, text: async () => "{}" } as unknown as Response;
+    }) as unknown as typeof fetch;
+    const prev = process.env.SPRITES_API_TOKEN;
+    delete process.env.SPRITES_API_TOKEN;
+    try {
+      const http = defaultSpritesHttp(undefined, fakeFetch);
+      await http("GET", "http://x/v1/sprites/task-1");
+      expect(seen[0]?.authorization).toBeUndefined();
+    } finally {
+      if (prev !== undefined) process.env.SPRITES_API_TOKEN = prev;
+    }
+  });
+});