@bluewombat/slots 0.6.0 → 0.7.0

package/README.md

@@ -112,16 +112,60 @@ isolated yet, and starting it would keep the operator's own config.
 | `--agent-arg VALUE`                | Appended to the CLI argv, before the prompt. Repeatable                          |
 | `--agent-home DIR`                 | Isolate the vendor process: its `HOME` is this directory. Cursor only; Claude refuses |
 | `--api-key-env NAME`               | With `--agent-home`, read `process.env[NAME]` for the vendor key. Never the value itself |
+| `--plugin-dir DIR`                 | A plugin folder of the operator's (a Mason home's `ai-plugins/core/*`). Repeatable, loaded first |
+| `--profile NAME`                   | The project's deck profile for this role, read in the working directory. Cursor only; Claude refuses |
+| `--plugins-out DIR`                | Where `--profile` is built, one folder per profile. Required with `--profile`; never the workspace |
+| `--deck-bin PATH`                  | The deck CLI. Default: the `@pinkpuma/deck` this package depends on |
 | `--id` / `--attempt` / `--context` | How a transcript is filed. Forwarded by the role                                 |
 
+### Plugins
+
+An agent starts with plugin folders, each passed to the vendor as
+`--plugin-dir`: first the `--plugin-dir` folders, in order, then what the
+project's [deck](https://github.com/tilap/pinkpuma-deck) profile resolves to.
+
+`--profile builder` runs `deck materialize -C <cwd> --profile builder --out
+<plugins-out>/builder --json` before the vendor starts. The working directory
+is the checkout the agent works on, so a role gets what the project committed
+at that commit — the base `ai-plugin.json` and `.ai/profiles/builder/`, as their
+locks pin them — never what the operator has installed. deck refuses a request
+no committed lock pins, and the wrapper then refuses before the vendor starts
+(`Run deck install in the project and commit its locks`). Every Attempt of the
+role refuses the same way until the project is fixed; `mason doctor` says so
+first.
+
+| The project has                         | The agent gets                       |
+| --------------------------------------- | ------------------------------------ |
+| `.ai/profiles/<name>/ai-plugin.json`    | the base and that profile            |
+| only a base `ai-plugin.json`            | the base, and a note on stderr       |
+| no deck file at all                     | the `--plugin-dir` folders only      |
+
+A non-empty `.ai/profiles/<name>/prompt.md` is appended to the filled prompt
+under `## Project instructions for this role`: what the project wants from that
+role, next to what Mason asks.
+
+The plugins keep their hooks: deck writes a plugin's `hooks/hooks.json` as its
+author did. `cursor-agent` ran a Claude-format one (`${CLAUDE_PLUGIN_ROOT}`,
+`PostToolUse` on edits) on a real run; a hook that runs is part of the agent's
+time and of what it reads back.
+
+deck's cache (`~/.cache/pinkpuma-deck`, or `DECK_CACHE`) has no lock, and
+`--plugins-out` holds one folder per profile: both rely on a Mason run starting
+one agent at a time, which it does.
+
+`claude.mjs` takes `--plugin-dir` but refuses `--profile`: not isolated, Claude
+also loads the operator's plugins and the project's `.claude/settings.json`, so
+a role's profile would not be all it gets.
+
 The agent CLI prints **one JSON line** — a `SerializedRun` from
-`@bluewombat/slot-kit` — with the vendor's raw streams plus three extras the
+`@bluewombat/slot-kit` — with the vendor's raw streams plus the extras the
 wrapper fills when it can:
 
 | Field    | Meaning                                                                                                                                              |
 | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `skills` | `null` = unknown (not stream-json, or unparseable). `[]` = looked, none used. Otherwise skill names in order                                         |
 | `usage`  | `null` = unknown. Otherwise token counts (`input`, `output`, `cacheRead`, `cacheWrite`) and `costUsd` (`null` when the vendor did not report a cost) |
