@intentius/chant-lexicon-fly 0.18.6 → 0.18.8

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.