@ai-ecoverse/slicc-agent 3.10.0 → 3.11.0

package/dist/sprinkles/index.js

@@ -0,0 +1,216 @@
+import {
+  replicatedState
+} from "@earendil-works/chord";
+import {
+  describe,
+  homePath,
+  NO_EXEC,
+  SPRINKLE_KIND,
+  SPRINKLES_DIR,
+  SprinklesDoc,
+  sprinkleFiles,
+  WELCOME,
+  WELCOMED
+} from "./sprinkles.js";
+const USAGE = `usage:
+  sprinkle list                 every sprinkle in /home/sprinkles, with its owner
+  sprinkle show <name>          show a sprinkle in your chat
+  sprinkle own <name> [<agent>] send its messages to <agent> (cone, cone-<n> or a scoop's handle)
+
+A sprinkle is an .shtml file in /home/sprinkles, as <name>.shtml or <name>/<name>.shtml.
+Every one of them has a button in the rail; edit the file and the open panel reloads.
+`;
+const RETIRED = {
+  open: "every sprinkle in /home/sprinkles already has a button in the rail; sprinkle show <name> shows one in the chat",
+  reload: "editing the .shtml file reloads the sprinkle",
+  close: "delete the .shtml file to retire a sprinkle; the user closes panels",
+  send: "a sprinkle reads data with slicc.readFile() or keeps it with slicc.setState(); write the file it reads",
+  chat: "show the sprinkle with sprinkle show <name> and wait for its lick"
+};
+function targetOf(agentId) {
+  return agentId.startsWith("scoop:") ? agentId : `cone:${agentId}`;
+}
+function agentOf(caller, agents) {
+  if (caller?.startsWith("cone:")) return caller.slice("cone:".length);
+  return caller ?? agents.activeCone();
+}
+function named(agents, value) {
+  const state = agents.state();
+  if (value in state.cones) return value;
+  const id = value.startsWith("scoop:") ? value : `scoop:${value}`;
+  return id in state.scoops ? id : void 0;
+}
+function setupSprinkles() {
+  return {
+    async attach(options, context) {
+      const { harness, agents, licks, env } = options;
+      const dir = options.dir ?? SPRINKLES_DIR;
+      const sprinkles = replicatedState([]);
+      const welcome = options.assets ? await options.assets("packages/vfs-root/sprinkles/welcome.shtml").catch(() => void 0) : void 0;
+      const owners = async (using) => (await harness.snapshot(SprinklesDoc, using))?.owners ?? {};
+      const reload = async (using) => {
+        const owned = await owners(using);
+        const out = [];
+        for (const { name, path } of await sprinkleFiles(env, dir, using)) {
+          if (name === WELCOME) continue;
+          const read = await env.readTextFile(path, using);
+          if (!read.ok) continue;
+          out.push({
+            id: name,
+            name,
+            ...describe(name, read.value),
+            agentId: owned[name] ?? agents.activeCone(),
+            html: read.value
+          });
+        }
+        if (welcome !== void 0)
+          out.push({
+            id: WELCOME,
+            name: WELCOME,
+            ...describe(WELCOME, welcome),
+            agentId: owned[WELCOME] ?? "cone",
+            html: welcome,
+            inline: true
+          });
+        sprinkles.replace(using, out);
+      };
+      const inside = async (path, using) => {
+        const asked = homePath(path);
+        const real = await env.canonicalPath(asked, using);
+        return real.ok ? homePath(real.value) : asked;
+      };
+      const offCone = agents.onCone(() => reload(context).catch(() => void 0));
+      const find = (id) => sprinkles.value.find((item) => item.id === id);
+      const post = async (id, agentId, using) => {
+        const conversation = await agents.conversation(agentId, using);
+        if (!conversation) throw new Error(`there is no agent ${agentId}`);
+        await conversation.submit(
+          { type: "write", entry: { kind: SPRINKLE_KIND, data: { sprinkle: id, at: Date.now() } } },
+          using
+        );
+      };
+      const setOwner = async (name, agentId, using) => {
+        await harness.commit(async (tx) => {
+          (await tx.doc(SprinklesDoc)).owners[name] = agentId;
+        }, using);
+        await reload(using);
+      };
+      await reload(context);
+      const state = await harness.snapshot(SprinklesDoc, context);
+      if (welcome !== void 0 && !state?.welcomed) {
+        await post(WELCOME, "cone", context);
+        await harness.commit(async (tx) => {
+          (await tx.doc(SprinklesDoc)).welcomed = true;
+        }, context);
+      }
+      let timer;
+      const watched = await env.watch(
+        [{ path: dir, recursive: true }],
+        () => {
+          clearTimeout(timer);
+          timer = setTimeout(() => void reload(context).catch(() => void 0), options.reloadMs);
+        },
+        context
+      );
+      const watcher = watched.ok ? watched.value : void 0;
+      const commands = {
+        async list(_argv, _caller, using) {
+          await reload(using);
+          const rows = sprinkles.value.filter((item) => !item.inline).map((item) => `${item.name}	${item.title}	${item.agentId}`);
+          return { code: 0, out: rows.length ? `${rows.join("\n")}
+` : "no sprinkles\n" };
+        },
+        async show(argv, caller, using) {
+          await reload(using);
+          const name = argv[1] ?? "";
+          if (!find(name)) return { code: 1, out: `sprinkle: there is no sprinkle ${name}
+` };
+          const agentId = agentOf(caller, agents);
+          await post(name, agentId, using);
+          if (!(await owners(using))[name]) await setOwner(name, agentId, using);
+          return { code: 0, out: `showed ${name} in the chat of ${agentId}
+` };
+        },
+        async own(argv, caller, using) {
+          const name = argv[1] ?? "";
+          if (!find(name)) return { code: 1, out: `sprinkle: there is no sprinkle ${name}
+` };
+          const agentId = argv[2] ? named(agents, argv[2]) : agentOf(caller, agents);
+          if (!agentId) return { code: 1, out: `sprinkle: there is no agent ${argv[2]}
+` };
+          await setOwner(name, agentId, using);
+          return { code: 0, out: `${name} now talks to ${agentId}
+` };
+        }
+      };
+      return {
+        sprinkles,
+        async send(id, payload, using) {
+          const sprinkle = find(id);
+          if (!sprinkle) return { delivered: false };
+          if (id === WELCOME && payload.action === "onboarding-complete")
+            await env.writeFile(WELCOMED, `${(/* @__PURE__ */ new Date()).toISOString()}
+`, using);
+          await licks.deliver(
+            {
+              channel: "sprinkle",
+              source: `sprinkle:${id}`,
+              title: sprinkle.title,
+              text: payload.action || "(no action)",
+              ...payload.data === null ? {} : { body: JSON.stringify(payload.data, null, 2) },
+              target: targetOf((await owners(using))[id] ?? agents.activeCone())
+            },
+            using
+          );
+          return { delivered: true };
+        },
+        async call(id, method, args, using) {
+          if (!find(id)) throw new Error(`there is no sprinkle ${id}`);
+          const handlers = {
+            async readFile() {
+              const read = await env.readTextFile(await inside(args[0], using), using);
+              if (!read.ok) throw new Error(read.error.message);
+              return read.value;
+            },
+            async exists() {
+              const found = await env.exists(await inside(args[0], using), using);
+              return found.ok && found.value;
+            },
+            async getState() {
+              return (await harness.snapshot(SprinklesDoc, using))?.state[id] ?? null;
+            },
+            async setState() {
+              await harness.commit(async (tx) => {
+                (await tx.doc(SprinklesDoc)).state[id] = args[0] ?? null;
+              }, using);
+              return null;
+            }
+          };
+          const handler = handlers[method];
+          if (!handler) throw new Error(NO_EXEC);
+          return handler();
+        },
+        async command(argv, caller, using) {
+          const verb = argv[0] ?? "help";
+          const run = commands[verb];
+          if (run) return run(argv, caller, using);
+          if (verb in RETIRED)
+            return { code: 2, out: `sprinkle ${verb} isn't in SLICC: ${RETIRED[verb]}
+` };
+          return { code: verb === "help" || verb === "--help" ? 0 : 2, out: USAGE };
+        },
+        reload,
+        async close(using) {
+          offCone();
+          clearTimeout(timer);
+          await watcher?.close(using);
+        }
+      };
+    }
+  };
+}
+export {
+  USAGE,
+  setupSprinkles
+};
+//# sourceMappingURL=index.js.map

