@intentius/chant-lexicon-fly 0.89.0 → 0.91.0

package/src/op/activities/sprite-services.docker.integration.test.ts

@@ -0,0 +1,87 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import { spriteCreate, spriteDelete, spriteUrl } from "./sprites";
+import { spriteServiceCreate, spriteServiceStop, spriteServiceStart } from "./sprite-services";
+import { spritesContainerUp, spritesContainerDown } from "./sprites-emulator";
+
+// Acceptance (#2711) against the REAL spritzer image in container exec mode
+// (SPRITZER_EXEC=container, SPRITZER_RUNTIME=docker — INTENTIUS/spritzer#22):
+// create a sprite, create a service running `python3 -m http.server 8080`,
+// wait for its URL to answer, stop it (the URL stops answering), start it
+// again (the URL answers again), delete the sprite. `sprite-services.test.ts`
+// runs the same scenario against the in-process fake, no Docker. 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, same convention as the other docker tests
+// here.
+//
+// Cleanup: the sprite container spritzer makes (`spritzer-<name>`) is removed
+// by `spriteDelete` before spritzer itself comes down; `docker ps -a` after
+// this suite should show neither.
+
+const CONTAINER = "chant-spritzer-container-it";
+const PORT = 4294;
+const SPRITE = "chant-2711-web";
+
+let available = false;
+let endpoint = "";
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  if (process.env.CI && !process.env.SPRITES_DOCKER) {
+    available = false;
+    return;
+  }
+  try {
+    const up = await spritesContainerUp({ name: CONTAINER, port: PORT, timeoutMs: 60_000 });
+    endpoint = up.endpoint;
+    prevBaseUrl = process.env.SPRITES_BASE_URL;
+    process.env.SPRITES_BASE_URL = endpoint;
+    available = true;
+  } catch {
+    available = false;
+  }
+}, 90_000);
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  if (available) {
+    // Idempotent: already deleted by the test on the happy path. A failed
+    // test still leaves no sprite container behind.
+    await spriteDelete({ id: SPRITE }).catch(() => {});
+    await spritesContainerDown({ name: CONTAINER });
+  }
+}, 30_000);
+
+describe("sprite services against real spritzer 0.6.0, container mode (#2711)", () => {
+  test("create → url waits and answers → stop → url stops answering → start → answers again → delete", async (ctx) => {
+    if (!available) ctx.skip();
+
+    await spriteCreate({ name: SPRITE });
+
+    await spriteServiceCreate({
+      id: SPRITE,
+      name: "web",
+      cmd: "python3",
+      args: ["-m", "http.server", "8080"],
+      http_port: 8080,
+      durationMs: 1000,
+    });
+
+    const { url } = await spriteUrl({ id: SPRITE, path: "/", timeoutMs: 20_000, intervalMs: 500 });
+    expect(url).toContain(SPRITE);
+
+    await spriteServiceStop({ id: SPRITE, name: "web" });
+    // The process is gone; nothing answers on the sprite URL any more.
+    const afterStop = await fetch(`${url}/`);
+    expect(afterStop.status).toBe(503);
+
+    await spriteServiceStart({ id: SPRITE, name: "web" });
+    const { url: url2 } = await spriteUrl({ id: SPRITE, path: "/", timeoutMs: 20_000, intervalMs: 500 });
+    expect(url2).toBe(url);
+
+    await spriteDelete({ id: SPRITE });
+    const afterDelete = await fetch(`${endpoint}/v1/sprites/${SPRITE}`);
+    expect(afterDelete.status).toBe(404);
+  }, 120_000);
+});

package/src/op/activities/sprite-services.test.ts

