@intentius/chant-lexicon-fly 0.89.0 → 0.91.0

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

@@ -6,9 +6,13 @@ import { SPRITES_CONTRACT, normalizeEndpoint, contractKeys } from "./sprites-con
 
 describe("SPRITES_CONTRACT", () => {
   test("covers every sprite activity that calls the Sprites API", () => {
-    const activities = new Set(SPRITES_CONTRACT.map((e) => e.activity));
-    // Every activity across the lifecycle, filesystem, config-reconcile, and
-    // keep-alive modules that makes an HTTP/WS call.
+    // A row's `activity` is comma-separated when more than one activity calls
+    // that physical endpoint (#2711) — split before comparing.
+    const activities = new Set(SPRITES_CONTRACT.flatMap((e) => e.activity.split(",").map((a) => a.trim())));
+    // Every activity across the lifecycle, filesystem, config-reconcile,
+    // single-service, and keep-alive modules that makes an HTTP/WS call.
+    // (spriteUrl, spriteServiceDelete and spriteServiceLogs are deliberately
+    // absent — see the module doc.)
     expect(activities).toEqual(
       new Set([
         // lifecycle (./sprites.ts)
@@ -18,6 +22,7 @@ describe("SPRITES_CONTRACT", () => {
         "listCheckpoints",
         "spriteRestore",
         "spriteDestroy",
+        "spriteDelete",
         // filesystem (./sprite-fs.ts)
         "spriteWriteFile",
         "spriteReadFile",
@@ -26,6 +31,12 @@ describe("SPRITES_CONTRACT", () => {
         // config reconcile (./sprite-config.ts)
         "spriteApplyNetworkPolicy",
         "spriteApplyServices",
+        // single-service (./sprite-services.ts, #2711)
+        "spriteServiceCreate",
+        "spriteServiceGet",
+        "spriteServiceList",
+        "spriteServiceStart",
+        "spriteServiceStop",
         // keep-alive tasks (./sprite-tasks.ts)
         "spriteTaskCreate",
         "spriteTaskRefresh",
@@ -63,7 +74,7 @@ describe("SPRITES_CONTRACT", () => {
     // contract must be updated in the same change. Scans every module that owns
     // contract endpoints, not just the lifecycle one.
     const dir = dirname(fileURLToPath(import.meta.url));
-    const src = ["sprites.ts", "sprite-fs.ts", "sprite-config.ts", "sprite-tasks.ts"]
+    const src = ["sprites.ts", "sprite-fs.ts", "sprite-config.ts", "sprite-services.ts", "sprite-tasks.ts"]
       .map((f) => readFileSync(join(dir, f), "utf-8"))
       .join("\n");
     const segments = new Set(

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

@@ -19,6 +19,22 @@
  * Path params are written with names matching ./sprites.ts (`{id}`, `{cp}`);
  * the coverage check normalizes param names before comparing, since spritzer
  * spells the checkpoint id `{cid}`.
+ *
+ * #2711 adds the imperative Services activities (`./sprite-services.ts`).
+ * Several of them share a physical endpoint with `spriteApplyServices`'s own
+ * calls (one `PUT`/one `GET .../services`/one `.../start` — the reconcile
+ * activity and the single-service primitives are two callers of the same
+ * REST surface), so one row lists every activity that calls it, comma
+ * separated, rather than one row per activity — `contractKeys()` stays one
+ * key per physical endpoint. `spriteServiceDelete` and `spriteServiceLogs`
+ * are deliberately absent: spritzer's interpreter mode (the coverage test's
+ * oracle) doesn't implement them, only its container-mode agent does, which
+ * has no per-verb entry in `/_spritzer/health` (real.go reports the whole
+ * `/v1/sprites/{id}/services/...` proxy as one wildcard line — nothing to
+ * normalize-compare against a specific verb). They're exercised instead by
+ * `sprite-services.docker.integration.test.ts` against real container-mode
+ * spritzer. `spriteUrl` is absent for the same reason, plus its target
+ * (`/s/{name}/...`) isn't under `/v1/sprites` at all.
  */
 
 /** One endpoint the fly sprite activities call. */
@@ -27,7 +43,7 @@ export interface SpritesEndpoint {
   method: "GET" | "POST" | "PUT" | "DELETE" | "WS";
   /** Path template under the Sprites base, e.g. `/v1/sprites/{id}/checkpoint`. */
   path: string;
-  /** The fly activity that calls it (an activity module export). */
+  /** The fly activity/activities that call it (comma-separated when more than one shares the endpoint). */
   activity: string;
 }
 
@@ -46,7 +62,7 @@ export const SPRITES_CONTRACT: readonly SpritesEndpoint[] = [
   { method: "POST", path: "/v1/sprites/{id}/checkpoint", activity: "spriteCheckpoint" },
   { method: "GET", path: "/v1/sprites/{id}/checkpoints", activity: "listCheckpoints" },
   { method: "POST", path: "/v1/sprites/{id}/checkpoints/{cp}/restore", activity: "spriteRestore" },
-  { method: "DELETE", path: "/v1/sprites/{id}", activity: "spriteDestroy" },
+  { method: "DELETE", path: "/v1/sprites/{id}", activity: "spriteDestroy, spriteDelete" },
   // Filesystem (./sprite-fs.ts)
   { method: "PUT", path: "/v1/sprites/{id}/fs/write", activity: "spriteWriteFile" },
   { method: "GET", path: "/v1/sprites/{id}/fs/read", activity: "spriteReadFile" },
@@ -55,10 +71,12 @@ export const SPRITES_CONTRACT: readonly SpritesEndpoint[] = [
   // Network policy (./sprite-config.ts)
   { method: "GET", path: "/v1/sprites/{id}/policy/network", activity: "spriteApplyNetworkPolicy" },
   { method: "POST", path: "/v1/sprites/{id}/policy/network", activity: "spriteApplyNetworkPolicy" },
-  // Services (./sprite-config.ts)
-  { method: "GET", path: "/v1/sprites/{id}/services", activity: "spriteApplyServices" },
-  { method: "PUT", path: "/v1/sprites/{id}/services/{svc}", activity: "spriteApplyServices" },
-  { method: "POST", path: "/v1/sprites/{id}/services/{svc}/start", activity: "spriteApplyServices" },
+  // Services (./sprite-config.ts, ./sprite-services.ts)
+  { method: "GET", path: "/v1/sprites/{id}/services", activity: "spriteApplyServices, spriteServiceList" },
+  { method: "GET", path: "/v1/sprites/{id}/services/{svc}", activity: "spriteServiceGet" },
+  { method: "PUT", path: "/v1/sprites/{id}/services/{svc}", activity: "spriteApplyServices, spriteServiceCreate" },
+  { method: "POST", path: "/v1/sprites/{id}/services/{svc}/start", activity: "spriteApplyServices, spriteServiceStart" },
+  { method: "POST", path: "/v1/sprites/{id}/services/{svc}/stop", activity: "spriteServiceStop" },
   // Keep-alive tasks (./sprite-tasks.ts)
   { method: "POST", path: "/v1/sprites/{id}/tasks", activity: "spriteTaskCreate" },
   { method: "PUT", path: "/v1/sprites/{id}/tasks/{name}", activity: "spriteTaskRefresh" },

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

@@ -1,5 +1,5 @@
 import { emulatorLifecycle, type EmulatorCapability, type EmulatorSpec } from "@intentius/chant/op";
-import { SPRITZER_IMAGE } from "./emulator-images";
+import { SPRITZER_IMAGE, SPRITZER_CONTAINER_IMAGE } from "./emulator-images";
 
 export interface SpritesUpArgs {
   /** Container name. Default: `chant-spritzer`. */
@@ -53,3 +53,54 @@ export const spritesUp = (args: SpritesUpArgs = {}, signal?: AbortSignal): Promi
 /** Stop and remove the local spritzer container (no-op if already gone). */
 export const spritesDown = (args: SpritesDownArgs = {}, signal?: AbortSignal): Promise<void> =>
   spritzer.down(args, signal);
+
+// ── Container exec mode (#2711, INTENTIUS/spritzer#22) ─────────────────────────
+//
+// A second, distinct spritzer lifecycle: `SPRITZER_EXEC=container` with the
+// Docker runtime, so each sprite it makes is a real container — the mode the
+// Services CRUD activities (`./sprite-services.ts`) and `spriteUrl` need (real
+// processes, a real sprite URL), and that `SPRITZER_SPEC` above (interpreter
+// mode, the default everything else tests against) does not run. The Docker
+// socket is mounted read-write so spritzer can create/exec/delete sibling
+// sprite containers through it (docker-outside-of-docker); no port publishing
+// is needed for the sprites themselves — spritzer reaches them by exec, and
+// proxies their URL (`/s/{name}/...`) through the one published port.
+
+/** Container exec mode spritzer, pinned to {@link SPRITZER_CONTAINER_IMAGE} (0.6.0, the first release with this mode). */
+export const SPRITZER_CONTAINER_SPEC: EmulatorSpec = {
+  name: "chant-spritzer-container",
+  image: SPRITZER_CONTAINER_IMAGE,
+  containerPort: 4290,
+  healthPath: "/_spritzer/health",
+  runArgs: [
+    // The image runs as `nonroot` by default, which cannot open a
+    // group/other-unwritable host socket — root inside the container is
+    // still an unprivileged Linux user account relative to the host/Docker
+    // Desktop VM, no different from any other `docker run` that mounts the
+    // socket.
+    "--user",
+    "root",
+    "-e",
+    "SPRITZER_EXEC=container",
+    "-e",
+    "SPRITZER_RUNTIME=docker",
+    "-v",
+    "/var/run/docker.sock:/var/run/docker.sock",
+  ],
+  upstream: { repo: "intentius/spritzer" },
+};
+
+const spritzerContainer = emulatorLifecycle(SPRITZER_CONTAINER_SPEC);
+
+export const spritesContainerRunCommand = (args: SpritesUpArgs = {}): string => spritzerContainer.runCommand(args);
+export const spritesContainerExistsCommand = spritzerContainer.existsCommand;
+export const spritesContainerRmCommand = spritzerContainer.rmCommand;
+export const spritesContainerHealthUrl = spritzerContainer.healthUrl;
+
+/** Boot a local spritzer in container exec mode (Docker runtime) and return its endpoint. */
+export const spritesContainerUp = (args: SpritesUpArgs = {}, signal?: AbortSignal): Promise<{ endpoint: string }> =>
+  spritzerContainer.up(args, signal);
+
+/** Stop and remove the local container-exec-mode spritzer (no-op if already gone). Sprite containers it made are the caller's to clean up (see the integration test). */
+export const spritesContainerDown = (args: SpritesDownArgs = {}, signal?: AbortSignal): Promise<void> =>
+  spritzerContainer.down(args, signal);

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

@@ -41,7 +41,10 @@ interface StoredService {
   dir?: string;
   needs?: string[];
   http_port?: number;
-  state: { name: string; pid: number; status: string; started_at?: string };
+  state: { name: string; pid: number; status: string; started_at?: string; error?: string };
+  /** Synthetic log lines (#2711) — the fake runs no real process, so `logs` is a
+   * scripted trail of lifecycle events, enough to exercise `spriteServiceLogs`. */
+  logs: string[];
 }
 
 interface SpriteState {
@@ -244,6 +247,11 @@ export function createSpritesFake(): Promise<{ url: string; close(): Promise<voi
       res.writeHead(status, { "content-type": "application/json" });
       res.end(JSON.stringify(body ?? {}));
     };
+    // No-body reply (real Sprites' 204s carry no content and no body): #2719.
+    const sendEmpty = (status: number): void => {
+      res.writeHead(status);
+      res.end();
+    };
     // 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" });
@@ -311,13 +319,14 @@ export function createSpritesFake(): Promise<{ url: string; close(): Promise<voi
       if (method === "POST") {
         const body = ((await readBody(req)) ?? {}) as { rules?: Array<{ domain: string; action: string }> };
         sprite.netPolicy = body.rules ?? [];
-        return send(200, { rules: sprite.netPolicy });
+        // 204 with no body — matches every official SDK and wisp (#2719).
+        return sendEmpty(204);
       }
       return send(404, { error: `not found: ${method} ${path}` });
     }
 
-    // Services: /v1/sprites/{id}/services[/{svc}[/start|stop|restart]].
-    const svcm = path.match(/^\/v1\/sprites\/([^/]+)\/services(?:\/([^/]+)(\/start|\/stop|\/restart)?)?\/?$/);
+    // Services: /v1/sprites/{id}/services[/{svc}[/start|stop|restart|logs]].
+    const svcm = path.match(/^\/v1\/sprites\/([^/]+)\/services(?:\/([^/]+)(\/start|\/stop|\/restart|\/logs)?)?\/?$/);
     if (svcm) {
       const id = decodeURIComponent(svcm[1]);
       const svc = svcm[2] ? decodeURIComponent(svcm[2]) : undefined;
@@ -328,15 +337,30 @@ export function createSpritesFake(): Promise<{ url: string; close(): Promise<voi
       // GET /services — list.
       if (method === "GET" && !svc) return send(200, Object.values(sprite.services));
 
+      // GET /services/{svc}/logs — the tail as NDJSON (#2711).
+      if (method === "GET" && svc && action === "/logs") {
+        const s = sprite.services[svc];
+        if (!s) return send(404, { error: `no service ${svc}` });
+        const n = Number(url.searchParams.get("lines"));
+        const tail = Number.isFinite(n) && n > 0 ? s.logs.slice(-n) : s.logs;
+        return sendNdjson(
+          200,
+          [...tail.map((data) => ({ type: "stdout", data })), { type: "complete", data: `${svc} log tail` }],
+        );
+      }
+
       if (svc && !action) {
         // GET /services/{svc}
         if (method === "GET") {
           const s = sprite.services[svc];
           return s ? send(200, s) : send(404, { error: `no service ${svc}` });
         }
-        // PUT /services/{svc} — create or update.
+        // PUT /services/{svc} — create-or-update, then start (#2711: real
+        // Sprites/spritzer's PUT both defines and starts the service).
         if (method === "PUT") {
-          const b = ((await readBody(req)) ?? {}) as Omit<StoredService, "name" | "state">;
+          const b = ((await readBody(req)) ?? {}) as Omit<StoredService, "name" | "state" | "logs">;
+          const prev = sprite.services[svc];
+          const started = new Date().toISOString();
           sprite.services[svc] = {
             name: svc,
             cmd: b.cmd,
@@ -345,18 +369,26 @@ export function createSpritesFake(): Promise<{ url: string; close(): Promise<voi
             dir: b.dir,
             needs: b.needs,
             http_port: b.http_port,
-            state: sprite.services[svc]?.state ?? { name: svc, pid: 0, status: "stopped" },
+            state: { name: svc, pid: 4321, status: "running", started_at: started },
+            logs: [...(prev?.logs ?? []), `${svc} started (pid 4321)`],
           };
           return send(200, sprite.services[svc]);
         }
+        // DELETE /services/{svc} — idempotent; a 404 means already gone (#2711).
+        if (method === "DELETE") {
+          if (!(svc in sprite.services)) return send(404, { error: `no service ${svc}` });
+          delete sprite.services[svc];
+          return send(200, {});
+        }
       }
 
       // POST /services/{svc}/start|stop|restart — NDJSON, flips status.
-      if (method === "POST" && svc && action) {
+      if (method === "POST" && svc && (action === "/start" || action === "/stop" || action === "/restart")) {
         const s = sprite.services[svc];
         if (!s) return send(404, { error: `no service ${svc}` });
         const stopped = action === "/stop";
         s.state = { name: svc, pid: stopped ? 0 : 4321, status: stopped ? "stopped" : "running", started_at: new Date().toISOString() };
+        s.logs.push(`${svc} ${stopped ? "stopping" : "started"}`);
         return sendNdjson(200, [
           { type: stopped ? "stopping" : "started", data: `${svc} ${stopped ? "stopping" : "started"}` },
           { type: "complete", data: `${svc} ${action.slice(1)} complete` },
@@ -365,6 +397,23 @@ export function createSpritesFake(): Promise<{ url: string; close(): Promise<voi
       return send(404, { error: `not found: ${method} ${path}` });
     }
 
+    // The sprite URL proxy: /s/{id}[/...] (#2711). Real spritzer routes this to
+    // whatever listens on the `http_port` service's port; the fake has no real
+    // process, so it answers 200 when such a service is `running` and 503
+    // ("nothing is answering", matching spritzer's real error) otherwise —
+    // enough for `spriteUrl`'s wait-for-200 and the stop/start round trip.
+    const sm = path.match(/^\/s\/([^/]+)(?:\/.*)?$/);
+    if (sm) {
+      const id = decodeURIComponent(sm[1]);
+      const sprite = sprites.get(id);
+      if (!sprite || sprite.status === "destroyed") return send(404, { error: `no sprite ${id}` });
+      const serving = Object.values(sprite.services).find((s) => s.http_port !== undefined && s.state.status === "running");
+      if (serving) return send(200, { ok: true, service: serving.name });
+      res.writeHead(503, { "content-type": "application/json", "retry-after": "2" });
+      res.end(JSON.stringify({ error: `sprite ${id}: nothing is answering on its url port` }));
+      return;
+    }
+
     // Filesystem API: /v1/sprites/{id}/fs/{read|write|list|delete}. read/write
     // move raw bytes; list/delete use query params + JSON/empty responses.
     const fsm = path.match(/^\/v1\/sprites\/([^/]+)\/fs\/(read|write|list|delete)\/?$/);

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

@@ -1,6 +1,7 @@
 import { describe, test, expect } from "vitest";
 import {
   resolveSpritesEndpoint,
+  resolveSpritesToken,
   DEFAULT_SPRITES_BASE_URL,
   accumulateExecFrames,
   parseCheckpointNdjson,
@@ -13,6 +14,8 @@ import {
   spriteRestore,
   listCheckpoints,
   spriteDestroy,
+  spriteDelete,
+  spriteUrl,
   type SpritesHttp,
   type Checkpoint,
 } from "./sprites";
@@ -141,6 +144,50 @@ describe("resolveSpritesEndpoint (S3)", () => {
   test("default is real Sprites", () => {
     expect(resolveSpritesEndpoint({}, {} as NodeJS.ProcessEnv)).toBe(DEFAULT_SPRITES_BASE_URL);
   });
+
+  // #2711 — the studio and wisp call it SPRITES_API_URL.
+  test("SPRITES_API_URL alias when SPRITES_BASE_URL is unset", () => {
+    expect(resolveSpritesEndpoint({}, { SPRITES_API_URL: "http://alias:9000" } as NodeJS.ProcessEnv)).toBe(
+      "http://alias:9000",
+    );
+  });
+
+  test("SPRITES_BASE_URL wins over SPRITES_API_URL", () => {
+    expect(
+      resolveSpritesEndpoint(
+        {},
+        { SPRITES_BASE_URL: "http://base:1", SPRITES_API_URL: "http://alias:2" } as NodeJS.ProcessEnv,
+      ),
+    ).toBe("http://base:1");
+  });
+});
+
+describe("resolveSpritesToken (#2711)", () => {
+  test("explicit arg wins", () => {
+    expect(resolveSpritesToken("arg-token", { SPRITES_API_TOKEN: "env" } as NodeJS.ProcessEnv)).toBe("arg-token");
+  });
+
+  test("SPRITES_API_TOKEN env when no arg", () => {
+    expect(resolveSpritesToken(undefined, { SPRITES_API_TOKEN: "env-token" } as NodeJS.ProcessEnv)).toBe(
+      "env-token",
+    );
+  });
+
+  test("SPRITE_TOKEN alias when SPRITES_API_TOKEN is unset", () => {
+    expect(resolveSpritesToken(undefined, { SPRITE_TOKEN: "alias-token" } as NodeJS.ProcessEnv)).toBe(
+      "alias-token",
+    );
+  });
+
+  test("SPRITES_API_TOKEN wins over SPRITE_TOKEN", () => {
+    expect(
+      resolveSpritesToken(undefined, { SPRITES_API_TOKEN: "orig", SPRITE_TOKEN: "alias" } as NodeJS.ProcessEnv),
+    ).toBe("orig");
+  });
+
+  test("undefined when nothing is set", () => {
+    expect(resolveSpritesToken(undefined, {} as NodeJS.ProcessEnv)).toBeUndefined();
+  });
 });
 
 // ── Command tokenizing + exec WS url ──────────────────────────────────────────
@@ -263,6 +310,61 @@ describe("spriteDestroy", () => {
   });
 });
 
+describe("spriteDelete (#2711)", () => {
+  test("is spriteDestroy under another name — same DELETE, same idempotence", async () => {
+    expect(spriteDelete).toBe(spriteDestroy);
+    const { http, calls } = recorder(() => ({ status: 200, text: "{}" }));
+    await spriteDelete({ 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");
+  });
+});
+
+describe("spriteUrl (#2711)", () => {
+  test("GETs /v1/sprites/{id} and returns its url", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: JSON.stringify({ url: "http://h/s/task-1" }) }));
+    const res = await spriteUrl({ id: "task-1", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual({ url: "http://h/s/task-1" });
+    expect(calls[0].method).toBe("GET");
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1");
+  });
+
+  test("throws when the sprite has no url", async () => {
+    const { http } = recorder(() => ({ status: 200, text: "{}" }));
+    await expect(spriteUrl({ id: "task-1", endpoint: "http://x" }, undefined, http)).rejects.toThrow(/no url/);
+  });
+
+  test("with a path: returns immediately once the check answers 2xx", async () => {
+    let checks = 0;
+    const { http, calls } = recorder((method, url) => {
+      if (method === "GET" && url === "http://x/v1/sprites/task-1") {
+        return { status: 200, text: JSON.stringify({ url: "http://h/s/task-1" }) };
+      }
+      checks += 1;
+      return { status: checks < 2 ? 503 : 200, text: "" };
+    });
+    const res = await spriteUrl(
+      { id: "task-1", endpoint: "http://x", path: "/", intervalMs: 1 },
+      undefined,
+      http,
+    );
+    expect(res).toEqual({ url: "http://h/s/task-1" });
+    expect(checks).toBe(2); // one 503, then 200
+    expect(calls.at(-1)?.url).toBe("http://h/s/task-1/");
+  });
+
+  test("with a path: throws once timeoutMs elapses without a match", async () => {
+    const { http } = recorder((method, url) =>
+      url === "http://x/v1/sprites/task-1"
+        ? { status: 200, text: JSON.stringify({ url: "http://h/s/task-1" }) }
+        : { status: 503, text: "nothing is answering" },
+    );
+    await expect(
+      spriteUrl({ id: "task-1", endpoint: "http://x", path: "/", timeoutMs: 5, intervalMs: 1 }, undefined, http),
+    ).rejects.toThrow(/did not answer/);
+  });
+});
+
 // ── Bearer header on the default client ───────────────────────────────────────
 
 describe("defaultSpritesHttp bearer header", () => {

package/src/op/activities/sprites.ts

@@ -20,6 +20,13 @@
  * 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.
+ *
+ * #2711: the studio and wisp's own docs call these `SPRITES_API_URL` and
+ * `SPRITE_TOKEN` rather than `SPRITES_BASE_URL`/`SPRITES_API_TOKEN`. Both
+ * pairs are accepted — `resolveSpritesEndpoint`/`resolveSpritesToken` read the
+ * alias when the original name is unset, with the original always winning
+ * when both are present, so an existing deployment is never surprised by the
+ * alias taking over.
  */
 
 // `ws` is loaded inside spriteExec, not at the top. It is a CommonJS package
@@ -27,6 +34,8 @@
 // ESM, where that require throws. The top-level import put it on the path of
 // every project that imports the lexicon and needs the run fallback (#2613).
 
+import { sleep } from "@intentius/chant/op";
+
 export const DEFAULT_SPRITES_BASE_URL = "https://api.sprites.dev";
 
 // ── Pure helpers (unit-testable without http/ws) ──────────────────────────────
@@ -41,15 +50,27 @@ export function resolveSpritesEndpoint(
   args: { endpoint?: string } = {},
   env: NodeJS.ProcessEnv = process.env,
 ): string {
-  const base = args.endpoint || env.SPRITES_BASE_URL || DEFAULT_SPRITES_BASE_URL;
+  const base = args.endpoint || env.SPRITES_BASE_URL || env.SPRITES_API_URL || DEFAULT_SPRITES_BASE_URL;
   return base.replace(/\/$/, "");
 }
 
+/**
+ * Resolve the bearer token (#2711): an explicit `token` arg wins, then
+ * `SPRITES_API_TOKEN`, then its alias `SPRITE_TOKEN`. Pure — mirrors
+ * `resolveSpritesEndpoint`.
+ */
+export function resolveSpritesToken(
+  token: string | undefined = undefined,
+  env: NodeJS.ProcessEnv = process.env,
+): string | undefined {
+  return token ?? env.SPRITES_API_TOKEN ?? env.SPRITE_TOKEN;
+}
+
 const spritesUrl = (base: string): string => `${base}/v1/sprites`;
-const spriteUrl = (base: string, id: string): string => `${spritesUrl(base)}/${encodeURIComponent(id)}`;
+const spriteResourceUrl = (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 spriteCheckpointUrl = (base: string, id: string): string => `${spriteResourceUrl(base, id)}/checkpoint`;
+const spriteCheckpointsUrl = (base: string, id: string): string => `${spriteResourceUrl(base, id)}/checkpoints`;
 const spriteCheckpointRestoreUrl = (base: string, id: string, cp: string): string =>
   `${spriteCheckpointsUrl(base, id)}/${encodeURIComponent(cp)}/restore`;
 
@@ -354,7 +375,7 @@ export function defaultSpritesHttp(token?: string, fetchImpl: typeof fetch = fet
   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;
+    const tok = resolveSpritesToken(token);
     if (tok) h["authorization"] = `Bearer ${tok}`;
     const res = await fetchImpl(url, {
       method,
@@ -393,7 +414,7 @@ export async function spriteCreate(
 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 token = resolveSpritesToken(args.token);
   const headers: Record<string, string> = {};
   if (token) headers.Authorization = `Bearer ${token}`;
   const { default: WebSocket } = await import("ws");
@@ -522,10 +543,90 @@ export async function spriteDestroy(
   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);
+  const res = await http("DELETE", spriteResourceUrl(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 {};
 }
+
+/**
+ * Delete the sprite (#2711) — the same idempotent `DELETE /v1/sprites/{id}` as
+ * `spriteDestroy`, under the name spritzer, wisp and the other lexicons'
+ * delete activities (`awsDelete`, `gcpDelete`, `azDelete`) use. A literal
+ * alias, not a reimplementation, so the two names can never drift: an Op
+ * authored against either resolves to the same call. `spriteDestroy` stays —
+ * it is the name every existing Op, example and the `op-verb-class` registry
+ * already depend on.
+ */
+export const spriteDelete = spriteDestroy;
+export type SpriteDeleteArgs = SpriteDestroyArgs;
+
+export interface SpriteUrlArgs {
+  /** Target sprite id. */
+  id: string;
+  /**
+   * Wait until this path on the sprite's URL answers, instead of returning
+   * the URL immediately. Unset (default): no wait, just resolve the URL.
+   */
+  path?: string;
+  /** Expected status while waiting. Default: any 2xx. */
+  status?: number;
+  /** Max time to wait for `path` to answer, ms. Default: `10000`. */
+  timeoutMs?: number;
+  /** Delay between polls, ms. Default: `500`. */
+  intervalMs?: number;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteUrlResult {
+  url: string;
+}
+
+/**
+ * Resolve the sprite's URL (#2711) — `spriteCreate` returns it too, but
+ * nothing until now exposed it on its own (for a later phase that only has
+ * the sprite `id`) or waited on it. `GET /v1/sprites/{id}` for the URL; with
+ * `path` set, polls `GET {url}{path}` until `status` (default any 2xx) or
+ * `timeoutMs` runs out — the box's door/hud/chud services take a moment to
+ * bind their `http_port` after `spriteServiceStart`.
+ */
+export async function spriteUrl(
+  args: SpriteUrlArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteUrlResult> {
+  const base = resolveSpritesEndpoint(args);
+  const res = await http("GET", spriteResourceUrl(base, args.id), undefined, undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} url lookup failed (${res.status}): ${res.text}`);
+  const url = (safeJson(res.text) as { url?: string } | undefined)?.url;
+  if (!url) throw new Error(`sprite ${args.id} has no url`);
+
+  if (args.path !== undefined) {
+    const timeoutMs = args.timeoutMs ?? 10_000;
+    const intervalMs = args.intervalMs ?? 500;
+    const target = `${url}${args.path}`;
+    const deadline = Date.now() + timeoutMs;
+    let lastErr = "";
+    for (;;) {
+      if (signal?.aborted) throw new Error(`sprite ${args.id} url wait aborted`);
+      try {
+        const check = await http("GET", target, undefined, undefined, signal);
+        const ok = args.status !== undefined ? check.status === args.status : check.status >= 200 && check.status < 300;
+        if (ok) {
+          console.log(`url: sprite/${args.id} answers on ${target} (${check.status})`);
+          return { url };
+        }
+        lastErr = `status ${check.status} (want ${args.status ?? "2xx"})`;
+      } catch (e) {
+        lastErr = e instanceof Error ? e.message : String(e);
+      }
+      if (Date.now() >= deadline) throw new Error(`sprite ${args.id} url ${target} did not answer: ${lastErr}`);
+      await sleep(intervalMs, signal);
+    }
+  }
+
+  return { url };
+}