package/dist/sprinkles/index.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/sprinkles/index.ts"],
+  "sourcesContent": ["import {\n  type Context,\n  type JsonValue,\n  type ReplicatedState,\n  replicatedState,\n} from '@earendil-works/chord';\nimport type { Harness } from '@earendil-works/pi-durable';\nimport type { ExecutionEnv, FileWatcher } from '@earendil-works/pi-durable/env';\nimport type { Agents } from '../agents.ts';\nimport type { LickTarget } from '../licks/lick.ts';\nimport type { Licks } from '../licks/licks.ts';\nimport {\n  describe,\n  homePath,\n  NO_EXEC,\n  SPRINKLE_KIND,\n  SPRINKLES_DIR,\n  type Sprinkle,\n  type SprinkleMethod,\n  SprinklesDoc,\n  sprinkleFiles,\n  WELCOME,\n  WELCOMED,\n} from './sprinkles.ts';\n\nexport type Answer = { code: number; out: string };\n\nexport interface SprinklePayload {\n  action: string;\n  data: JsonValue | null;\n  target: string | null;\n}\n\nexport interface SprinklesRuntime {\n  readonly sprinkles: ReplicatedState<Sprinkle[]>;\n  send(id: string, payload: SprinklePayload, context: Context): Promise<{ delivered: boolean }>;\n  call(id: string, method: string, args: readonly unknown[], context: Context): Promise<JsonValue>;\n  command(argv: readonly string[], caller: string | null, context: Context): Promise<Answer>;\n  reload(context: Context): Promise<void>;\n  close(context: Context): Promise<void>;\n}\n\nexport interface SprinklesAttach {\n  harness: Harness;\n  agents: Agents;\n  licks: Licks;\n  env: ExecutionEnv;\n  assets?: (path: string) => Promise<string>;\n  reloadMs: number;\n  dir?: string;\n}\n\nexport const USAGE = `usage:\n  sprinkle list                 every sprinkle in /home/sprinkles, with its owner\n  sprinkle show <name>          show a sprinkle in your chat\n  sprinkle own <name> [<agent>] send its messages to <agent> (cone, cone-<n> or a scoop's handle)\n\nA sprinkle is an .shtml file in /home/sprinkles, as <name>.shtml or <name>/<name>.shtml.\nEvery one of them has a button in the rail; edit the file and the open panel reloads.\n`;\n\nconst RETIRED: Record<string, string> = {\n  open: 'every sprinkle in /home/sprinkles already has a button in the rail; sprinkle show <name> shows one in the chat',\n  reload: 'editing the .shtml file reloads the sprinkle',\n  close: 'delete the .shtml file to retire a sprinkle; the user closes panels',\n  send: 'a sprinkle reads data with slicc.readFile() or keeps it with slicc.setState(); write the file it reads',\n  chat: 'show the sprinkle with sprinkle show <name> and wait for its lick',\n};\n\nfunction targetOf(agentId: string): LickTarget {\n  return agentId.startsWith('scoop:') ? (agentId as LickTarget) : `cone:${agentId}`;\n}\n\nfunction agentOf(caller: string | null, agents: Agents): string {\n  if (caller?.startsWith('cone:')) return caller.slice('cone:'.length);\n  return caller ?? agents.activeCone();\n}\n\nfunction named(agents: Agents, value: string): string | undefined {\n  const state = agents.state();\n  if (value in state.cones) return value;\n  const id = value.startsWith('scoop:') ? value : `scoop:${value}`;\n  return id in state.scoops ? id : undefined;\n}\n\nexport function setupSprinkles() {\n  return {\n    async attach(options: SprinklesAttach, context: Context): Promise<SprinklesRuntime> {\n      const { harness, agents, licks, env } = options;\n      const dir = options.dir ?? SPRINKLES_DIR;\n      const sprinkles = replicatedState<Sprinkle[]>([]);\n      const welcome = options.assets\n        ? await options.assets('packages/vfs-root/sprinkles/welcome.shtml').catch(() => undefined)\n        : undefined;\n      const owners = async (using: Context) =>\n        (await harness.snapshot(SprinklesDoc, using))?.owners ?? {};\n      const reload = async (using: Context) => {\n        const owned = await owners(using);\n        const out: Sprinkle[] = [];\n        for (const { name, path } of await sprinkleFiles(env, dir, using)) {\n          if (name === WELCOME) continue;\n          const read = await env.readTextFile(path, using);\n          if (!read.ok) continue;\n          out.push({\n            id: name,\n            name,\n            ...describe(name, read.value),\n            agentId: owned[name] ?? agents.activeCone(),\n            html: read.value,\n          });\n        }\n        if (welcome !== undefined)\n          out.push({\n            id: WELCOME,\n            name: WELCOME,\n            ...describe(WELCOME, welcome),\n            agentId: owned[WELCOME] ?? 'cone',\n            html: welcome,\n            inline: true,\n          });\n        sprinkles.replace(using, out);\n      };\n      const inside = async (path: unknown, using: Context) => {\n        const asked = homePath(path);\n        const real = await env.canonicalPath(asked, using);\n        return real.ok ? homePath(real.value) : asked;\n      };\n      const offCone = agents.onCone(() => reload(context).catch(() => undefined));\n      const find = (id: string) => sprinkles.value.find((item) => item.id === id);\n      const post = async (id: string, agentId: string, using: Context) => {\n        const conversation = await agents.conversation(agentId, using);\n        if (!conversation) throw new Error(`there is no agent ${agentId}`);\n        await conversation.submit(\n          { type: 'write', entry: { kind: SPRINKLE_KIND, data: { sprinkle: id, at: Date.now() } } },\n          using\n        );\n      };\n      const setOwner = async (name: string, agentId: string, using: Context) => {\n        await harness.commit(async (tx) => {\n          (await tx.doc(SprinklesDoc)).owners[name] = agentId;\n        }, using);\n        await reload(using);\n      };\n      await reload(context);\n      const state = await harness.snapshot(SprinklesDoc, context);\n      if (welcome !== undefined && !state?.welcomed) {\n        await post(WELCOME, 'cone', context);\n        await harness.commit(async (tx) => {\n          (await tx.doc(SprinklesDoc)).welcomed = true;\n        }, context);\n      }\n      let timer: ReturnType<typeof setTimeout> | undefined;\n      const watched = await env.watch(\n        [{ path: dir, recursive: true }],\n        () => {\n          clearTimeout(timer);\n          timer = setTimeout(() => void reload(context).catch(() => undefined), options.reloadMs);\n        },\n        context\n      );\n      const watcher: FileWatcher | undefined = watched.ok ? watched.value : undefined;\n      const commands: Record<\n        string,\n        (argv: readonly string[], caller: string | null, using: Context) => Promise<Answer>\n      > = {\n        async list(_argv, _caller, using) {\n          await reload(using);\n          const rows = sprinkles.value\n            .filter((item) => !item.inline)\n            .map((item) => `${item.name}\\t${item.title}\\t${item.agentId}`);\n          return { code: 0, out: rows.length ? `${rows.join('\\n')}\\n` : 'no sprinkles\\n' };\n        },\n        async show(argv, caller, using) {\n          await reload(using);\n          const name = argv[1] ?? '';\n          if (!find(name)) return { code: 1, out: `sprinkle: there is no sprinkle ${name}\\n` };\n          const agentId = agentOf(caller, agents);\n          await post(name, agentId, using);\n          if (!(await owners(using))[name]) await setOwner(name, agentId, using);\n          return { code: 0, out: `showed ${name} in the chat of ${agentId}\\n` };\n        },\n        async own(argv, caller, using) {\n          const name = argv[1] ?? '';\n          if (!find(name)) return { code: 1, out: `sprinkle: there is no sprinkle ${name}\\n` };\n          const agentId = argv[2] ? named(agents, argv[2]) : agentOf(caller, agents);\n          if (!agentId) return { code: 1, out: `sprinkle: there is no agent ${argv[2]}\\n` };\n          await setOwner(name, agentId, using);\n          return { code: 0, out: `${name} now talks to ${agentId}\\n` };\n        },\n      };\n      return {\n        sprinkles,\n        async send(id, payload, using) {\n          const sprinkle = find(id);\n          if (!sprinkle) return { delivered: false };\n          if (id === WELCOME && payload.action === 'onboarding-complete')\n            await env.writeFile(WELCOMED, `${new Date().toISOString()}\\n`, using);\n          await licks.deliver(\n            {\n              channel: 'sprinkle',\n              source: `sprinkle:${id}`,\n              title: sprinkle.title,\n              text: payload.action || '(no action)',\n              ...(payload.data === null ? {} : { body: JSON.stringify(payload.data, null, 2) }),\n              target: targetOf((await owners(using))[id] ?? agents.activeCone()),\n            },\n            using\n          );\n          return { delivered: true };\n        },\n        async call(id, method, args, using) {\n          if (!find(id)) throw new Error(`there is no sprinkle ${id}`);\n          const handlers: Record<SprinkleMethod, () => Promise<JsonValue>> = {\n            async readFile() {\n              const read = await env.readTextFile(await inside(args[0], using), using);\n              if (!read.ok) throw new Error(read.error.message);\n              return read.value;\n            },\n            async exists() {\n              const found = await env.exists(await inside(args[0], using), using);\n              return found.ok && found.value;\n            },\n            async getState() {\n              return (await harness.snapshot(SprinklesDoc, using))?.state[id] ?? null;\n            },\n            async setState() {\n              await harness.commit(async (tx) => {\n                (await tx.doc(SprinklesDoc)).state[id] = (args[0] ?? null) as JsonValue;\n              }, using);\n              return null;\n            },\n          };\n          const handler = handlers[method as SprinkleMethod];\n          if (!handler) throw new Error(NO_EXEC);\n          return handler();\n        },\n        async command(argv, caller, using) {\n          const verb = argv[0] ?? 'help';\n          const run = commands[verb];\n          if (run) return run(argv, caller, using);\n          if (verb in RETIRED)\n            return { code: 2, out: `sprinkle ${verb} isn't in SLICC: ${RETIRED[verb]}\\n` };\n          return { code: verb === 'help' || verb === '--help' ? 0 : 2, out: USAGE };\n        },\n        reload,\n        async close(using) {\n          offCone();\n          clearTimeout(timer);\n          await watcher?.close(using);\n        },\n      };\n    },\n  };\n}\n"],
+  "mappings": "AAAA;AAAA,EAIE;AAAA,OACK;AAMP;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EAGA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;AA6BA,MAAM,QAAQ;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AASrB,MAAM,UAAkC;AAAA,EACtC,MAAM;AAAA,EACN,QAAQ;AAAA,EACR,OAAO;AAAA,EACP,MAAM;AAAA,EACN,MAAM;AACR;AAEA,SAAS,SAAS,SAA6B;AAC7C,SAAO,QAAQ,WAAW,QAAQ,IAAK,UAAyB,QAAQ,OAAO;AACjF;AAEA,SAAS,QAAQ,QAAuB,QAAwB;AAC9D,MAAI,QAAQ,WAAW,OAAO,EAAG,QAAO,OAAO,MAAM,QAAQ,MAAM;AACnE,SAAO,UAAU,OAAO,WAAW;AACrC;AAEA,SAAS,MAAM,QAAgB,OAAmC;AAChE,QAAM,QAAQ,OAAO,MAAM;AAC3B,MAAI,SAAS,MAAM,MAAO,QAAO;AACjC,QAAM,KAAK,MAAM,WAAW,QAAQ,IAAI,QAAQ,SAAS,KAAK;AAC9D,SAAO,MAAM,MAAM,SAAS,KAAK;AACnC;AAEO,SAAS,iBAAiB;AAC/B,SAAO;AAAA,IACL,MAAM,OAAO,SAA0B,SAA6C;AAClF,YAAM,EAAE,SAAS,QAAQ,OAAO,IAAI,IAAI;AACxC,YAAM,MAAM,QAAQ,OAAO;AAC3B,YAAM,YAAY,gBAA4B,CAAC,CAAC;AAChD,YAAM,UAAU,QAAQ,SACpB,MAAM,QAAQ,OAAO,2CAA2C,EAAE,MAAM,MAAM,MAAS,IACvF;AACJ,YAAM,SAAS,OAAO,WACnB,MAAM,QAAQ,SAAS,cAAc,KAAK,IAAI,UAAU,CAAC;AAC5D,YAAM,SAAS,OAAO,UAAmB;AACvC,cAAM,QAAQ,MAAM,OAAO,KAAK;AAChC,cAAM,MAAkB,CAAC;AACzB,mBAAW,EAAE,MAAM,KAAK,KAAK,MAAM,cAAc,KAAK,KAAK,KAAK,GAAG;AACjE,cAAI,SAAS,QAAS;AACtB,gBAAM,OAAO,MAAM,IAAI,aAAa,MAAM,KAAK;AAC/C,cAAI,CAAC,KAAK,GAAI;AACd,cAAI,KAAK;AAAA,YACP,IAAI;AAAA,YACJ;AAAA,YACA,GAAG,SAAS,MAAM,KAAK,KAAK;AAAA,YAC5B,SAAS,MAAM,IAAI,KAAK,OAAO,WAAW;AAAA,YAC1C,MAAM,KAAK;AAAA,UACb,CAAC;AAAA,QACH;AACA,YAAI,YAAY;AACd,cAAI,KAAK;AAAA,YACP,IAAI;AAAA,YACJ,MAAM;AAAA,YACN,GAAG,SAAS,SAAS,OAAO;AAAA,YAC5B,SAAS,MAAM,OAAO,KAAK;AAAA,YAC3B,MAAM;AAAA,YACN,QAAQ;AAAA,UACV,CAAC;AACH,kBAAU,QAAQ,OAAO,GAAG;AAAA,MAC9B;AACA,YAAM,SAAS,OAAO,MAAe,UAAmB;AACtD,cAAM,QAAQ,SAAS,IAAI;AAC3B,cAAM,OAAO,MAAM,IAAI,cAAc,OAAO,KAAK;AACjD,eAAO,KAAK,KAAK,SAAS,KAAK,KAAK,IAAI;AAAA,MAC1C;AACA,YAAM,UAAU,OAAO,OAAO,MAAM,OAAO,OAAO,EAAE,MAAM,MAAM,MAAS,CAAC;AAC1E,YAAM,OAAO,CAAC,OAAe,UAAU,MAAM,KAAK,CAAC,SAAS,KAAK,OAAO,EAAE;AAC1E,YAAM,OAAO,OAAO,IAAY,SAAiB,UAAmB;AAClE,cAAM,eAAe,MAAM,OAAO,aAAa,SAAS,KAAK;AAC7D,YAAI,CAAC,aAAc,OAAM,IAAI,MAAM,qBAAqB,OAAO,EAAE;AACjE,cAAM,aAAa;AAAA,UACjB,EAAE,MAAM,SAAS,OAAO,EAAE,MAAM,eAAe,MAAM,EAAE,UAAU,IAAI,IAAI,KAAK,IAAI,EAAE,EAAE,EAAE;AAAA,UACxF;AAAA,QACF;AAAA,MACF;AACA,YAAM,WAAW,OAAO,MAAc,SAAiB,UAAmB;AACxE,cAAM,QAAQ,OAAO,OAAO,OAAO;AACjC,WAAC,MAAM,GAAG,IAAI,YAAY,GAAG,OAAO,IAAI,IAAI;AAAA,QAC9C,GAAG,KAAK;AACR,cAAM,OAAO,KAAK;AAAA,MACpB;AACA,YAAM,OAAO,OAAO;AACpB,YAAM,QAAQ,MAAM,QAAQ,SAAS,cAAc,OAAO;AAC1D,UAAI,YAAY,UAAa,CAAC,OAAO,UAAU;AAC7C,cAAM,KAAK,SAAS,QAAQ,OAAO;AACnC,cAAM,QAAQ,OAAO,OAAO,OAAO;AACjC,WAAC,MAAM,GAAG,IAAI,YAAY,GAAG,WAAW;AAAA,QAC1C,GAAG,OAAO;AAAA,MACZ;AACA,UAAI;AACJ,YAAM,UAAU,MAAM,IAAI;AAAA,QACxB,CAAC,EAAE,MAAM,KAAK,WAAW,KAAK,CAAC;AAAA,QAC/B,MAAM;AACJ,uBAAa,KAAK;AAClB,kBAAQ,WAAW,MAAM,KAAK,OAAO,OAAO,EAAE,MAAM,MAAM,MAAS,GAAG,QAAQ,QAAQ;AAAA,QACxF;AAAA,QACA;AAAA,MACF;AACA,YAAM,UAAmC,QAAQ,KAAK,QAAQ,QAAQ;AACtE,YAAM,WAGF;AAAA,QACF,MAAM,KAAK,OAAO,SAAS,OAAO;AAChC,gBAAM,OAAO,KAAK;AAClB,gBAAM,OAAO,UAAU,MACpB,OAAO,CAAC,SAAS,CAAC,KAAK,MAAM,EAC7B,IAAI,CAAC,SAAS,GAAG,KAAK,IAAI,IAAK,KAAK,KAAK,IAAK,KAAK,OAAO,EAAE;AAC/D,iBAAO,EAAE,MAAM,GAAG,KAAK,KAAK,SAAS,GAAG,KAAK,KAAK,IAAI,CAAC;AAAA,IAAO,iBAAiB;AAAA,QACjF;AAAA,QACA,MAAM,KAAK,MAAM,QAAQ,OAAO;AAC9B,gBAAM,OAAO,KAAK;AAClB,gBAAM,OAAO,KAAK,CAAC,KAAK;AACxB,cAAI,CAAC,KAAK,IAAI,EAAG,QAAO,EAAE,MAAM,GAAG,KAAK,kCAAkC,IAAI;AAAA,EAAK;AACnF,gBAAM,UAAU,QAAQ,QAAQ,MAAM;AACtC,gBAAM,KAAK,MAAM,SAAS,KAAK;AAC/B,cAAI,EAAE,MAAM,OAAO,KAAK,GAAG,IAAI,EAAG,OAAM,SAAS,MAAM,SAAS,KAAK;AACrE,iBAAO,EAAE,MAAM,GAAG,KAAK,UAAU,IAAI,mBAAmB,OAAO;AAAA,EAAK;AAAA,QACtE;AAAA,QACA,MAAM,IAAI,MAAM,QAAQ,OAAO;AAC7B,gBAAM,OAAO,KAAK,CAAC,KAAK;AACxB,cAAI,CAAC,KAAK,IAAI,EAAG,QAAO,EAAE,MAAM,GAAG,KAAK,kCAAkC,IAAI;AAAA,EAAK;AACnF,gBAAM,UAAU,KAAK,CAAC,IAAI,MAAM,QAAQ,KAAK,CAAC,CAAC,IAAI,QAAQ,QAAQ,MAAM;AACzE,cAAI,CAAC,QAAS,QAAO,EAAE,MAAM,GAAG,KAAK,+BAA+B,KAAK,CAAC,CAAC;AAAA,EAAK;AAChF,gBAAM,SAAS,MAAM,SAAS,KAAK;AACnC,iBAAO,EAAE,MAAM,GAAG,KAAK,GAAG,IAAI,iBAAiB,OAAO;AAAA,EAAK;AAAA,QAC7D;AAAA,MACF;AACA,aAAO;AAAA,QACL;AAAA,QACA,MAAM,KAAK,IAAI,SAAS,OAAO;AAC7B,gBAAM,WAAW,KAAK,EAAE;AACxB,cAAI,CAAC,SAAU,QAAO,EAAE,WAAW,MAAM;AACzC,cAAI,OAAO,WAAW,QAAQ,WAAW;AACvC,kBAAM,IAAI,UAAU,UAAU,IAAG,oBAAI,KAAK,GAAE,YAAY,CAAC;AAAA,GAAM,KAAK;AACtE,gBAAM,MAAM;AAAA,YACV;AAAA,cACE,SAAS;AAAA,cACT,QAAQ,YAAY,EAAE;AAAA,cACtB,OAAO,SAAS;AAAA,cAChB,MAAM,QAAQ,UAAU;AAAA,cACxB,GAAI,QAAQ,SAAS,OAAO,CAAC,IAAI,EAAE,MAAM,KAAK,UAAU,QAAQ,MAAM,MAAM,CAAC,EAAE;AAAA,cAC/E,QAAQ,UAAU,MAAM,OAAO,KAAK,GAAG,EAAE,KAAK,OAAO,WAAW,CAAC;AAAA,YACnE;AAAA,YACA;AAAA,UACF;AACA,iBAAO,EAAE,WAAW,KAAK;AAAA,QAC3B;AAAA,QACA,MAAM,KAAK,IAAI,QAAQ,MAAM,OAAO;AAClC,cAAI,CAAC,KAAK,EAAE,EAAG,OAAM,IAAI,MAAM,wBAAwB,EAAE,EAAE;AAC3D,gBAAM,WAA6D;AAAA,YACjE,MAAM,WAAW;AACf,oBAAM,OAAO,MAAM,IAAI,aAAa,MAAM,OAAO,KAAK,CAAC,GAAG,KAAK,GAAG,KAAK;AACvE,kBAAI,CAAC,KAAK,GAAI,OAAM,IAAI,MAAM,KAAK,MAAM,OAAO;AAChD,qBAAO,KAAK;AAAA,YACd;AAAA,YACA,MAAM,SAAS;AACb,oBAAM,QAAQ,MAAM,IAAI,OAAO,MAAM,OAAO,KAAK,CAAC,GAAG,KAAK,GAAG,KAAK;AAClE,qBAAO,MAAM,MAAM,MAAM;AAAA,YAC3B;AAAA,YACA,MAAM,WAAW;AACf,sBAAQ,MAAM,QAAQ,SAAS,cAAc,KAAK,IAAI,MAAM,EAAE,KAAK;AAAA,YACrE;AAAA,YACA,MAAM,WAAW;AACf,oBAAM,QAAQ,OAAO,OAAO,OAAO;AACjC,iBAAC,MAAM,GAAG,IAAI,YAAY,GAAG,MAAM,EAAE,IAAK,KAAK,CAAC,KAAK;AAAA,cACvD,GAAG,KAAK;AACR,qBAAO;AAAA,YACT;AAAA,UACF;AACA,gBAAM,UAAU,SAAS,MAAwB;AACjD,cAAI,CAAC,QAAS,OAAM,IAAI,MAAM,OAAO;AACrC,iBAAO,QAAQ;AAAA,QACjB;AAAA,QACA,MAAM,QAAQ,MAAM,QAAQ,OAAO;AACjC,gBAAM,OAAO,KAAK,CAAC,KAAK;AACxB,gBAAM,MAAM,SAAS,IAAI;AACzB,cAAI,IAAK,QAAO,IAAI,MAAM,QAAQ,KAAK;AACvC,cAAI,QAAQ;AACV,mBAAO,EAAE,MAAM,GAAG,KAAK,YAAY,IAAI,oBAAoB,QAAQ,IAAI,CAAC;AAAA,EAAK;AAC/E,iBAAO,EAAE,MAAM,SAAS,UAAU,SAAS,WAAW,IAAI,GAAG,KAAK,MAAM;AAAA,QAC1E;AAAA,QACA;AAAA,QACA,MAAM,MAAM,OAAO;AACjB,kBAAQ;AACR,uBAAa,KAAK;AAClB,gBAAM,SAAS,MAAM,KAAK;AAAA,QAC5B;AAAA,MACF;AAAA,IACF;AAAA,EACF;AACF;",
+  "names": []
+}

