@intentius/chant-lexicon-fly 0.18.6 → 0.18.8

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

@@ -0,0 +1,217 @@
+/**
+ * Sprite filesystem activities (#848) — imperative file-I/O primitives over the
+ * Sprites filesystem API (`/v1/sprites/{id}/fs/*`). Same category as the
+ * lifecycle activities in `sprites.ts`: runtime-orchestration primitives, no
+ * desired state. They let an Op stage an input file into a sprite and read a
+ * result out without shelling it through `spriteExec` + `cat`/`tee`.
+ *
+ * read/write move raw file bytes in the body (not JSON), so these use a small
+ * raw HTTP client (`SpritesRawHttp`) rather than the JSON `SpritesHttp` the
+ * lifecycle activities use; path/mode/mkdir/recursive ride as query params.
+ * Endpoint + bearer resolution mirror `sprites.ts` — an explicit `endpoint` /
+ * `token` wins, then `SPRITES_BASE_URL` / `SPRITES_API_TOKEN`.
+ */
+
+import { resolveSpritesEndpoint } from "./sprites";
+
+function safeJson(text: string): unknown {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+// ── Pure URL builders (unit-testable) ──────────────────────────────────────────
+
+/**
+ * Build a `/v1/sprites/{id}/fs/{op}?...` URL. `params` values that are undefined
+ * or empty are dropped so the query only carries what the caller set. Pure.
+ */
+export function spriteFsUrl(
+  base: string,
+  id: string,
+  op: "read" | "write" | "list" | "delete",
+  params: Record<string, string | boolean | undefined>,
+): string {
+  const q = new URLSearchParams();
+  for (const [k, v] of Object.entries(params)) {
+    if (v === undefined || v === "") continue;
+    q.set(k, typeof v === "boolean" ? String(v) : v);
+  }
+  const qs = q.toString();
+  return `${base}/v1/sprites/${encodeURIComponent(id)}/fs/${op}${qs ? `?${qs}` : ""}`;
+}
+
+// ── Raw HTTP client (raw string bodies, mirrors defaultSpritesHttp) ─────────────
+
+/**
+ * Injectable raw HTTP client — like `SpritesHttp` but the body is sent verbatim
+ * (a file's bytes as a string), not JSON-encoded, and the response `text` is the
+ * raw body. Tests inject a fake; the default hits `fetch`.
+ */
+export type SpritesRawHttp = (
+  method: string,
+  url: string,
+  body?: string,
+  headers?: Record<string, string>,
+  signal?: AbortSignal,
+) => Promise<{ status: number; text: string }>;
+
+/**
+ * Default `fetch`-based raw client. Sends the body as-is with an
+ * `application/octet-stream` content-type and `Authorization: Bearer <token>`
+ * when a token is set (real Sprites); the fake ignores the token. The token
+ * defaults to `SPRITES_API_TOKEN` at call time. `fetchImpl` is injectable.
+ */
+export function defaultSpritesRawHttp(token?: string, fetchImpl: typeof fetch = fetch): SpritesRawHttp {
+  return async (method, url, body, headers, signal) => {
+    const h: Record<string, string> = { ...headers };
+    if (body !== undefined) h["content-type"] = "application/octet-stream";
+    const tok = token ?? process.env.SPRITES_API_TOKEN;
+    if (tok) h["authorization"] = `Bearer ${tok}`;
+    const res = await fetchImpl(url, {
+      method,
+      headers: Object.keys(h).length ? h : undefined,
+      body,
+      signal,
+    });
+    return { status: res.status, text: await res.text() };
+  };
+}
+
+// ── Activity contracts ──────────────────────────────────────────────────────────
+
+export interface SpriteWriteFileArgs {
+  /** Target sprite id (the `name` passed to `spriteCreate`). */
+  id: string;
+  /** Absolute path (or relative to `workingDir`) to write. */
+  path: string;
+  /** File contents. */
+  content: string;
+  /** Octal file mode, e.g. `"0644"`. */
+  mode?: string;
+  /** Create missing parent directories. */
+  mkdir?: boolean;
+  /** Base directory for a relative `path`. */
+  workingDir?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteReadFileArgs {
+  id: string;
+  path: string;
+  workingDir?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteReadFileResult {
+  content: string;
+}
+
+export interface SpriteListDirArgs {
+  id: string;
+  path: string;
+  workingDir?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+/** One directory entry. `type` is `file` or `dir`. */
+export interface SpriteDirEntry {
+  name: string;
+  type: "file" | "dir";
+  size?: number;
+}
+
+export interface SpriteRemoveArgs {
+  id: string;
+  path: string;
+  /** Remove a directory and its contents. */
+  recursive?: boolean;
+  /** Perform the delete as root. */
+  asRoot?: boolean;
+  workingDir?: string;
+  endpoint?: string;
+  token?: string;
+}
+
+// ── Activities (ActivityFn: (args, signal?) => Promise<unknown>) ──────────────
+
+/** Write a file into the sprite. `PUT /v1/sprites/{id}/fs/write` with raw body. */
+export async function spriteWriteFile(
+  args: SpriteWriteFileArgs,
+  signal?: AbortSignal,
+  http: SpritesRawHttp = defaultSpritesRawHttp(args.token),
+): Promise<Record<string, never>> {
+  const base = resolveSpritesEndpoint(args);
+  const url = spriteFsUrl(base, args.id, "write", {
+    path: args.path,
+    mode: args.mode,
+    mkdir: args.mkdir,
+    workingDir: args.workingDir,
+  });
+  const res = await http("PUT", url, args.content, undefined, signal);
+  if (res.status >= 300) {
+    throw new Error(`sprite ${args.id} write ${args.path} failed (${res.status}): ${res.text}`);
+  }
+  console.log(`wrote: sprite/${args.id}:${args.path} (${args.content.length}b)`);
+  return {};
+}
+
+/** Read a file from the sprite. `GET /v1/sprites/{id}/fs/read` → raw body. */
+export async function spriteReadFile(
+  args: SpriteReadFileArgs,
+  signal?: AbortSignal,
+  http: SpritesRawHttp = defaultSpritesRawHttp(args.token),
+): Promise<SpriteReadFileResult> {
+  const base = resolveSpritesEndpoint(args);
+  const url = spriteFsUrl(base, args.id, "read", { path: args.path, workingDir: args.workingDir });
+  const res = await http("GET", url, undefined, undefined, signal);
+  if (res.status === 404) throw new Error(`sprite ${args.id} read ${args.path}: not found`);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} read ${args.path} failed (${res.status}): ${res.text}`);
+  return { content: res.text };
+}
+
+/** List a directory in the sprite. `GET /v1/sprites/{id}/fs/list` → entry array. */
+export async function spriteListDir(
+  args: SpriteListDirArgs,
+  signal?: AbortSignal,
+  http: SpritesRawHttp = defaultSpritesRawHttp(args.token),
+): Promise<SpriteDirEntry[]> {
+  const base = resolveSpritesEndpoint(args);
+  const url = spriteFsUrl(base, args.id, "list", { path: args.path, workingDir: args.workingDir });
+  const res = await http("GET", url, undefined, undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} list ${args.path} failed (${res.status}): ${res.text}`);
+  const parsed = safeJson(res.text);
+  // Accept a bare array or a `{ entries: [...] }` envelope.
+  if (Array.isArray(parsed)) return parsed as SpriteDirEntry[];
+  const entries = (parsed as { entries?: unknown } | undefined)?.entries;
+  return Array.isArray(entries) ? (entries as SpriteDirEntry[]) : [];
+}
+
+/**
+ * Remove a path in the sprite. `DELETE /v1/sprites/{id}/fs/delete`. Idempotent:
+ * a 404 (already gone) is a no-op, matching `rm -f` and the destroy activity.
+ */
+export async function spriteRemove(
+  args: SpriteRemoveArgs,
+  signal?: AbortSignal,
+  http: SpritesRawHttp = defaultSpritesRawHttp(args.token),
+): Promise<Record<string, never>> {
+  const base = resolveSpritesEndpoint(args);
+  const url = spriteFsUrl(base, args.id, "delete", {
+    path: args.path,
+    recursive: args.recursive,
+    asRoot: args.asRoot,
+    workingDir: args.workingDir,
+  });
+  const res = await http("DELETE", url, undefined, undefined, signal);
+  if (res.status >= 300 && res.status !== 404) {
+    throw new Error(`sprite ${args.id} remove ${args.path} failed (${res.status}): ${res.text}`);
+  }
+  console.log(`removed: sprite/${args.id}:${args.path}`);
+  return {};
+}

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

@@ -0,0 +1,165 @@
+import { describe, test, expect, beforeAll, afterAll } from "vitest";
+import {
+  loadActivities,
+  runOpLocally,
+  phase,
+  spriteCreate,
+  spriteApplyNetworkPolicy,
+  spriteTaskCreate,
+  spriteWriteFile,
+  spriteApplyServices,
+  spriteExec,
+  spriteTaskRelease,
+  spriteDestroy,
+  type ActivityFn,
+  type ActivityProfile,
+  type OpConfig,
+} from "@intentius/chant/op";
+import { createSpritesFake } from "./sprites-fake";
+import { spriteCreate as createImpl } from "./sprites";
+import {
+  spriteTaskCreate as taskCreateImpl,
+  spriteTaskRefresh as taskRefreshImpl,
+  spriteTaskRelease as taskReleaseImpl,
+  spriteTasksUrl,
+} from "./sprite-tasks";
+
+// Keep-alive Tasks (#847) + the full Managed Agents session Op, end-to-end
+// against the in-process fake (S7). No Docker, no key — runs in CI.
+
+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();
+  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();
+});
+
+async function inspect(id: string): Promise<{
+  status: string;
+  fs: Record<string, string>;
+  netPolicy: Array<{ domain: string; action: string }>;
+  services: Record<string, { state: { status: string } }>;
+  tasks: Record<string, unknown>;
+}> {
+  const res = await fetch(`${fake.url}/v1/sprites/${id}`);
+  return (await res.json()) as never;
+}
+
+describe("spriteTaskUrl (pure)", () => {
+  test("builds the sprite-scoped tasks path", () => {
+    expect(spriteTasksUrl("http://h", "s 1")).toBe("http://h/v1/sprites/s%201/tasks");
+  });
+});
+
+describe("keep-alive task activities", () => {
+  test("create → refresh → release, release is idempotent", async () => {
+    await createImpl({ name: "ka-1", endpoint: fake.url });
+    await taskCreateImpl({ id: "ka-1", name: "session", expire: "5m", endpoint: fake.url });
+    expect(Object.keys((await inspect("ka-1")).tasks)).toEqual(["session"]);
+
+    await taskRefreshImpl({ id: "ka-1", name: "session", expire: "5m", endpoint: fake.url });
+    await taskReleaseImpl({ id: "ka-1", name: "session", endpoint: fake.url });
+    expect(Object.keys((await inspect("ka-1")).tasks)).toEqual([]);
+
+    // Idempotent: releasing an already-gone task is a no-op (404 tolerated).
+    await expect(taskReleaseImpl({ id: "ka-1", name: "session", endpoint: fake.url })).resolves.toBeDefined();
+  });
+
+  test("refreshing a missing task throws", async () => {
+    await createImpl({ name: "ka-2", endpoint: fake.url });
+    await expect(taskRefreshImpl({ id: "ka-2", name: "nope", endpoint: fake.url })).rejects.toThrow(/refresh failed/);
+  });
+
+  test("task activities resolve by name", () => {
+    for (const fn of ["spriteTaskCreate", "spriteTaskRefresh", "spriteTaskRelease"]) {
+      expect(typeof activities.get(fn)).toBe("function");
+    }
+  });
+});
+
+describe("Managed Agents session Op (#847)", () => {
+  const SESSION = "agent-session-t1";
+  test("Create → Secure → Hold → Stage → Runner → Run → Release → Destroy runs green", async () => {
+    const op: OpConfig = {
+      name: "managed-agent-session",
+      overview: "one session end-to-end",
+      taskQueue: "sprites",
+      phases: [
+        phase("Create", [spriteCreate({ name: SESSION })]),
+        phase("Secure", [
+          spriteApplyNetworkPolicy({
+            id: SESSION,
+            rules: [
+              { domain: "api.anthropic.com", action: "allow" },
+              { domain: "*", action: "deny" },
+            ],
+          }),
+        ]),
+        phase("Hold", [spriteTaskCreate({ id: SESSION, name: "session", expire: "5m" })]),
+        phase("Stage", [spriteWriteFile({ id: SESSION, path: "/run/agent.env", mkdir: true, content: "ANTHROPIC_SESSION_ID=agent-session-t1" })]),
+        phase("Runner", [
+          spriteApplyServices({
+            id: SESSION,
+            start: true,
+            services: [{ name: "agent-runner", cmd: "agent-runner", dir: "/run", http_port: 8080 }],
+          }),
+        ]),
+        phase("Run", [spriteExec({ id: SESSION, cmd: "echo session-complete > /run/status" })]),
+        phase("Release", [spriteTaskRelease({ id: SESSION, name: "session" })]),
+        phase("Destroy", [spriteDestroy({ id: SESSION })]),
+      ],
+    };
+    const result = await runOpLocally(op, activities, PROFILES);
+    expect(result.ok).toBe(true);
+    expect(result.records.map((r) => r.fn)).toEqual([
+      "spriteCreate",
+      "spriteApplyNetworkPolicy",
+      "spriteTaskCreate",
+      "spriteWriteFile",
+      "spriteApplyServices",
+      "spriteExec",
+      "spriteTaskRelease",
+      "spriteDestroy",
+    ]);
+    expect(result.records.every((r) => r.status === "ok")).toBe(true);
+  });
+
+  test("mid-session state: policy set, runner running, task held, before teardown", async () => {
+    const id = "agent-session-t2";
+    const op: OpConfig = {
+      name: "managed-agent-session-partial",
+      overview: "up to Run, no teardown, so state is observable",
+      phases: [
+        phase("Create", [spriteCreate({ name: id })]),
+        phase("Secure", [
+          spriteApplyNetworkPolicy({ id, rules: [{ domain: "api.anthropic.com", action: "allow" }, { domain: "*", action: "deny" }] }),
+        ]),
+        phase("Hold", [spriteTaskCreate({ id, name: "session", expire: "5m" })]),
+        phase("Runner", [spriteApplyServices({ id, start: true, services: [{ name: "agent-runner", cmd: "agent-runner" }] })]),
+      ],
+    };
+    await runOpLocally(op, activities, PROFILES);
+    const s = await inspect(id);
+    expect(s.netPolicy).toEqual([
+      { domain: "api.anthropic.com", action: "allow" },
+      { domain: "*", action: "deny" },
+    ]);
+    expect(s.services["agent-runner"].state.status).toBe("running");
+    expect(Object.keys(s.tasks)).toEqual(["session"]);
+  });
+});

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

