@intentius/chant-lexicon-fly 0.18.5 → 0.18.7

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-fake.ts

@@ -33,6 +33,17 @@ interface StoredCheckpoint {
   fs: Record<string, string>;
 }
 
+interface StoredService {
+  name: string;
+  cmd: string;
+  args?: string[];
+  env?: Record<string, string>;
+  dir?: string;
+  needs?: string[];
+  http_port?: number;
+  state: { name: string; pid: number; status: string; started_at?: string };
+}
+
 interface SpriteState {
   id: string;
   status: SpriteStatus;
@@ -44,6 +55,12 @@ interface SpriteState {
   /** Monotonic version counter for `v<N>` ids. */
   version: number;
   policy?: unknown;
+  /** Outbound network policy (whole-object replace via /policy/network). */
+  netPolicy: Array<{ domain: string; action: string }>;
+  /** Background services keyed by name (create-or-update via PUT). */
+  services: Record<string, StoredService>;
+  /** Keep-alive tasks keyed by name; while any exists the sprite stays active. */
+  tasks: Record<string, { name: string; expire?: number | string }>;
 }
 
 interface ExecResult {
@@ -68,7 +85,12 @@ export function fakeExec(sprite: SpriteState, cmd: string): ExecResult {
     if (!seg) continue;
 
     let m: RegExpMatchArray | null;
-    if ((m = seg.match(/^echo\s+(.+?)\s*>\s*(\S+)$/))) {
+    if ((m = seg.match(/^cat\s+(\S+)\s*>\s*(\S+)$/))) {
+      // Copy a file: `cat SRC > DEST`. Lets an Op stage input with spriteWriteFile,
+      // process it with exec, then read the result with spriteReadFile.
+      sprite.fs[m[2]] = sprite.fs[m[1]] ?? "";
+      exitCode = 0;
+    } else if ((m = seg.match(/^echo\s+(.+?)\s*>\s*(\S+)$/))) {
       sprite.fs[m[2]] = unquote(m[1]);
       exitCode = 0;
     } else if ((m = seg.match(/^echo\s+(.+)$/))) {
@@ -135,6 +157,36 @@ async function readBody(req: IncomingMessage): Promise<unknown> {
   }
 }
 
+/** Read the request body as raw text (for the filesystem write endpoint). */
+async function readRawBody(req: IncomingMessage): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const c of req) chunks.push(c as Buffer);
+  return Buffer.concat(chunks).toString("utf8");
+}
+
+/**
+ * Immediate children of `dir` in a flat `path → contents` map: a key
+ * `${dir}/name` is a file; `${dir}/name/...` contributes the dir `name` once.
+ * Pure — the filesystem-list model for the fake.
+ */
+export function fakeListDir(fs: Record<string, string>, dir: string): Array<{ name: string; type: "file" | "dir"; size?: number }> {
+  const prefix = dir.replace(/\/+$/, "") + "/";
+  const files = new Map<string, number>();
+  const dirs = new Set<string>();
+  for (const [key, val] of Object.entries(fs)) {
+    if (!key.startsWith(prefix)) continue;
+    const rest = key.slice(prefix.length);
+    if (!rest) continue;
+    const slash = rest.indexOf("/");
+    if (slash === -1) files.set(rest, val.length);
+    else dirs.add(rest.slice(0, slash));
+  }
+  return [
+    ...[...dirs].sort().map((name) => ({ name, type: "dir" as const })),
+    ...[...files.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([name, size]) => ({ name, type: "file" as const, size })),
+  ];
+}
+
 /**
  * Start the in-process Sprites fake on an ephemeral port. Returns its base
  * `url` (feed it to `SPRITES_BASE_URL`) and a `close()`.
@@ -211,11 +263,155 @@ export function createSpritesFake(): Promise<{ url: string; close(): Promise<voi
         checkpoints: [],
         version: 0,
         policy: body.policy,
+        netPolicy: [],
+        services: {},
+        tasks: {},
       };
       sprites.set(id, sprite);
       return send(201, { id: sprite.id, url: sprite.url });
     }
 
+    // Keep-alive tasks: /v1/sprites/{id}/tasks[/{name}].
+    const tm = path.match(/^\/v1\/sprites\/([^/]+)\/tasks(?:\/([^/]+))?\/?$/);
+    if (tm) {
+      const id = decodeURIComponent(tm[1]);
+      const name = tm[2] ? decodeURIComponent(tm[2]) : undefined;
+      const sprite = sprites.get(id);
+      if (!sprite || sprite.status === "destroyed") return send(404, { error: `no sprite ${id}` });
+
+      if (method === "GET" && !name) return send(200, Object.values(sprite.tasks));
+      if (method === "POST" && !name) {
+        const b = ((await readBody(req)) ?? {}) as { name?: string; expire?: number | string };
+        if (!b.name) return send(400, { error: "name is required" });
+        sprite.tasks[b.name] = { name: b.name, expire: b.expire };
+        return send(201, { name: b.name, expires_at: "2026-01-01T00:00:00Z" });
+      }
+      if (method === "PUT" && name) {
+        const b = ((await readBody(req)) ?? {}) as { expire?: number | string };
+        const t = sprite.tasks[name];
+        if (!t) return send(404, { error: `no task ${name}` });
+        t.expire = b.expire ?? t.expire;
+        return send(200, { name, expires_at: "2026-01-01T00:00:00Z" });
+      }
+      if (method === "DELETE" && name) {
+        if (!(name in sprite.tasks)) return send(404, { error: `no task ${name}` });
+        delete sprite.tasks[name];
+        return send(204, {});
+      }
+      return send(404, { error: `not found: ${method} ${path}` });
+    }
+
+    // Network policy: GET/POST /v1/sprites/{id}/policy/network (whole-object replace).
+    const pm = path.match(/^\/v1\/sprites\/([^/]+)\/policy\/network\/?$/);
+    if (pm) {
+      const id = decodeURIComponent(pm[1]);
+      const sprite = sprites.get(id);
+      if (!sprite || sprite.status === "destroyed") return send(404, { error: `no sprite ${id}` });
+      if (method === "GET") return send(200, { rules: sprite.netPolicy });
+      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 });
+      }
+      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)?)?\/?$/);
+    if (svcm) {
+      const id = decodeURIComponent(svcm[1]);
+      const svc = svcm[2] ? decodeURIComponent(svcm[2]) : undefined;
+      const action = svcm[3];
+      const sprite = sprites.get(id);
+      if (!sprite || sprite.status === "destroyed") return send(404, { error: `no sprite ${id}` });
+
+      // GET /services — list.
+      if (method === "GET" && !svc) return send(200, Object.values(sprite.services));
+
+      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.
+        if (method === "PUT") {
+          const b = ((await readBody(req)) ?? {}) as Omit<StoredService, "name" | "state">;
+          sprite.services[svc] = {
+            name: svc,
+            cmd: b.cmd,
+            args: b.args,
+            env: b.env,
+            dir: b.dir,
+            needs: b.needs,
+            http_port: b.http_port,
+            state: sprite.services[svc]?.state ?? { name: svc, pid: 0, status: "stopped" },
+          };
+          return send(200, sprite.services[svc]);
+        }
+      }
+
+      // POST /services/{svc}/start|stop|restart — NDJSON, flips status.
+      if (method === "POST" && svc && action) {
+        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() };
+        return sendNdjson(200, [
+          { type: stopped ? "stopping" : "started", data: `${svc} ${stopped ? "stopping" : "started"}` },
+          { type: "complete", data: `${svc} ${action.slice(1)} complete` },
+        ]);
+      }
+      return send(404, { error: `not found: ${method} ${path}` });
+    }
+
+    // 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)\/?$/);
+    if (fsm) {
+      const id = decodeURIComponent(fsm[1]);
+      const op = fsm[2];
+      const sprite = sprites.get(id);
+      if (!sprite || sprite.status === "destroyed") return send(404, { error: `no sprite ${id}` });
+      const p = url.searchParams.get("path") ?? "";
+      if (!p) return send(400, { error: "path is required" });
+      const sendRaw = (status: number, body: string): void => {
+        res.writeHead(status, { "content-type": "application/octet-stream" });
+        res.end(body);
+      };
+
+      if (method === "PUT" && op === "write") {
+        sprite.fs[p] = await readRawBody(req);
+        return send(200, {});
+      }
+      if (method === "GET" && op === "read") {
+        const content = sprite.fs[p];
+        if (content === undefined) return send(404, { error: `no file ${p}` });
+        return sendRaw(200, content);
+      }
+      if (method === "GET" && op === "list") {
+        return send(200, fakeListDir(sprite.fs, p));
+      }
+      if (method === "DELETE" && op === "delete") {
+        const recursive = url.searchParams.get("recursive") === "true";
+        if (recursive) {
+          const prefix = p.replace(/\/+$/, "");
+          let removed = 0;
+          for (const key of Object.keys(sprite.fs)) {
+            if (key === prefix || key.startsWith(prefix + "/")) {
+              delete sprite.fs[key];
+              removed += 1;
+            }
+          }
+          return removed > 0 ? send(200, {}) : send(404, { error: `no path ${p}` });
+        }
+        if (!(p in sprite.fs)) return send(404, { error: `no file ${p}` });
+        delete sprite.fs[p];
+        return send(200, {});
+      }
+      return send(404, { error: `not found: ${method} ${path}` });
+    }
+
     const m = path.match(/^\/v1\/sprites\/([^/]+)(\/checkpoint|\/checkpoints(?:\/([^/]+)(\/restore)?)?)?\/?$/);
     if (m) {
       const id = decodeURIComponent(m[1]);
@@ -282,7 +478,7 @@ export function createSpritesFake(): Promise<{ url: string; close(): Promise<voi
         return send(200, {});
       }
 
-      // GET /v1/sprites/{id} — inspection (fs + checkpoint ids), used by tests/verify.
+      // GET /v1/sprites/{id} — inspection (fs + checkpoint ids + config), used by tests/verify.
       if (method === "GET" && !sub) {
         return send(200, {
           id: sprite.id,
@@ -290,6 +486,9 @@ export function createSpritesFake(): Promise<{ url: string; close(): Promise<voi
           url: sprite.url,
           fs: sprite.fs,
           checkpoints: sprite.checkpoints.map((c) => c.id),
+          netPolicy: sprite.netPolicy,
+          services: sprite.services,
+          tasks: sprite.tasks,
         });
       }
     }

package/src/skills/chant-fly-sprites.md

@@ -99,6 +99,20 @@ The offline, Docker-free emulator that CI runs against is `createSpritesFake()`
 
 The real Sprites REST surface is provisional (S6, tracked in #766): the endpoint constants may still move to match the official API. The activity input and output contracts (the `Args` and `Result` shapes shown above) are the stable interface the Ops and the emulator are written against, so build your Ops on those.
 
+## Beyond the five: filesystem, config, and keep-alive
+
+The same lexicon ships more Sprite primitives, all imported from `@intentius/chant-lexicon-fly` and resolved by `loadActivities(["fly"])`:
+
+| Family | Activities | Use |
+|--------|-----------|-----|
+| Filesystem (#848) | `spriteWriteFile` / `spriteReadFile` / `spriteListDir` / `spriteRemove` | stage an input file and read a result out without shelling `spriteExec` + `cat` |
+| Config reconcile (#849) | `spriteApplyNetworkPolicy` / `spriteApplyServices` | reconcile a Sprite's egress allowlist and background services against typed config (validated before any HTTP; a whole-object replace for policy, create-or-update by name for services) |
+| Keep-alive (#847) | `spriteTaskCreate` / `spriteTaskRefresh` / `spriteTaskRelease` | hold a Sprite active for a session so it will not pause; a session past the 1-hour task cap refreshes on an interval |
+
+These are still runtime-orchestration primitives, not declarable resources — a Sprite has no desired-state create body to reconcile.
+
 ## Where it fits
 
 The runnable starter is [`examples/sprites-agent-task`](../../examples/sprites-agent-task), which ships both Ops above. Run `chant run agent-task` for the happy path and `chant run guarded-task` to watch the checkpoint-as-compensation rollback. `guarded-task` exits non-zero on purpose: the `Run` phase fails, the `onFailure` `Restore` runs, and the sprite is back at `pre-run`.
+
+[`examples/sprites-managed-agent-worker`](../../examples/sprites-managed-agent-worker) composes the config and keep-alive families into one [Claude Managed Agents](https://docs.sprites.dev/integrations/claude-managed-agents/) session: create → egress policy → keep-alive task → env-contract file → runner-as-service → run → release → destroy, with an `onFailure` that frees the hold and tears the Sprite down.