@@ -0,0 +1,263 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import type { SpritesHttp } from "./sprites";
+import { spriteCreate as createImpl } from "./sprites";
+import { createSpritesFake } from "./sprites-fake";
+import {
+  spriteServiceCreate,
+  spriteServiceGet,
+  spriteServiceList,
+  spriteServiceStart,
+  spriteServiceStop,
+  spriteServiceDelete,
+  spriteServiceLogs,
+  spriteServiceCreateBody,
+  parseServiceLogNdjson,
+} from "./sprite-services";
+
+// 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 }> = [];
+  const http: SpritesHttp = async (method, url, body) => {
+    calls.push({ method, url, body });
+    return answer(method, url, body);
+  };
+  return { http, calls };
+}
+
+const running = (name: string, extra: Record<string, unknown> = {}) =>
+  JSON.stringify({ name, cmd: "run", state: { name, status: "running", pid: 4321 }, ...extra });
+
+// ── Pure helpers ────────────────────────────────────────────────────────────
+
+describe("spriteServiceCreateBody", () => {
+  test("omits undefined optional fields", () => {
+    expect(spriteServiceCreateBody({ id: "s", name: "web", cmd: "run-web" })).toEqual({ cmd: "run-web" });
+  });
+
+  test("includes every field that is set", () => {
+    expect(
+      spriteServiceCreateBody({
+        id: "s",
+        name: "web",
+        cmd: "python3",
+        args: ["-m", "http.server", "8080"],
+        env: { PORT: "8080" },
+        dir: "/app",
+        needs: ["db"],
+        http_port: 8080,
+      }),
+    ).toEqual({
+      cmd: "python3",
+      args: ["-m", "http.server", "8080"],
+      env: { PORT: "8080" },
+      dir: "/app",
+      needs: ["db"],
+      http_port: 8080,
+    });
+  });
+});
+
+describe("parseServiceLogNdjson", () => {
+  test("keeps stdout/stderr data in order, drops the complete marker", () => {
+    const text = [
+      JSON.stringify({ type: "started", data: "web started (pid 1)" }),
+      JSON.stringify({ type: "stdout", data: "Serving on 0.0.0.0:8080" }),
+      JSON.stringify({ type: "complete", data: "ignored" }),
+    ].join("\n");
+    expect(parseServiceLogNdjson(text)).toEqual(["web started (pid 1)", "Serving on 0.0.0.0:8080"]);
+  });
+
+  test("skips blank and unparseable lines", () => {
+    expect(parseServiceLogNdjson('\n{"type":"stdout","data":"a"}\n\nnot json\n')).toEqual(["a"]);
+  });
+});
+
+// ── Activity request shapes (injected SpritesHttp) ─────────────────────────
+
+describe("spriteServiceCreate", () => {
+  test("PUTs .../services/{name} with ?duration, then GETs the definitive state", async () => {
+    const { http, calls } = recorder((method) => ({
+      status: method === "PUT" ? 200 : 200,
+      text: method === "PUT" ? '{"type":"complete"}' : running("web", { http_port: 8080 }),
+    }));
+    const res = await spriteServiceCreate(
+      { id: "task-1", name: "web", cmd: "python3", args: ["-m", "http.server", "8080"], http_port: 8080, endpoint: "http://x" },
+      undefined,
+      http,
+    );
+    expect(res.state.status).toBe("running");
+    expect(calls[0].method).toBe("PUT");
+    expect(calls[0].url).toBe("http://x/v1/sprites/task-1/services/web?duration=500ms");
+    expect(calls[0].body).toEqual({ cmd: "python3", args: ["-m", "http.server", "8080"], http_port: 8080 });
+    expect(calls[1].method).toBe("GET");
+    expect(calls[1].url).toBe("http://x/v1/sprites/task-1/services/web");
+  });
+
+  test("a custom durationMs is passed through as ms", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: running("web") }));
+    await spriteServiceCreate({ id: "t", name: "web", cmd: "x", durationMs: 2000, endpoint: "http://x" }, undefined, http);
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web?duration=2000ms");
+  });
+
+  test("throws when the resulting state is failed", async () => {
+    const { http } = recorder((method) => ({
+      status: 200,
+      text: method === "PUT"
+        ? '{"type":"error","data":"boom"}'
+        : JSON.stringify({ name: "web", cmd: "x", state: { name: "web", status: "failed", error: "exec: not found" } }),
+    }));
+    await expect(
+      spriteServiceCreate({ id: "t", name: "web", cmd: "nope", endpoint: "http://x" }, undefined, http),
+    ).rejects.toThrow(/failed to start.*exec: not found/);
+  });
+
+  test("throws on a non-2xx PUT", async () => {
+    const { http } = recorder(() => ({ status: 400, text: "bad request" }));
+    await expect(
+      spriteServiceCreate({ id: "t", name: "web", cmd: "x", endpoint: "http://x" }, undefined, http),
+    ).rejects.toThrow(/create failed \(400\)/);
+  });
+});
+
+describe("spriteServiceGet", () => {
+  test("GETs .../services/{name}", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: running("web") }));
+    const res = await spriteServiceGet({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(res.state.status).toBe("running");
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web");
+  });
+});
+
+describe("spriteServiceList", () => {
+  test("GETs .../services and returns the array", async () => {
+    const list = [JSON.parse(running("web")), JSON.parse(running("db"))];
+    const { http, calls } = recorder(() => ({ status: 200, text: JSON.stringify(list) }));
+    const res = await spriteServiceList({ id: "t", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual(list);
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services");
+  });
+});
+
+describe("spriteServiceStart / spriteServiceStop", () => {
+  test("start POSTs .../start?duration and re-GETs", async () => {
+    const { http, calls } = recorder((method) => ({
+      status: 200,
+      text: method === "POST" ? '{"type":"complete"}' : running("web"),
+    }));
+    const res = await spriteServiceStart({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(res.state.status).toBe("running");
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/start?duration=500ms");
+  });
+
+  test("stop POSTs .../stop and re-GETs", async () => {
+    const { http, calls } = recorder((method) => ({
+      status: 200,
+      text: method === "POST"
+        ? '{"type":"complete"}'
+        : JSON.stringify({ name: "web", cmd: "x", state: { name: "web", status: "stopped" } }),
+    }));
+    const res = await spriteServiceStop({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(res.state.status).toBe("stopped");
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/stop");
+  });
+
+  test("stop passes ?timeout when timeoutMs is set", async () => {
+    const { http, calls } = recorder((method) => ({
+      status: 200,
+      text: method === "POST" ? "{}" : running("web"),
+    }));
+    await spriteServiceStop({ id: "t", name: "web", timeoutMs: 3000, endpoint: "http://x" }, undefined, http);
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/stop?timeout=3000ms");
+  });
+});
+
+describe("spriteServiceDelete", () => {
+  test("DELETEs .../services/{name}", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: "{}" }));
+    await spriteServiceDelete({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(calls[0].method).toBe("DELETE");
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web");
+  });
+
+  test("a 404 is idempotent, not an error", async () => {
+    const { http } = recorder(() => ({ status: 404, text: "gone" }));
+    await expect(spriteServiceDelete({ id: "t", name: "web", endpoint: "http://x" }, undefined, http)).resolves.toEqual({});
+  });
+});
+
+describe("spriteServiceLogs", () => {
+  test("GETs .../logs and returns the parsed tail", async () => {
+    const { http, calls } = recorder(() => ({
+      status: 200,
+      text: [JSON.stringify({ type: "stdout", data: "line 1" }), JSON.stringify({ type: "complete" })].join("\n"),
+    }));
+    const res = await spriteServiceLogs({ id: "t", name: "web", endpoint: "http://x" }, undefined, http);
+    expect(res).toEqual({ lines: ["line 1"] });
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/logs");
+  });
+
+  test("passes ?lines when set", async () => {
+    const { http, calls } = recorder(() => ({ status: 200, text: "" }));
+    await spriteServiceLogs({ id: "t", name: "web", lines: 5, endpoint: "http://x" }, undefined, http);
+    expect(calls[0].url).toBe("http://x/v1/sprites/t/services/web/logs?lines=5");
+  });
+});
+
+// ── End to end against the in-process fake (S7, no Docker) ────────────────
+//
+// The acceptance scenario from #2711, offline: create a sprite, create a
+// service with http_port, list/get it, stop and start it, delete it. The
+// docker-gated `sprite-services.docker.integration.test.ts` runs the same
+// scenario against real spritzer 0.6.0 in container mode.
+
+let fake: { url: string; close(): Promise<void> };
+let prevBaseUrl: string | undefined;
+
+beforeAll(async () => {
+  fake = await createSpritesFake();
+  prevBaseUrl = process.env.SPRITES_BASE_URL;
+  process.env.SPRITES_BASE_URL = fake.url;
+});
+
+afterAll(async () => {
+  if (prevBaseUrl === undefined) delete process.env.SPRITES_BASE_URL;
+  else process.env.SPRITES_BASE_URL = prevBaseUrl;
+  await fake?.close();
+});
+
+describe("sprite services against the in-process fake (#2711)", () => {
+  test("create, get, list, stop, start, delete", async () => {
+    await createImpl({ name: "svc-fake-1" });
+
+    const created = await spriteServiceCreate({
+      id: "svc-fake-1",
+      name: "web",
+      cmd: "python3",
+      args: ["-m", "http.server", "8080"],
+      http_port: 8080,
+    });
+    expect(created.state.status).toBe("running");
+
+    const got = await spriteServiceGet({ id: "svc-fake-1", name: "web" });
+    expect(got.name).toBe("web");
+    expect(got.http_port).toBe(8080);
+
+    const list = await spriteServiceList({ id: "svc-fake-1" });
+    expect(list.map((s) => s.name)).toEqual(["web"]);
+
+    const stopped = await spriteServiceStop({ id: "svc-fake-1", name: "web" });
+    expect(stopped.state.status).toBe("stopped");
+
+    const restarted = await spriteServiceStart({ id: "svc-fake-1", name: "web" });
+    expect(restarted.state.status).toBe("running");
+
+    const logs = await spriteServiceLogs({ id: "svc-fake-1", name: "web" });
+    expect(logs.lines.length).toBeGreaterThan(0);
+
+    await spriteServiceDelete({ id: "svc-fake-1", name: "web" });
+    await expect(spriteServiceGet({ id: "svc-fake-1", name: "web" })).rejects.toThrow(/get failed \(404\)/);
+
+    // A second delete is idempotent.
+    await expect(spriteServiceDelete({ id: "svc-fake-1", name: "web" })).resolves.toEqual({});
+  });
+});

package/src/op/activities/sprite-services.ts

@@ -0,0 +1,311 @@
+/**
+ * Sprite Services activities (#2711) — imperative create/get/list/start/stop/
+ * delete/logs over a Sprite's background services, the surface a box's door,
+ * hud and chud run as long-lived services through (`sprite-env services`
+ * inside the sprite, `/v1/sprites/{id}/services/...` outside). Shared by the
+ * Sprites API, wisp (arugula-salad/wisp) and spritzer 0.6.0's container mode
+ * (INTENTIUS/spritzer#22).
+ *
+ * This is the imperative twin of `sprite-config.ts`'s `spriteApplyServices` —
+ * that one reconciles a whole desired service *set* (additive create-or-update,
+ * optionally started, no delete). These activities are the single-service
+ * primitives underneath it: create-and-start one service and watch it come
+ * up, inspect or list what's running, stop/start one by name, delete it, and
+ * read its log tail. An Op that provisions a box one service at a time (or
+ * needs delete, which `spriteApplyServices` doesn't expose) uses these
+ * directly; `spriteApplyServices` stays the batch-reconcile convenience on
+ * top of the same wire shapes.
+ *
+ * `spriteServiceCreate` is a `PUT` that both defines the service and starts
+ * it, streaming NDJSON progress (`started`, `stdout`, `stderr`, `exit`,
+ * `complete`) for a bounded `?duration` window (default 500ms — enough to
+ * surface an immediate failure, e.g. a missing binary, without holding the
+ * step open for spritzer's own 5s default). The stream is read to completion
+ * either way; the definitive result comes from a follow-up `GET` of the
+ * service (`spriteServiceGet`'s own logic), which throws if its `state.status`
+ * is `"failed"`. `spriteServiceStart` follows the same create-then-GET shape
+ * (`PUT` already started it; `start` is for a stopped service).
+ */
+
+import { resolveSpritesEndpoint, defaultSpritesHttp, type SpritesHttp } from "./sprites";
+
+// ── URL building (pure) ─────────────────────────────────────────────────────
+
+const servicesUrl = (base: string, id: string): string => `${base}/v1/sprites/${encodeURIComponent(id)}/services`;
+const serviceUrl = (base: string, id: string, name: string): string =>
+  `${servicesUrl(base, id)}/${encodeURIComponent(name)}`;
+const serviceLogsUrl = (base: string, id: string, name: string): string => `${serviceUrl(base, id, name)}/logs`;
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Shapes (wisp's guest API shapes, per spritzer's services.go) ───────────
+
+/** A service's live half. */
+export interface SpriteServiceState {
+  name: string;
+  /** `stopped` | `running` | `stopping` | `failed`. */
+  status: string;
+  pid?: number;
+  started_at?: string;
+  error?: string;
+  restart_count?: number;
+}
+
+/** The `GET`/`PUT` response shape: the definition with its state beside it. */
+export interface SpriteService {
+  name: string;
+  cmd: string;
+  args?: string[];
+  env?: Record<string, string>;
+  dir?: string;
+  /** Names of services that must be running first. */
+  needs?: string[];
+  /** Route the sprite's public URL to this port. Only one service may set it. */
+  http_port?: number;
+  state: SpriteServiceState;
+}
+
+export interface SpriteServiceCreateArgs {
+  /** Target sprite id. */
+  id: string;
+  /** Service name — the key every later call addresses it by. */
+  name: string;
+  cmd: string;
+  args?: string[];
+  env?: Record<string, string>;
+  dir?: string;
+  needs?: string[];
+  http_port?: number;
+  /**
+   * How long spritzer keeps streaming NDJSON after the start action
+   * succeeds, ms (`?duration`). Default: `500`. A crash past this window is
+   * caught by a later `spriteServiceGet`/`spriteUrl`, not this call.
+   */
+  durationMs?: number;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteServiceGetArgs {
+  id: string;
+  name: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteServiceListArgs {
+  id: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteServiceStartArgs {
+  id: string;
+  name: string;
+  /** Same as `spriteServiceCreate`'s `durationMs`. Default: `500`. */
+  durationMs?: number;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteServiceStopArgs {
+  id: string;
+  name: string;
+  /** Grace period before SIGKILL, ms (`?timeout`). Default: spritzer's own (10s). */
+  timeoutMs?: number;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteServiceDeleteArgs {
+  id: string;
+  name: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteServiceLogsArgs {
+  id: string;
+  name: string;
+  /** Tail length. Default: spritzer's own (100). */
+  lines?: number;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteServiceLogsResult {
+  /** The tail, one entry per log line, oldest first. */
+  lines: string[];
+}
+
+/** Build the `PUT` create-or-update body. Pure. */
+export function spriteServiceCreateBody(args: SpriteServiceCreateArgs): Record<string, unknown> {
+  return {
+    cmd: args.cmd,
+    ...(args.args !== undefined ? { args: args.args } : {}),
+    ...(args.env !== undefined ? { env: args.env } : {}),
+    ...(args.dir !== undefined ? { dir: args.dir } : {}),
+    ...(args.needs !== undefined ? { needs: args.needs } : {}),
+    ...(args.http_port !== undefined ? { http_port: args.http_port } : {}),
+  };
+}
+
+/**
+ * Parse a service log NDJSON body (`{type, data, timestamp, ...}` per line,
+ * terminated by a `complete` event) into a plain line tail — the `data` text
+ * of every non-`complete` event, in stream order. Pure.
+ */
+export function parseServiceLogNdjson(text: string): string[] {
+  const lines: string[] = [];
+  for (const raw of text.split("\n")) {
+    const t = raw.trim();
+    if (!t) continue;
+    const obj = safeJson(t) as { type?: string; data?: string } | undefined;
+    if (!obj || obj.type === "complete") continue;
+    if (typeof obj.data === "string") lines.push(obj.data);
+  }
+  return lines;
+}
+
+// ── Activities ───────────────────────────────────────────────────────────────
+
+/**
+ * Create (or replace) and start a service. `PUT /v1/sprites/{id}/services/{name}`,
+ * streamed as NDJSON for `?duration` (mapped from `durationMs`). The stream is
+ * read to completion, then a `GET` fetches the definitive state; a `"failed"`
+ * status throws with the agent's own error text.
+ */
+export async function spriteServiceCreate(
+  args: SpriteServiceCreateArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteService> {
+  const base = resolveSpritesEndpoint(args);
+  const durationMs = args.durationMs ?? 500;
+  const url = `${serviceUrl(base, args.id, args.name)}?duration=${durationMs}ms`;
+  const res = await http("PUT", url, spriteServiceCreateBody(args), undefined, signal);
+  if (res.status >= 300) {
+    throw new Error(`sprite ${args.id} service ${args.name} create failed (${res.status}): ${res.text}`);
+  }
+  const svc = await spriteServiceGet({ id: args.id, name: args.name, endpoint: args.endpoint, token: args.token }, signal, http);
+  if (svc.state.status === "failed") {
+    throw new Error(`sprite ${args.id} service ${args.name} failed to start: ${svc.state.error ?? "unknown error"}`);
+  }
+  console.log(`service: sprite/${args.id}/${args.name} ${svc.state.status} (${base})`);
+  return svc;
+}
+
+/** Get one service. `GET /v1/sprites/{id}/services/{name}`. */
+export async function spriteServiceGet(
+  args: SpriteServiceGetArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteService> {
+  const base = resolveSpritesEndpoint(args);
+  const res = await http("GET", serviceUrl(base, args.id, args.name), undefined, undefined, signal);
+  if (res.status >= 300) {
+    throw new Error(`sprite ${args.id} service ${args.name} get failed (${res.status}): ${res.text}`);
+  }
+  return (safeJson(res.text) as SpriteService | undefined) ?? ({ name: args.name, cmd: "", state: { name: args.name, status: "stopped" } } as SpriteService);
+}
+
+/** List every service on the sprite. `GET /v1/sprites/{id}/services`. */
+export async function spriteServiceList(
+  args: SpriteServiceListArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteService[]> {
+  const base = resolveSpritesEndpoint(args);
+  const res = await http("GET", servicesUrl(base, args.id), undefined, undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} service list failed (${res.status}): ${res.text}`);
+  const parsed = safeJson(res.text);
+  return Array.isArray(parsed) ? (parsed as SpriteService[]) : [];
+}
+
+/**
+ * Start a stopped service. `POST /v1/sprites/{id}/services/{name}/start`,
+ * streamed as NDJSON for `?duration`, then a `GET` for the definitive state
+ * (same shape as `spriteServiceCreate`).
+ */
+export async function spriteServiceStart(
+  args: SpriteServiceStartArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteService> {
+  const base = resolveSpritesEndpoint(args);
+  const durationMs = args.durationMs ?? 500;
+  const url = `${serviceUrl(base, args.id, args.name)}/start?duration=${durationMs}ms`;
+  const res = await http("POST", url, undefined, undefined, signal);
+  if (res.status >= 300) {
+    throw new Error(`sprite ${args.id} service ${args.name} start failed (${res.status}): ${res.text}`);
+  }
+  const svc = await spriteServiceGet({ id: args.id, name: args.name, endpoint: args.endpoint, token: args.token }, signal, http);
+  if (svc.state.status === "failed") {
+    throw new Error(`sprite ${args.id} service ${args.name} failed to start: ${svc.state.error ?? "unknown error"}`);
+  }
+  console.log(`service: sprite/${args.id}/${args.name} ${svc.state.status} (${base})`);
+  return svc;
+}
+
+/**
+ * Stop a running service (SIGTERM, then SIGKILL after the grace period).
+ * `POST /v1/sprites/{id}/services/{name}/stop`.
+ */
+export async function spriteServiceStop(
+  args: SpriteServiceStopArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteService> {
+  const base = resolveSpritesEndpoint(args);
+  const qs = args.timeoutMs !== undefined ? `?timeout=${args.timeoutMs}ms` : "";
+  const url = `${serviceUrl(base, args.id, args.name)}/stop${qs}`;
+  const res = await http("POST", url, undefined, undefined, signal);
+  if (res.status >= 300) {
+    throw new Error(`sprite ${args.id} service ${args.name} stop failed (${res.status}): ${res.text}`);
+  }
+  const svc = await spriteServiceGet({ id: args.id, name: args.name, endpoint: args.endpoint, token: args.token }, signal, http);
+  console.log(`service: sprite/${args.id}/${args.name} ${svc.state.status} (${base})`);
+  return svc;
+}
+
+/**
+ * Delete a service, stopping it first (idempotent; a 404 means it is already
+ * gone). `DELETE /v1/sprites/{id}/services/{name}`.
+ */
+export async function spriteServiceDelete(
+  args: SpriteServiceDeleteArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<Record<string, never>> {
+  const base = resolveSpritesEndpoint(args);
+  const res = await http("DELETE", serviceUrl(base, args.id, args.name), undefined, undefined, signal);
+  if (res.status >= 300 && res.status !== 404) {
+    throw new Error(`sprite ${args.id} service ${args.name} delete failed (${res.status}): ${res.text}`);
+  }
+  console.log(`deleted: sprite/${args.id}/${args.name}`);
+  return {};
+}
+
+/**
+ * Read a service's log tail. `GET /v1/sprites/{id}/services/{name}/logs`,
+ * parsed from NDJSON to a plain line array (`parseServiceLogNdjson`).
+ */
+export async function spriteServiceLogs(
+  args: SpriteServiceLogsArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<SpriteServiceLogsResult> {
+  const base = resolveSpritesEndpoint(args);
+  const qs = args.lines !== undefined ? `?lines=${args.lines}` : "";
+  const res = await http("GET", `${serviceLogsUrl(base, args.id, args.name)}${qs}`, undefined, undefined, signal);
+  if (res.status >= 300) {
+    throw new Error(`sprite ${args.id} service ${args.name} logs failed (${res.status}): ${res.text}`);
+  }
+  return { lines: parseServiceLogNdjson(res.text) };
+}