@@ -0,0 +1,91 @@
+/**
+ * Sprite keep-alive Tasks activities (#847) — a hold that prevents a Sprite from
+ * pausing while a session runs. While at least one task exists the Sprite stays
+ * active; the hold is refreshed on an interval and released on exit.
+ *
+ * Per the Sprites docs a task carries an `expire` (seconds or a duration string
+ * like `"5m"`/`"1h"`) with a **1-hour max per task**, so a session longer than
+ * that must refresh. The recommended shape is a short expiry refreshed on a
+ * shorter interval — 5-minute expiry / 60-second refresh — released on exit.
+ *
+ * These are the three primitives, not a magic looping hold: a phased Op creates
+ * the task around a session (`spriteTaskCreate`) and releases it after (in the
+ * happy path and in `onFailure`). A worker whose session can outlast the 1-hour
+ * cap wraps its own run in a `spriteTaskRefresh` loop (that ambient loop lives in
+ * the long-running caller, not a single serializable activity — a phased Op has
+ * no single step to hang it on). `spriteTaskRelease` is idempotent so a crash
+ * still frees the Sprite (and the task auto-expires if the release never lands).
+ *
+ * The task REST path is provisional (S6, #766); it mirrors the other endpoints'
+ * `/v1/sprites/{id}/...` shape. URL building is a pure helper so the path can
+ * move without touching callers.
+ */
+
+import { resolveSpritesEndpoint, defaultSpritesHttp, type SpritesHttp } from "./sprites";
+
+/** The task REST base for a sprite. Pure. */
+export function spriteTasksUrl(base: string, id: string): string {
+  return `${base}/v1/sprites/${encodeURIComponent(id)}/tasks`;
+}
+export function spriteTaskUrl(base: string, id: string, name: string): string {
+  return `${spriteTasksUrl(base, id)}/${encodeURIComponent(name)}`;
+}
+
+export interface SpriteTaskCreateArgs {
+  id: string;
+  /** Task name (the key later refresh/release use). */
+  name: string;
+  /** Expiry: seconds (number) or a duration string (`"5m"`, `"1h"`). Max 1h. */
+  expire?: number | string;
+  endpoint?: string;
+  token?: string;
+}
+
+export interface SpriteTaskRefreshArgs extends SpriteTaskCreateArgs {}
+
+export interface SpriteTaskReleaseArgs {
+  id: string;
+  name: string;
+  endpoint?: string;
+  token?: string;
+}
+
+/** Create a keep-alive task. `POST /v1/sprites/{id}/tasks`. */
+export async function spriteTaskCreate(
+  args: SpriteTaskCreateArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<{ name: string }> {
+  const base = resolveSpritesEndpoint(args);
+  const body = { name: args.name, ...(args.expire !== undefined ? { expire: args.expire } : {}) };
+  const res = await http("POST", spriteTasksUrl(base, args.id), body, undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} task create failed (${res.status}): ${res.text}`);
+  return { name: args.name };
+}
+
+/** Refresh a task's expiry. `PUT /v1/sprites/{id}/tasks/{name}`. */
+export async function spriteTaskRefresh(
+  args: SpriteTaskRefreshArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<{ name: string }> {
+  const base = resolveSpritesEndpoint(args);
+  const body = args.expire !== undefined ? { expire: args.expire } : undefined;
+  const res = await http("PUT", spriteTaskUrl(base, args.id, args.name), body, undefined, signal);
+  if (res.status >= 300) throw new Error(`sprite ${args.id} task refresh failed (${res.status}): ${res.text}`);
+  return { name: args.name };
+}
+
+/** Release a task (idempotent; a 404 means already gone). `DELETE /v1/sprites/{id}/tasks/{name}`. */
+export async function spriteTaskRelease(
+  args: SpriteTaskReleaseArgs,
+  signal?: AbortSignal,
+  http: SpritesHttp = defaultSpritesHttp(args.token),
+): Promise<Record<string, never>> {
+  const base = resolveSpritesEndpoint(args);
+  const res = await http("DELETE", spriteTaskUrl(base, args.id, args.name), undefined, undefined, signal);
+  if (res.status >= 300 && res.status !== 404) {
+    throw new Error(`sprite ${args.id} task release failed (${res.status}): ${res.text}`);
+  }
+  return {};
+}

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

@@ -7,15 +7,29 @@ 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));
-    // The six ./sprites.ts activities that make an HTTP/WS call.
+    // Every activity across the lifecycle, filesystem, config-reconcile, and
+    // keep-alive modules that makes an HTTP/WS call.
     expect(activities).toEqual(
       new Set([
+        // lifecycle (./sprites.ts)
         "spriteCreate",
         "spriteExec",
         "spriteCheckpoint",
         "listCheckpoints",
         "spriteRestore",
         "spriteDestroy",
+        // filesystem (./sprite-fs.ts)
+        "spriteWriteFile",
+        "spriteReadFile",
+        "spriteListDir",
+        "spriteRemove",
+        // config reconcile (./sprite-config.ts)
+        "spriteApplyNetworkPolicy",
+        "spriteApplyServices",
+        // keep-alive tasks (./sprite-tasks.ts)
+        "spriteTaskCreate",
+        "spriteTaskRefresh",
+        "spriteTaskRelease",
       ]),
     );
   });
@@ -23,7 +37,7 @@ describe("SPRITES_CONTRACT", () => {
   test("every entry has a v1 path and a known method", () => {
     for (const e of SPRITES_CONTRACT) {
       expect(e.path.startsWith("/v1/sprites")).toBe(true);
-      expect(["GET", "POST", "DELETE", "WS"]).toContain(e.method);
+      expect(["GET", "POST", "PUT", "DELETE", "WS"]).toContain(e.method);
     }
   });
 
@@ -43,18 +57,22 @@ describe("SPRITES_CONTRACT", () => {
     expect(keys.size).toBe(SPRITES_CONTRACT.length);
   });
 
-  test("every contract path segment appears in the sprites.ts source (drift anchor)", () => {
+  test("every contract path segment appears in the activity source (drift anchor)", () => {
     // Anchors the hand-authored contract to the activity implementations: if an
     // activity's endpoint path changes, a segment goes missing here and the
-    // contract must be updated in the same change.
-    const src = readFileSync(join(dirname(fileURLToPath(import.meta.url)), "sprites.ts"), "utf-8");
+    // 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"]
+      .map((f) => readFileSync(join(dir, f), "utf-8"))
+      .join("\n");
     const segments = new Set(
       SPRITES_CONTRACT.flatMap((e) =>
         e.path.split("/").filter((s) => s.length > 0 && !s.startsWith("{")),
       ),
     );
     for (const seg of segments) {
-      expect(src, `path segment "${seg}" from the contract is absent from sprites.ts`).toContain(seg);
+      expect(src, `path segment "${seg}" from the contract is absent from the activity source`).toContain(seg);
     }
   });
 });

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

@@ -5,8 +5,8 @@
  * the fly resource surface generates + drift-checks against. The Sprites API
  * (api.sprites.dev) ships no such spec at any conventional path, so there is
  * nothing to diff automatically. This module is the manual stand-in: the exact
- * endpoint set the fly sprite activities (./sprites.ts) depend on, maintained by
- * hand from https://docs.sprites.dev.
+ * endpoint set the fly sprite activities (lifecycle, filesystem, config, tasks)
+ * depend on, maintained by hand from https://docs.sprites.dev.
  *
  * It anchors two fidelity checks:
  *   1. Coverage — every endpoint here must be served by the pinned spritzer
@@ -24,24 +24,45 @@
 /** One endpoint the fly sprite activities call. */
 export interface SpritesEndpoint {
   /** HTTP method, or "WS" for the control-WebSocket exec channel. */
-  method: "GET" | "POST" | "DELETE" | "WS";
+  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 (./sprites.ts export). */
+  /** The fly activity that calls it (an activity module export). */
   activity: string;
 }
 
 /**
- * The Sprites endpoints ./sprites.ts depends on. Keep in sync with the activity
- * implementations — the unit test asserts every sprite activity is represented.
+ * The Sprites endpoints the fly sprite activities depend on, across the lifecycle
+ * (./sprites.ts), filesystem (./sprite-fs.ts), config reconcile
+ * (./sprite-config.ts), and keep-alive tasks (./sprite-tasks.ts) modules. Keep in
+ * sync with the activity implementations — the unit test asserts every sprite
+ * activity is represented, and the coverage test asserts the pinned spritzer
+ * serves each one.
  */
 export const SPRITES_CONTRACT: readonly SpritesEndpoint[] = [
+  // Lifecycle (./sprites.ts)
   { method: "POST", path: "/v1/sprites", activity: "spriteCreate" },
   { method: "WS", path: "/v1/sprites/{id}/exec", activity: "spriteExec" },
   { 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" },
+  // Filesystem (./sprite-fs.ts)
+  { method: "PUT", path: "/v1/sprites/{id}/fs/write", activity: "spriteWriteFile" },
+  { method: "GET", path: "/v1/sprites/{id}/fs/read", activity: "spriteReadFile" },
+  { method: "GET", path: "/v1/sprites/{id}/fs/list", activity: "spriteListDir" },
+  { method: "DELETE", path: "/v1/sprites/{id}/fs/delete", activity: "spriteRemove" },
+  // 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" },
+  // 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" },
+  { method: "DELETE", path: "/v1/sprites/{id}/tasks/{name}", activity: "spriteTaskRelease" },
 ] as const;
 
 /**