package/dist/sprinkles/kind.js

@@ -0,0 +1,5 @@
+const SPRINKLE_KIND = "slicc.sprinkle";
+export {
+  SPRINKLE_KIND
+};
+//# sourceMappingURL=kind.js.map

package/dist/sprinkles/kind.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/sprinkles/kind.ts"],
+  "sourcesContent": ["export const SPRINKLE_KIND = 'slicc.sprinkle';\n\nexport interface Sprinkle {\n  id: string;\n  name: string;\n  title: string;\n  icon: string;\n  agentId: string;\n  html: string;\n  inline?: boolean;\n}\n"],
+  "mappings": "AAAO,MAAM,gBAAgB;",
+  "names": []
+}

package/dist/sprinkles/sprinkles.js

@@ -0,0 +1,65 @@
+import { defineDoc } from "@earendil-works/pi-durable";
+import { normalize } from "../kernel/paths.js";
+import { SPRINKLE_KIND } from "./kind.js";
+const SPRINKLES_DIR = "/home/sprinkles";
+const WELCOME = "welcome";
+const WELCOMED = "/home/.welcomed";
+const DEFAULT_ICON = "sparkles";
+const SprinklesDoc = defineDoc({
+  kind: "slicc.sprinkles",
+  version: 1,
+  scope: "session",
+  initial: () => ({ owners: {}, state: {}, welcomed: false })
+});
+function decode(text) {
+  return text.replace(/&lt;/g, "<").replace(/&gt;/g, ">").replace(/&quot;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&");
+}
+function describe(name, html) {
+  const title = /<title>([\s\S]*?)<\/title>/i.exec(html)?.[1]?.trim();
+  const icon = /<link\b[^>]*\brel=["']icon["'][^>]*\bhref=["']([^"']+)["']/i.exec(html)?.[1] ?? /<link\b[^>]*\bhref=["']([^"']+)["'][^>]*\brel=["']icon["']/i.exec(html)?.[1];
+  return { title: title ? decode(title) : name, icon: icon ?? DEFAULT_ICON };
+}
+const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+async function sprinkleFiles(env, dir, context) {
+  const listed = await env.listDir(dir, context);
+  if (!listed.ok) return [];
+  const out = /* @__PURE__ */ new Map();
+  for (const entry of [...listed.value].sort((a, b) => a.name.localeCompare(b.name))) {
+    if (entry.kind !== "directory" && entry.name.endsWith(".shtml")) {
+      const name = entry.name.slice(0, -".shtml".length);
+      if (NAME.test(name)) out.set(name, `${dir}/${entry.name}`);
+    }
+    if (entry.kind === "directory" && NAME.test(entry.name) && !out.has(entry.name)) {
+      const inner = await env.listDir(`${dir}/${entry.name}`, context);
+      if (inner.ok && inner.value.some((item) => item.name === `${entry.name}.shtml`))
+        out.set(entry.name, `${dir}/${entry.name}/${entry.name}.shtml`);
+    }
+  }
+  return [...out].map(([name, path]) => ({ name, path }));
+}
+function homePath(path) {
+  if (typeof path !== "string" || !path) throw new Error("a sprinkle reads files by absolute path");
+  const mapped = path.startsWith("/shared/") ? `/home/${path.slice("/shared/".length)}` : path;
+  const segments = mapped.split("/");
+  if (segments.includes(".") || segments.includes(".."))
+    throw new Error(`a sprinkle reads paths without . or .. segments, not ${path}`);
+  const resolved = normalize(mapped);
+  if (resolved !== "/home" && !resolved.startsWith("/home/"))
+    throw new Error(`a sprinkle can only read files in /home, not ${path}`);
+  return resolved;
+}
+const NO_EXEC = "sprinkles can't run commands in SLICC; send the agent a message with slicc.lick() and let it run them";
+export {
+  DEFAULT_ICON,
+  NAME,
+  NO_EXEC,
+  SPRINKLES_DIR,
+  SPRINKLE_KIND,
+  SprinklesDoc,
+  WELCOME,
+  WELCOMED,
+  describe,
+  homePath,
+  sprinkleFiles
+};
+//# sourceMappingURL=sprinkles.js.map

package/dist/sprinkles/sprinkles.js.map

@@ -0,0 +1,7 @@
+{
+  "version": 3,
+  "sources": ["../../src/sprinkles/sprinkles.ts"],
+  "sourcesContent": ["import type { Context, JsonValue } from '@earendil-works/chord';\nimport { defineDoc } from '@earendil-works/pi-durable';\nimport type { ExecutionEnv } from '@earendil-works/pi-durable/env';\nimport { normalize } from '../kernel/paths.ts';\n\nexport { SPRINKLE_KIND, type Sprinkle } from './kind.ts';\n\nexport const SPRINKLES_DIR = '/home/sprinkles';\nexport const WELCOME = 'welcome';\nexport const WELCOMED = '/home/.welcomed';\nexport const DEFAULT_ICON = 'sparkles';\n\nexport type SprinkleMethod = 'readFile' | 'exists' | 'getState' | 'setState';\n\nexport const SprinklesDoc = defineDoc<{\n  owners: Record<string, string>;\n  state: Record<string, JsonValue>;\n  welcomed: boolean;\n}>({\n  kind: 'slicc.sprinkles',\n  version: 1,\n  scope: 'session',\n  initial: () => ({ owners: {}, state: {}, welcomed: false }),\n});\n\nfunction decode(text: string): string {\n  return text\n    .replace(/&lt;/g, '<')\n    .replace(/&gt;/g, '>')\n    .replace(/&quot;/g, '\"')\n    .replace(/&#39;/g, \"'\")\n    .replace(/&amp;/g, '&');\n}\n\nexport function describe(name: string, html: string): { title: string; icon: string } {\n  const title = /<title>([\\s\\S]*?)<\\/title>/i.exec(html)?.[1]?.trim();\n  const icon =\n    /<link\\b[^>]*\\brel=[\"']icon[\"'][^>]*\\bhref=[\"']([^\"']+)[\"']/i.exec(html)?.[1] ??\n    /<link\\b[^>]*\\bhref=[\"']([^\"']+)[\"'][^>]*\\brel=[\"']icon[\"']/i.exec(html)?.[1];\n  return { title: title ? decode(title) : name, icon: icon ?? DEFAULT_ICON };\n}\n\nexport const NAME = /^[a-z0-9][a-z0-9._-]{0,63}$/;\n\nexport async function sprinkleFiles(\n  env: Pick<ExecutionEnv, 'listDir'>,\n  dir: string,\n  context: Context\n): Promise<{ name: string; path: string }[]> {\n  const listed = await env.listDir(dir, context);\n  if (!listed.ok) return [];\n  const out = new Map<string, string>();\n  for (const entry of [...listed.value].sort((a, b) => a.name.localeCompare(b.name))) {\n    if (entry.kind !== 'directory' && entry.name.endsWith('.shtml')) {\n      const name = entry.name.slice(0, -'.shtml'.length);\n      if (NAME.test(name)) out.set(name, `${dir}/${entry.name}`);\n    }\n    if (entry.kind === 'directory' && NAME.test(entry.name) && !out.has(entry.name)) {\n      const inner = await env.listDir(`${dir}/${entry.name}`, context);\n      if (inner.ok && inner.value.some((item) => item.name === `${entry.name}.shtml`))\n        out.set(entry.name, `${dir}/${entry.name}/${entry.name}.shtml`);\n    }\n  }\n  return [...out].map(([name, path]) => ({ name, path }));\n}\n\nexport function homePath(path: unknown): string {\n  if (typeof path !== 'string' || !path) throw new Error('a sprinkle reads files by absolute path');\n  const mapped = path.startsWith('/shared/') ? `/home/${path.slice('/shared/'.length)}` : path;\n  const segments = mapped.split('/');\n  if (segments.includes('.') || segments.includes('..'))\n    throw new Error(`a sprinkle reads paths without . or .. segments, not ${path}`);\n  const resolved = normalize(mapped);\n  if (resolved !== '/home' && !resolved.startsWith('/home/'))\n    throw new Error(`a sprinkle can only read files in /home, not ${path}`);\n  return resolved;\n}\n\nexport const NO_EXEC =\n  \"sprinkles can't run commands in SLICC; send the agent a message with slicc.lick() and let it run them\";\n"],
+  "mappings": "AACA,SAAS,iBAAiB;AAE1B,SAAS,iBAAiB;AAE1B,SAAS,qBAAoC;AAEtC,MAAM,gBAAgB;AACtB,MAAM,UAAU;AAChB,MAAM,WAAW;AACjB,MAAM,eAAe;AAIrB,MAAM,eAAe,UAIzB;AAAA,EACD,MAAM;AAAA,EACN,SAAS;AAAA,EACT,OAAO;AAAA,EACP,SAAS,OAAO,EAAE,QAAQ,CAAC,GAAG,OAAO,CAAC,GAAG,UAAU,MAAM;AAC3D,CAAC;AAED,SAAS,OAAO,MAAsB;AACpC,SAAO,KACJ,QAAQ,SAAS,GAAG,EACpB,QAAQ,SAAS,GAAG,EACpB,QAAQ,WAAW,GAAG,EACtB,QAAQ,UAAU,GAAG,EACrB,QAAQ,UAAU,GAAG;AAC1B;AAEO,SAAS,SAAS,MAAc,MAA+C;AACpF,QAAM,QAAQ,8BAA8B,KAAK,IAAI,IAAI,CAAC,GAAG,KAAK;AAClE,QAAM,OACJ,8DAA8D,KAAK,IAAI,IAAI,CAAC,KAC5E,8DAA8D,KAAK,IAAI,IAAI,CAAC;AAC9E,SAAO,EAAE,OAAO,QAAQ,OAAO,KAAK,IAAI,MAAM,MAAM,QAAQ,aAAa;AAC3E;AAEO,MAAM,OAAO;AAEpB,eAAsB,cACpB,KACA,KACA,SAC2C;AAC3C,QAAM,SAAS,MAAM,IAAI,QAAQ,KAAK,OAAO;AAC7C,MAAI,CAAC,OAAO,GAAI,QAAO,CAAC;AACxB,QAAM,MAAM,oBAAI,IAAoB;AACpC,aAAW,SAAS,CAAC,GAAG,OAAO,KAAK,EAAE,KAAK,CAAC,GAAG,MAAM,EAAE,KAAK,cAAc,EAAE,IAAI,CAAC,GAAG;AAClF,QAAI,MAAM,SAAS,eAAe,MAAM,KAAK,SAAS,QAAQ,GAAG;AAC/D,YAAM,OAAO,MAAM,KAAK,MAAM,GAAG,CAAC,SAAS,MAAM;AACjD,UAAI,KAAK,KAAK,IAAI,EAAG,KAAI,IAAI,MAAM,GAAG,GAAG,IAAI,MAAM,IAAI,EAAE;AAAA,IAC3D;AACA,QAAI,MAAM,SAAS,eAAe,KAAK,KAAK,MAAM,IAAI,KAAK,CAAC,IAAI,IAAI,MAAM,IAAI,GAAG;AAC/E,YAAM,QAAQ,MAAM,IAAI,QAAQ,GAAG,GAAG,IAAI,MAAM,IAAI,IAAI,OAAO;AAC/D,UAAI,MAAM,MAAM,MAAM,MAAM,KAAK,CAAC,SAAS,KAAK,SAAS,GAAG,MAAM,IAAI,QAAQ;AAC5E,YAAI,IAAI,MAAM,MAAM,GAAG,GAAG,IAAI,MAAM,IAAI,IAAI,MAAM,IAAI,QAAQ;AAAA,IAClE;AAAA,EACF;AACA,SAAO,CAAC,GAAG,GAAG,EAAE,IAAI,CAAC,CAAC,MAAM,IAAI,OAAO,EAAE,MAAM,KAAK,EAAE;AACxD;AAEO,SAAS,SAAS,MAAuB;AAC9C,MAAI,OAAO,SAAS,YAAY,CAAC,KAAM,OAAM,IAAI,MAAM,yCAAyC;AAChG,QAAM,SAAS,KAAK,WAAW,UAAU,IAAI,SAAS,KAAK,MAAM,WAAW,MAAM,CAAC,KAAK;AACxF,QAAM,WAAW,OAAO,MAAM,GAAG;AACjC,MAAI,SAAS,SAAS,GAAG,KAAK,SAAS,SAAS,IAAI;AAClD,UAAM,IAAI,MAAM,wDAAwD,IAAI,EAAE;AAChF,QAAM,WAAW,UAAU,MAAM;AACjC,MAAI,aAAa,WAAW,CAAC,SAAS,WAAW,QAAQ;AACvD,UAAM,IAAI,MAAM,gDAAgD,IAAI,EAAE;AACxE,SAAO;AACT;AAEO,MAAM,UACX;",
+  "names": []
+}

package/dist/types/client.d.ts

@@ -1,6 +1,7 @@
 import { type Context, type ReplicatedState } from '@earendil-works/chord';
 import type { ConversationView } from '@earendil-works/pi-durable';
 import { AgentControl, AgentSettings, type AgentsSummary, type Command, type Delivered, type SendMode } from './services.ts';
+import type { Sprinkle } from './sprinkles/kind.ts';
 import { type PortEndpoint } from './wire.ts';
 export interface AgentConnection {
     readonly serverId: string;
@@ -10,6 +11,7 @@ export interface AgentConnection {
     readonly agents?: ReplicatedState<AgentsSummary>;
     readonly views?: ReplicatedState<Record<string, ConversationView>>;
     readonly commands?: ReplicatedState<Command[]>;
+    readonly sprinkles?: ReplicatedState<Sprinkle[]>;
     readonly settings: AgentSettings;
     prompt(text: string, whenBusy?: SendMode): Promise<string>;
     close(): Promise<void>;

package/dist/types/control.d.ts

@@ -5,6 +5,7 @@ import type { LickSources, Licks } from './licks/index.ts';
 import type { Scoops, ScoopsRuntime } from './scoops/index.ts';
 import type { AgentControl } from './services.ts';
 import type { SkillsRuntime } from './skills/index.ts';
+import type { SprinklesRuntime } from './sprinkles/index.ts';
 export interface HostLicks {
     licks: Licks;
     sources: LickSources;
@@ -15,4 +16,4 @@ export interface HostScoops {
 }
 export declare function readable(out: string): string;
 export declare function submissionId(value: string): SubmissionId | undefined;
-export declare function createAgentControl(harness: Harness, target: Conversation | Cones, deliveries?: Deliveries, licks?: HostLicks, scoops?: HostScoops, skills?: Pick<SkillsRuntime, 'expand'>): AgentControl;
+export declare function createAgentControl(harness: Harness, target: Conversation | Cones, deliveries?: Deliveries, licks?: HostLicks, scoops?: HostScoops, skills?: Pick<SkillsRuntime, 'expand'>, sprinkles?: Pick<SprinklesRuntime, 'send' | 'call'>): AgentControl;

package/dist/types/host.d.ts

@@ -3,6 +3,7 @@ import type { Agent } from './agent.ts';
 import { type HostLicks, type HostScoops } from './control.ts';
 import { AgentSettings } from './services.ts';
 import type { SkillsRuntime } from './skills/index.ts';
+import type { SprinklesRuntime } from './sprinkles/index.ts';
 import type { PortEndpoint } from './wire.ts';
 export interface AgentHost {
     readonly serverId: string;
@@ -17,4 +18,5 @@ export declare function hostAgent(agent: Agent, options?: {
     licks?: HostLicks;
     scoops?: HostScoops;
     skills?: SkillsRuntime;
+    sprinkles?: SprinklesRuntime;
 }): Promise<AgentHost>;

package/dist/types/scoops/cli.d.ts

@@ -19,6 +19,7 @@ export interface CliOptions {
     roles: () => Promise<Roles>;
     alive?: (pid: number) => Promise<boolean>;
     now?: () => number;
+    sprinkle?: (argv: readonly string[], caller: string | null, context: Context) => Promise<Answer>;
 }
 export type Deps = CliOptions & {
     now: () => number;

package/dist/types/scoops/index.d.ts

@@ -5,6 +5,7 @@ import { type Agents } from '../agents.ts';
 import type { ProcessGroups } from '../kernel/groups.ts';
 import type { Licks } from '../licks/licks.ts';
 import { type Roles } from '../roles/roles.ts';
+import { type CliOptions } from './cli.ts';
 import { type ControlPlane } from './requests.ts';
 import { type Scoops } from './service.ts';
 export declare const BUILTIN_ROLES: string[];
@@ -23,6 +24,7 @@ export interface AttachOptions {
     sweepEvery?: number;
     alive?: (pid: number) => Promise<boolean>;
     reads: () => readonly string[];
+    sprinkle?: CliOptions['sprinkle'];
 }
 export interface ScoopsRuntime {
     roles(context: Context): Promise<Roles>;

package/dist/types/scoops/requests.d.ts

@@ -6,7 +6,7 @@ export declare const PROTOCOL = "slicc-agent/1";
 export declare const STALE_MS: number;
 export interface Request {
     id: string;
-    as: 'agent' | 'subagent';
+    as: 'agent' | 'subagent' | 'sprinkle';
     caller: string;
     cwd: string;
     pid: number | null;

package/dist/types/services.d.ts

@@ -1,5 +1,6 @@
-import { type Context, type ReplicatedState } from '@earendil-works/chord';
+import { type Context, type JsonValue, type ReplicatedState } from '@earendil-works/chord';
 import type { ConversationView } from '@earendil-works/pi-durable';
+import type { Sprinkle } from './sprinkles/kind.ts';
 export type SendMode = 'steer' | 'followUp' | 'reject';
 export interface SendRequest {
     text: string;
@@ -52,6 +53,14 @@ export interface AgentControl {
     unqueue(agentId: string | null, submissionId: string, context: Context): Promise<{
         outcome: 'withdrawn' | 'already_placed' | 'not_found';
     }>;
+    sprinkleSend(sprinkleId: string, payload: {
+        action: string;
+        data: JsonValue | null;
+        target: string | null;
+    }, context: Context): Promise<{
+        delivered: boolean;
+    }>;
+    sprinkleCall(sprinkleId: string, method: string, args: JsonValue[], context: Context): Promise<JsonValue>;
 }
 export type Created = {
     id: string;
@@ -110,6 +119,7 @@ export interface AgentTranscript {
     readonly agents: ReplicatedState<AgentsSummary>;
     readonly views: ReplicatedState<Record<string, ConversationView>>;
     readonly commands: ReplicatedState<Command[]>;
+    readonly sprinkles: ReplicatedState<Sprinkle[]>;
 }
 export interface Command {
     name: string;

package/dist/types/spectrum/index.d.ts

@@ -1,10 +1,12 @@
 import type { AgentConnection } from '../client.ts';
 import { AgentAdapter } from './agent-port.ts';
 import { type Login, SettingsAdapter } from './settings-port.ts';
+import { SprinkleAdapter } from './sprinkle-port.ts';
 import { TrayAdapter } from './tray-port.ts';
 export { AgentAdapter, CONE } from './agent-port.ts';
 export { assistant, errorAction, errorPart, isBusy, queued, textOf, toMessages, } from './messages.ts';
 export { type Login, SETTINGS_KEY, SettingsAdapter } from './settings-port.ts';
+export { SprinkleAdapter } from './sprinkle-port.ts';
 export { TrayAdapter } from './tray-port.ts';
 export declare function createAgentModel(connection: AgentConnection, options?: {
     storage?: Pick<Storage, 'getItem' | 'setItem'> | null;
@@ -13,4 +15,5 @@ export declare function createAgentModel(connection: AgentConnection, options?:
     agent: AgentAdapter;
     settings: SettingsAdapter;
     tray: TrayAdapter;
+    sprinkles: SprinkleAdapter;
 };

package/dist/types/spectrum/sprinkle-port.d.ts

@@ -0,0 +1,10 @@
+import type { Sprinkle, SprinkleEvents, SprinklePort } from '@ai-ecoverse/slicc-spectrum/ui';
+import type { AgentConnection } from '../client.ts';
+import { Emitter } from './emitter.ts';
+export declare class SprinkleAdapter extends Emitter<SprinkleEvents> implements SprinklePort {
+    #private;
+    constructor(connection: AgentConnection);
+    list(): readonly Sprinkle[];
+    send(id: string, payload: unknown): void;
+    call(id: string, method: string, args: readonly unknown[]): Promise<unknown>;
+}

package/dist/types/sprinkles/index.d.ts

@@ -0,0 +1,38 @@
+import { type Context, type JsonValue, type ReplicatedState } from '@earendil-works/chord';
+import type { Harness } from '@earendil-works/pi-durable';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+import type { Agents } from '../agents.ts';
+import type { Licks } from '../licks/licks.ts';
+import { type Sprinkle } from './sprinkles.ts';
+export type Answer = {
+    code: number;
+    out: string;
+};
+export interface SprinklePayload {
+    action: string;
+    data: JsonValue | null;
+    target: string | null;
+}
+export interface SprinklesRuntime {
+    readonly sprinkles: ReplicatedState<Sprinkle[]>;
+    send(id: string, payload: SprinklePayload, context: Context): Promise<{
+        delivered: boolean;
+    }>;
+    call(id: string, method: string, args: readonly unknown[], context: Context): Promise<JsonValue>;
+    command(argv: readonly string[], caller: string | null, context: Context): Promise<Answer>;
+    reload(context: Context): Promise<void>;
+    close(context: Context): Promise<void>;
+}
+export interface SprinklesAttach {
+    harness: Harness;
+    agents: Agents;
+    licks: Licks;
+    env: ExecutionEnv;
+    assets?: (path: string) => Promise<string>;
+    reloadMs: number;
+    dir?: string;
+}
+export declare const USAGE = "usage:\n  sprinkle list                 every sprinkle in /home/sprinkles, with its owner\n  sprinkle show <name>          show a sprinkle in your chat\n  sprinkle own <name> [<agent>] send its messages to <agent> (cone, cone-<n> or a scoop's handle)\n\nA sprinkle is an .shtml file in /home/sprinkles, as <name>.shtml or <name>/<name>.shtml.\nEvery one of them has a button in the rail; edit the file and the open panel reloads.\n";
+export declare function setupSprinkles(): {
+    attach(options: SprinklesAttach, context: Context): Promise<SprinklesRuntime>;
+};

package/dist/types/sprinkles/kind.d.ts

@@ -0,0 +1,10 @@
+export declare const SPRINKLE_KIND = "slicc.sprinkle";
+export interface Sprinkle {
+    id: string;
+    name: string;
+    title: string;
+    icon: string;
+    agentId: string;
+    html: string;
+    inline?: boolean;
+}

package/dist/types/sprinkles/sprinkles.d.ts

@@ -0,0 +1,24 @@
+import type { Context, JsonValue } from '@earendil-works/chord';
+import type { ExecutionEnv } from '@earendil-works/pi-durable/env';
+export { SPRINKLE_KIND, type Sprinkle } from './kind.ts';
+export declare const SPRINKLES_DIR = "/home/sprinkles";
+export declare const WELCOME = "welcome";
+export declare const WELCOMED = "/home/.welcomed";
+export declare const DEFAULT_ICON = "sparkles";
+export type SprinkleMethod = 'readFile' | 'exists' | 'getState' | 'setState';
+export declare const SprinklesDoc: import("@earendil-works/pi-durable").SessionDocToken<{
+    owners: Record<string, string>;
+    state: Record<string, JsonValue>;
+    welcomed: boolean;
+}>;
+export declare function describe(name: string, html: string): {
+    title: string;
+    icon: string;
+};
+export declare const NAME: RegExp;
+export declare function sprinkleFiles(env: Pick<ExecutionEnv, 'listDir'>, dir: string, context: Context): Promise<{
+    name: string;
+    path: string;
+}[]>;
+export declare function homePath(path: unknown): string;
+export declare const NO_EXEC = "sprinkles can't run commands in SLICC; send the agent a message with slicc.lick() and let it run them";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ai-ecoverse/slicc-agent",
-  "version": "3.10.0",
+  "version": "3.11.0",
   "description": "SLICC's agent core on pi durable: an agent worker, session storage, remoting and pi extensions",
   "type": "module",
   "license": "Apache-2.0",
@@ -62,7 +62,7 @@
   },
   "devDependencies": {
     "@ai-ecoverse/slicc-shared-web": "1.8.0",
-    "@ai-ecoverse/slicc-spectrum": "1.23.3",
+    "@ai-ecoverse/slicc-spectrum": "1.24.0",
     "@ai-ecoverse/wasm-bash": "5.3.0-7",
     "@ai-ecoverse/wasm-coreutils": "9.7.0-3",
     "@biomejs/biome": "2.5.15",
@@ -76,7 +76,7 @@
     "typescript": "7.0.2"
   },
   "dependencies": {
-    "@ai-ecoverse/slicc-kernel": "1.17.3",
+    "@ai-ecoverse/slicc-kernel": "1.17.4",
     "@earendil-works/chord": "1.0.4",
     "@earendil-works/pi-ai": "1.0.4",
     "@earendil-works/pi-client": "1.0.4",