@intentius/chant-lexicon-fly 0.89.0 → 0.90.0

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

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)\/?$/);