+| `plugins` | Absent when no plugin folder was loaded. Otherwise each folder: `id`, `path`, `from` (`local` or `deck`), and `integrity` (deck's, `null` for a local one) |
 | `tools`  | `null` = unknown (not stream-json, or unparseable). Otherwise what the agent did with its tools: `calls` per tool name, `busyMs` (time with a tool running; `null` when the stream has no times, as Claude's), and the lists `web` (pages fetched, searches, URLs a shell command named), `mcp` (`server/tool`, plus `getMcpTools` when the agent only listed a server's tools), `subagents` (by description), `outside` (paths named outside the working directory, skill files excepted) |
 
 Cursor extracts skills from `stream-json` `readToolCall` paths ending in
@@ -134,8 +178,8 @@ Claude's `tool_use` blocks (`WebFetch`, `WebSearch`, `Bash`, `Task`,
 future vendor agent (`codex.mjs`, …) uses the same fields: leave them `null`
 when it cannot tell.
 
-When `--transcript-dir` is set, the transcript header repeats `skills`,
-`usage` and the tools — `tools`, `web`, `mcp`, `subagents`, `outside the
+When `--transcript-dir` is set, the transcript header lists the `plugins` and
+repeats `skills`, `usage` and the tools — `tools`, `web`, `mcp`, `subagents`, `outside the
 workspace` — each `unknown`, `(none)`, or the values. "Did it read the page I
 linked?" is answered there, without reading the stream.
 

package/agents/agent-plugins.mjs

@@ -0,0 +1,231 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { createRequire } from "node:module";
+import { basename, dirname, join, resolve } from "node:path";
+import { listOption, textOption } from "@bluewombat/slot-kit";
+
+// The plugin folders an agent starts with, shared by every vendor wrapper.
+//
+//   --plugin-dir DIR      a folder of the operator's own (the Mason home's
+//                         core plugins). Repeatable, loaded first, in order
+//   --profile NAME        the project's deck profile for this role: the base
+//                         and that profile, as the project's locks pin them
+//   --plugins-out DIR     where the profile is materialized, one folder per
+//                         profile. Required with --profile: never the
+//                         workspace, whose tree the Gates read
+//   --deck-bin PATH       the deck CLI. Default: the @pinkpuma/deck this
+//                         package depends on
+//
+// The profile is read from the working directory — the checkout the agent
+// works on — so a role gets what the project committed at that commit, not
+// what the operator has installed. Agents of one Mason run one at a time,
+// which is why one folder per profile is enough.
+
+const PROFILE_NAME = /^[A-Za-z0-9_-][A-Za-z0-9._-]*$/;
+
+/**
+ * @typedef {import("@bluewombat/slot-kit").AgentPlugin} AgentPlugin
+ * @typedef {{ ok: true, plugins: AgentPlugin[], prompt: string | undefined, notes: string[] }
+ *   | { ok: false, reason: string }} LoadedPlugins
+ */
+
+/**
+ * @param {import("@bluewombat/slot-kit").OptionValues} options
+ * @param {string} cwd
+ * @returns {LoadedPlugins}
+ */
+export function loadPlugins(options, cwd) {
+  /** @type {AgentPlugin[]} */
+  const plugins = [];
+  for (const dir of listOption(options, "pluginDir")) {
+    const path = resolve(cwd, dir);
+    if (!isDirectory(path)) {
+      return { ok: false, reason: `The --plugin-dir ${dir} is not a folder.` };
+    }
+    plugins.push({ id: pluginId(path), path, from: "local", integrity: null });
+  }
+  const profile = textOption(options, "profile");
+  if (profile === undefined) {
+    return { ok: true, plugins, prompt: undefined, notes: [] };
+  }
+  if (!PROFILE_NAME.test(profile) || profile === "current") {
+    return { ok: false, reason: `The --profile "${profile}" is not a deck profile name.` };
+  }
+  const out = textOption(options, "pluginsOut");
+  if (out === undefined) {
+    return {
+      ok: false,
+      reason: "--profile needs --plugins-out: the profile is built outside the workspace.",
+    };
+  }
+  const hasBase = existsSync(join(cwd, "ai-plugin.json"));
+  // deck's own rule: a profile is a folder of .ai/profiles that holds a request.
+  const hasProfile = existsSync(join(cwd, ".ai", "profiles", profile, "ai-plugin.json"));
+  if (!hasBase && !hasProfile) {
+    return {
+      ok: true,
+      plugins,
+      prompt: undefined,
+      notes: [`The project has no deck setup: no plugin for profile ${profile}.`],
+    };
+  }
+  const deck = deckBin(options);
+  if (!deck.ok) {
+    return deck;
+  }
+  const args = [
+    deck.path,
+    "materialize",
+    "-C",
+    cwd,
+    "--out",
+    resolve(cwd, out, profile),
+    "--json",
+    ...(hasProfile ? ["--profile", profile] : []),
+  ];
+  // No timeout: this runs inside the agent wrapper's own process group, so
+  // the slot's deadline ends deck with it.
+  const run = spawnSync(process.execPath, args, { cwd, encoding: "utf8" });
+  if (run.error !== undefined || run.status !== 0) {
+    const said = (run.stderr || run.error?.message || `exit ${run.status}`).trim();
+    return {
+      ok: false,
+      reason: `deck materialize refused profile ${profile}: ${said} Run deck install in the project and commit its locks.`,
+    };
+  }
+  const result = parseMaterialized(run.stdout);
+  if (result === undefined) {
+    return { ok: false, reason: `deck materialize answered no JSON for profile ${profile}.` };
+  }
+  for (const plugin of result.plugins) {
+    plugins.push({ ...plugin, from: "deck" });
+  }
+  return {
+    ok: true,
+    plugins,
+    prompt: profilePrompt(result.prompt),
+    notes: hasProfile ? [] : [`The project has no deck profile ${profile}: base plugins only.`],
+  };
+}
+
+/**
+ * The filled prompt, then the project's own words for this role.
+ *
+ * @param {string} prompt
+ * @param {string | undefined} profilePromptText
+ * @returns {string}
+ */
+export function withProfilePrompt(prompt, profilePromptText) {
+  if (profilePromptText === undefined) {
+    return prompt;
+  }
+  return `${prompt.trimEnd()}\n\n## Project instructions for this role\n\n${profilePromptText}\n`;
+}
+
+/**
+ * `--plugin-dir` once per plugin folder: what both Cursor and Claude read.
+ *
+ * @param {readonly AgentPlugin[]} plugins
+ * @returns {string[]}
+ */
+export function pluginDirArgs(plugins) {
+  return plugins.flatMap((plugin) => ["--plugin-dir", plugin.path]);
+}
+
+/**
+ * @param {import("@bluewombat/slot-kit").OptionValues} options
+ * @returns {{ ok: true, path: string } | { ok: false, reason: string }}
+ */
+function deckBin(options) {
+  const given = textOption(options, "deckBin");
+  if (given !== undefined) {
+    return { ok: true, path: resolve(given) };
+  }
+  try {
+    const manifest = createRequire(import.meta.url).resolve("@pinkpuma/deck/package.json");
+    return { ok: true, path: join(dirname(manifest), "bin", "deck.js") };
+  } catch {
+    return {
+      ok: false,
+      reason:
+        "@pinkpuma/deck is not installed next to @bluewombat/slots. Install it, or pass --deck-bin.",
+    };
+  }
+}
+
+/**
+ * @param {string} stdout
+ * @returns {{ prompt: string | null, plugins: { id: string, path: string, integrity: string | null }[] } | undefined}
+ */
+function parseMaterialized(stdout) {
+  let raw;
+  try {
+    raw = JSON.parse(stdout);
+  } catch {
+    return undefined;
+  }
+  if (raw === null || typeof raw !== "object" || !Array.isArray(raw.plugins)) {
+    return undefined;
+  }
+  const plugins = [];
+  for (const entry of raw.plugins) {
+    if (typeof entry?.id !== "string" || typeof entry?.path !== "string") {
+      return undefined;
+    }
+    plugins.push({
+      id: entry.id,
+      path: entry.path,
+      integrity: typeof entry.integrity === "string" ? entry.integrity : null,
+    });
+  }
+  return { prompt: typeof raw.prompt === "string" ? raw.prompt : null, plugins };
+}
+
+/**
+ * @param {string | null} path
+ * @returns {string | undefined}
+ */
+function profilePrompt(path) {
+  if (path === null) {
+    return undefined;
+  }
+  try {
+    const text = readFileSync(path, "utf8").trim();
+    return text.length === 0 ? undefined : text;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * The name the plugin's manifest gives, else its folder's.
+ *
+ * @param {string} dir
+ * @returns {string}
+ */
+function pluginId(dir) {
+  for (const manifest of [
+    "plugin.json",
+    ".cursor-plugin/plugin.json",
+    ".claude-plugin/plugin.json",
+  ]) {
+    try {
+      const name = JSON.parse(readFileSync(join(dir, manifest), "utf8")).name;
+      if (typeof name === "string" && name.length > 0) {
+        return name;
+      }
+    } catch {
+      // try the next manifest
+    }
+  }
+  return basename(dir);
+}
+
+/** @param {string} path */
+function isDirectory(path) {
+  try {
+    return statSync(path).isDirectory();
+  } catch {
+    return false;
+  }
+}

package/agents/claude.mjs

@@ -13,6 +13,7 @@ import {
   transcriptFor,
   writeContract,
 } from "@bluewombat/slot-kit";
+import { loadPlugins, pluginDirArgs } from "./agent-plugins.mjs";
 import { extrasFromClaude } from "./claude-extras.mjs";
 
 // Claude Code as a vendor agent. The prompt is already filled: this command
@@ -28,6 +29,11 @@ import { extrasFromClaude } from "./claude-extras.mjs";
 //   --agent-arg VALUE      appended before the prompt. Repeatable
 //   --agent-home / --api-key-env   recognised, then refused. Claude is not
 //                         isolated yet; starting would keep the operator's config
+//   --plugin-dir DIR      a plugin folder, repeatable (see agent-plugins.mjs)
+//   --profile / --plugins-out / --deck-bin   recognised, then refused for the
+//                         same reason: Claude would also load the operator's
+//                         and the project's own plugins, so a role's profile
+//                         would not be what it gets
 //   --id / --attempt / --context   how a transcript is filed
 
 const NAME = "Claude Code";
@@ -57,6 +63,15 @@ if (
     "Claude Code does not isolate the operator home yet. Remove --agent-home and --api-key-env; the vendor was not started.",
   );
 }
+if (
+  textOption(options, "profile") !== undefined ||
+  textOption(options, "pluginsOut") !== undefined ||
+  textOption(options, "deckBin") !== undefined
+) {
+  refuse(
+    "Claude Code does not isolate the operator home yet, so a deck profile would not be all it loads. Remove --profile; the vendor was not started.",
+  );
+}
 
 const loaded = readAgentPrompt(options);
 if (!loaded.ok) {
@@ -64,6 +79,12 @@ if (!loaded.ok) {
 }
 const prompt = loaded.prompt;
 
+const loadedPlugins = loadPlugins(options, cwd);
+if (!loadedPlugins.ok) {
+  refuse(loadedPlugins.reason);
+}
+const plugins = loadedPlugins.plugins;
+
 const bin = textOption(options, "bin") ?? findExecutable(CLI_NAMES, INSTALL_DIRS);
 if (bin === undefined) {
   refuse(
@@ -83,6 +104,7 @@ const args = [
   // Claude's stream-json only emits tool events with --verbose (headless docs).
   ...(outputFormat === "stream-json" ? ["--verbose"] : []),
   ...(model === undefined ? [] : ["--model", model]),
+  ...pluginDirArgs(plugins),
   ...listOption(options, "agentArg"),
   prompt,
 ];
@@ -92,6 +114,7 @@ const transcript = transcriptFor(process.argv, options, {
   bin,
   args,
   prompt,
+  plugins,
 });
 const run = await runAgent({ file: bin, args, cwd });
 const extras = extrasFromClaude(run.stdout, outputFormat, cwd);
@@ -119,6 +142,7 @@ function answer(run, binPath, extras) {
         skills: extras.skills,
         usage: extras.usage,
         tools: extras.tools,
+        plugins,
       }),
     )}\n`,
   );

package/agents/cursor.mjs

@@ -14,6 +14,7 @@ import {
   transcriptFor,
   writeContract,
 } from "@bluewombat/slot-kit";
+import { loadPlugins, pluginDirArgs, withProfilePrompt } from "./agent-plugins.mjs";
 import { extrasFromCursor } from "./cursor-extras.mjs";
 
 // Cursor CLI as a vendor agent. The prompt is already filled: this command
@@ -29,6 +30,8 @@ import { extrasFromCursor } from "./cursor-extras.mjs";
 //   --agent-home DIR      isolate this process: HOME is DIR, not the operator's
 //   --api-key-env NAME    required with --agent-home. Read process.env[NAME];
 //                         the value is never put on the argv
+//   --plugin-dir / --profile / --plugins-out / --deck-bin   plugin folders,
+//                         see agent-plugins.mjs
 //   --id / --attempt / --context   how a transcript is filed
 
 const NAME = "Cursor CLI";
@@ -47,7 +50,15 @@ const loaded = readAgentPrompt(options);
 if (!loaded.ok) {
   refuse(loaded.reason);
 }
-const prompt = loaded.prompt;
+const loadedPlugins = loadPlugins(options, cwd);
+if (!loadedPlugins.ok) {
+  refuse(loadedPlugins.reason);
+}
+for (const note of loadedPlugins.notes) {
+  process.stderr.write(`${note}\n`);
+}
+const plugins = loadedPlugins.plugins;
+const prompt = withProfilePrompt(loaded.prompt, loadedPlugins.prompt);
 
 const bin = textOption(options, "bin") ?? findExecutable(CLI_NAMES, INSTALL_DIRS);
 if (bin === undefined) {
@@ -70,6 +81,7 @@ const args = [
   "--output-format",
   outputFormat,
   ...(model === undefined ? [] : ["--model", model]),
+  ...pluginDirArgs(plugins),
   ...listOption(options, "agentArg"),
   prompt,
 ];
@@ -84,6 +96,7 @@ const transcript = transcriptFor(process.argv, options, {
   bin,
   args,
   prompt,
+  plugins,
 });
 const run = await runAgent({
   file: bin,
@@ -224,6 +237,7 @@ function answer(run, binPath, extras) {
         skills: extras.skills,
         usage: extras.usage,
         tools: extras.tools,
+        plugins,
       }),
     )}\n`,
   );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bluewombat/slots",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "description": "Shipped mason slots: Planners, Builders, Gates, publishers, and refreshers a Project names in its config.",
   "keywords": [
@@ -53,6 +53,7 @@
     "test": "tsx --test $(find test -name '*.test.ts')"
   },
   "dependencies": {
-    "@bluewombat/slot-kit": "^0.6.0"
+    "@bluewombat/slot-kit": "^0.7.0",
+    "@pinkpuma/deck": "1.0.0"
   }
 }