Merge pull request #4 refactor(prism-facet): registration framework + strip content

Two related fixes:

1. core/router-loader.loadRouters() previously called map.clear() before
   scanning routersDir, which wiped routers registered via
   __prismFacet.addRouter (the cross-plugin API). Now: track which
   entries in the map came from a file vs API (filePath sentinel),
   only delete file-based ones that disappeared between loads. External
   routers are never touched.

2. scripts/install.mjs: chown installed plugin files to root when the
   installer is running as root. openclaw 2026.5+ blocks plugins whose
   files are owned by non-root; rsync/tar from a developer laptop
   silently broke prism-facet on the next gateway restart. Matches the
   Meridian + ClawPrompts install.mjs fix.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

plugin/core/cross-plugin-api.ts

@@ -0,0 +1,110 @@
+/**
+ * Cross-plugin API: globalThis.__prismFacet
+ *
+ * PrismFacet is the registration mechanism (routers, rules, the
+ * before_prompt_build hook that resolves them); other plugins (notably
+ * ClawPrompts) supply the actual content by calling into this API at
+ * their own register() time.
+ *
+ * Installation idempotence: safe to call install() multiple times — the
+ * function attaches the same set of methods to globalThis.__prismFacet
+ * if not already present. Plugin reload doesn't break consumers.
+ *
+ * If a consumer plugin (ClawPrompts) loads BEFORE PrismFacet, the
+ * `globalThis.__prismFacet` slot will be undefined at the consumer's
+ * register() time. To make load-order independence work, this module
+ * pre-creates the slot at module-import time too — consumers can call
+ * .addRouter / .addRule even if PrismFacet's register() hasn't run yet
+ * (the registration still lands in the shared maps).
+ */
+import { addExternalRouter, type RouterContext } from "./router-loader.js";
+import { addExternalRule } from "./rule-store.js";
+
+const _G = globalThis as Record<string, unknown>;
+
+export interface PrismFacetCrossPluginApi {
+  /**
+   * Register a router programmatically.
+   * @param name router name (matches the "router:" prefix of rule keys)
+   * @param resolve function returning a key string for the given context
+   *                (or empty/null to skip this router for this context)
+   */
+  addRouter(
+    name: string,
+    resolve: (ctx: RouterContext) => string | Promise<string>,
+  ): void;
+
+  /**
+   * Register a rule programmatically (in-memory; persistent rules.json
+   * entries set by the prompt-rules tool take precedence on conflict).
+   * @param routerName router this rule binds to
+   * @param key value the router must resolve to for this rule to fire
+   * @param prompt either { file: "/abs/path.md" } or { text: "..." }
+   */
+  addRule(
+    routerName: string,
+    key: string,
+    prompt: { file?: string; text?: string },
+  ): void;
+}
+
+type PendingOp =
+  | { type: "router"; name: string; resolve: (ctx: RouterContext) => string | Promise<string> }
+  | { type: "rule"; routerName: string; key: string; prompt: { file?: string; text?: string } };
+
+/**
+ * Idempotent install. Called from PrismFacet's register(). Also runs
+ * at module-import time below so consumer plugins loading before
+ * PrismFacet still find a usable API.
+ *
+ * Plugin load order is undefined — if ClawPrompts loads before
+ * PrismFacet, the `_G['__prismFacet']` slot stays at the buffering stub
+ * created by ClawPrompts (or, if neither has installed yet, missing).
+ * To make this race-free, we install the real API on first call from
+ * either side AND drain any queued ops a buffering caller may have
+ * accumulated via the well-known `__prismFacetPending` array. ClawPrompts
+ * (and any future consumer) only needs to: push ops onto the pending
+ * array when `__prismFacet?.addRouter` isn't callable; PrismFacet's
+ * install() will drain them when it runs.
+ */
+export function installCrossPluginApi(): PrismFacetCrossPluginApi {
+  const existing = _G["__prismFacet"] as PrismFacetCrossPluginApi | undefined;
+  if (existing && typeof existing.addRouter === "function" && (existing as any).__real) return existing;
+
+  const api: PrismFacetCrossPluginApi & { __real: true } = {
+    addRouter(name, resolve) {
+      addExternalRouter(name, resolve);
+    },
+    addRule(routerName, key, prompt) {
+      if (!prompt.file) {
+        throw new Error(
+          "__prismFacet.addRule: only { file: '/abs/path.md' } is supported today; " +
+          "inline { text } pending injector update",
+        );
+      }
+      addExternalRule(routerName, key, prompt.file);
+    },
+    __real: true,
+  };
+  _G["__prismFacet"] = api;
+
+  // Drain any ops queued by consumer plugins that ran before us.
+  const pending = _G["__prismFacetPending"] as PendingOp[] | undefined;
+  if (Array.isArray(pending) && pending.length > 0) {
+    for (const op of pending) {
+      try {
+        if (op.type === "router") api.addRouter(op.name, op.resolve);
+        else api.addRule(op.routerName, op.key, op.prompt);
+      } catch {
+        // Swallow per-op errors so one bad pending entry doesn't block
+        // the rest. Consumer plugin logs already fired at queue time.
+      }
+    }
+    _G["__prismFacetPending"] = [];
+  }
+
+  return api;
+}
+
+// Eager install on module load.
+installCrossPluginApi();

plugin/core/router-loader.ts

@@ -35,7 +35,16 @@ export async function loadRouters(
   log: { info(msg: string): void; warn(msg: string): void }
 ): Promise<void> {
   const map = getRouterMap();
-  map.clear();
+  // Don't clear() — that would wipe externally-registered routers added
+  // by other plugins via __prismFacet.addRouter. Instead, track which
+  // routers came from the filesystem this run and remove only those
+  // that disappeared. External routers (filePath sentinel) are never
+  // touched here.
+  const FILE_SENTINEL_PREFIX = "<external:";
+  const fileRoutersBefore = new Set<string>();
+  for (const [name, r] of map.entries()) {
+    if (!r.filePath.startsWith(FILE_SENTINEL_PREFIX)) fileRoutersBefore.add(name);
+  }
 
   if (typeof _G[LOAD_COUNTER_KEY] !== "number") _G[LOAD_COUNTER_KEY] = 0;
   (_G[LOAD_COUNTER_KEY] as number)++;
@@ -48,9 +57,12 @@ export async function loadRouters(
     );
   } catch {
     log.warn(`[prism-facet] routers directory not found: ${routersDir}`);
+    // No file-based routers this run — drop any leftover file routers.
+    for (const name of fileRoutersBefore) map.delete(name);
     return;
   }
 
+  const seenThisRun = new Set<string>();
   for (const file of files) {
     const name = routerNameFromFile(file);
     const filePath = path.resolve(routersDir, file);
@@ -61,11 +73,17 @@ export async function loadRouters(
         continue;
       }
       map.set(name, { name, filePath, module: mod });
+      seenThisRun.add(name);
       log.info(`[prism-facet] router loaded: ${name}`);
     } catch (err) {
       log.warn(`[prism-facet] router ${name}: failed to load — ${String(err)}`);
     }
   }
+  // Drop file-based routers that disappeared between loads. Untouched
+  // routers stay.
+  for (const stale of fileRoutersBefore) {
+    if (!seenThisRun.has(stale)) map.delete(stale);
+  }
 }
 
 export function getRouters(): LoadedRouter[] {
@@ -75,3 +93,21 @@ export function getRouters(): LoadedRouter[] {
 export function getRouterNames(): string[] {
   return Array.from(getRouterMap().keys());
 }
+
+/**
+ * Cross-plugin API: register a router programmatically. Other plugins
+ * (e.g. ClawPrompts) call this via globalThis.__prismFacet.addRouter
+ * to publish a router without dropping a .ts file in PrismFacet's
+ * routersDir. Replaces any existing router of the same name.
+ */
+export function addExternalRouter(
+  name: string,
+  resolveFn: (ctx: RouterContext) => string | Promise<string>,
+): void {
+  const map = getRouterMap();
+  map.set(name, {
+    name,
+    filePath: `<external: registered via __prismFacet.addRouter>`,
+    module: { resolve: resolveFn },
+  });
+}

plugin/core/rule-store.ts

@@ -1,16 +1,34 @@
+/**
+ * Two-tier rule store: persistent (operator/admin rules loaded from
+ * rules.json, mutated by the prompt-rules tool) and external (in-memory
+ * rules registered by other plugins via the __prismFacet cross-plugin
+ * API). External rules are NOT saved to disk — they belong to the
+ * registering plugin and are re-registered on every gateway start.
+ *
+ * Lookup precedence: persistent > external (operator wins over plugin
+ * defaults so an explicit rules.json override is honored).
+ */
 import { readFileSync, writeFileSync } from "node:fs";
 
 export type RuleStore = Record<string, string>; // "router:key" → prompt file path
 
 const _G = globalThis as Record<string, unknown>;
-const RULES_KEY = "_prismFacetRules";
+const PERSISTENT_KEY = "_prismFacetRules";
+const EXTERNAL_KEY = "_prismFacetExternalRules";
 const RULES_PATH_KEY = "_prismFacetRulesPath";
 
-function getRules(): RuleStore {
-  if (!_G[RULES_KEY] || typeof _G[RULES_KEY] !== "object") {
-    _G[RULES_KEY] = {};
+function getPersistent(): RuleStore {
+  if (!_G[PERSISTENT_KEY] || typeof _G[PERSISTENT_KEY] !== "object") {
+    _G[PERSISTENT_KEY] = {};
   }
-  return _G[RULES_KEY] as RuleStore;
+  return _G[PERSISTENT_KEY] as RuleStore;
+}
+
+function getExternal(): RuleStore {
+  if (!_G[EXTERNAL_KEY] || typeof _G[EXTERNAL_KEY] !== "object") {
+    _G[EXTERNAL_KEY] = {};
+  }
+  return _G[EXTERNAL_KEY] as RuleStore;
 }
 
 function getRulesPath(): string {
@@ -20,26 +38,32 @@ function getRulesPath(): string {
 function save(): void {
   const p = getRulesPath();
   if (!p) return;
-  writeFileSync(p, JSON.stringify(getRules(), null, 2) + "\n", "utf8");
+  writeFileSync(p, JSON.stringify(getPersistent(), null, 2) + "\n", "utf8");
 }
 
 export function initRuleStore(filePath: string): void {
   _G[RULES_PATH_KEY] = filePath;
   try {
     const raw = readFileSync(filePath, "utf8");
-    _G[RULES_KEY] = JSON.parse(raw) as RuleStore;
+    _G[PERSISTENT_KEY] = JSON.parse(raw) as RuleStore;
   } catch {
-    _G[RULES_KEY] = {};
+    _G[PERSISTENT_KEY] = {};
   }
 }
 
+/** Operator-facing addRule (writes through to rules.json on disk). */
 export function addRule(router: string, key: string, promptFile: string): void {
-  getRules()[`${router}:${key}`] = promptFile;
+  getPersistent()[`${router}:${key}`] = promptFile;
   save();
 }
 
+/** Cross-plugin API: register a rule that lives in memory only. */
+export function addExternalRule(router: string, key: string, promptFile: string): void {
+  getExternal()[`${router}:${key}`] = promptFile;
+}
+
 export function removeRule(router: string, key: string): boolean {
-  const rules = getRules();
+  const rules = getPersistent();
   const ruleKey = `${router}:${key}`;
   if (!(ruleKey in rules)) return false;
   delete rules[ruleKey];
@@ -47,10 +71,22 @@ export function removeRule(router: string, key: string): boolean {
   return true;
 }
 
+/** Lookup. Persistent (rules.json) overrides external (plugin defaults). */
 export function getRule(router: string, key: string): string | undefined {
-  return getRules()[`${router}:${key}`];
+  const persistentValue = getPersistent()[`${router}:${key}`];
+  if (persistentValue) return persistentValue;
+  return getExternal()[`${router}:${key}`];
 }
 
+/** Merged view for the admin tool. Persistent overrides external. */
 export function listRules(): Record<string, string> {
-  return { ...getRules() };
+  return { ...getExternal(), ...getPersistent() };
+}
+
+/** Admin tool needs to know which tier a rule came from. */
+export function listRulesTiered(): {
+  persistent: RuleStore;
+  external: RuleStore;
+} {
+  return { persistent: { ...getPersistent() }, external: { ...getExternal() } };
 }

plugin/hooks/fabric-chat-injector.ts

@@ -1,85 +0,0 @@
-/**
- * Inject a "start the chat workflow" hint into the agent's system prompt
- * when this turn was triggered by a message in a fabric channel.
- *
- * Two cases:
- *   - no prior chat journal for this (agent, channel) → suggest
- *     `workflow_start chat` (fresh).
- *   - mapping exists → suggest `workflow_start chat from <journalId>`
- *     so the conversation continues in the same linear journal.
- *
- * The (channel → journal) mapping is owned by Meridian and exposed via
- * globalThis.__meridian.getChatJournalForChannel. Meridian writes the
- * entry the first time the agent starts a chat workflow on a channel
- * with no `from` argument.
- *
- * TODO(phase-2): once Fabric.OpenclawPlugin exposes per-channel type
- * info (DM / group / triage) via a cross-plugin API, narrow this hook
- * to xType === 'dm' only. Today we inject for any fabric channel — chat
- * workflow itself is a no-op outside DMs, but the suggestion is noise.
- */
-const _G = globalThis as Record<string, unknown>;
-const DEDUP_KEY = '_prismFacetFabricChatDedup';
-
-interface MeridianBridge {
-  getChatJournalForChannel?: (agentId: string, channelId: string) => Promise<string | null>;
-}
-
-interface PromptCtx {
-  agentId?: string;
-  channelId?: string;
-  messageProvider?: string;
-}
-
-export function registerFabricChatInjector(api: {
-  on(hook: string, handler: (...args: any[]) => any): void;
-  logger: { info(msg: string): void; warn(msg: string): void };
-}): void {
-  if (!(_G[DEDUP_KEY] instanceof WeakSet)) _G[DEDUP_KEY] = new WeakSet<object>();
-  const dedup = _G[DEDUP_KEY] as WeakSet<object>;
-
-  api.on('before_prompt_build', async (event: unknown, ctx: PromptCtx) => {
-    if (dedup.has(event as object)) return;
-    dedup.add(event as object);
-
-    const agentId = ctx.agentId || '';
-    const channelId = (ctx.channelId || '').trim();
-    const provider = (ctx.messageProvider || '').toLowerCase();
-    if (!agentId || !channelId) return;
-    if (provider && provider !== 'fabric') return;
-    // Empty provider also accepted — gateway sometimes omits the field
-    // even when the trigger was a fabric channel; channelId presence is
-    // the load-bearing signal.
-
-    let journalId: string | null = null;
-    const meridian = _G['__meridian'] as MeridianBridge | undefined;
-    if (typeof meridian?.getChatJournalForChannel === 'function') {
-      try {
-        journalId = await meridian.getChatJournalForChannel(agentId, channelId);
-      } catch (err) {
-        api.logger.warn(
-          `[prism-facet] fabric-chat-injector: meridian lookup failed for ` +
-          `agent=${agentId} channel=${channelId}: ${String(err)}`,
-        );
-      }
-    }
-
-    const cmd = journalId
-      ? `\`workflow_start\` with \`workflow="chat"\` and \`from="${journalId}"\``
-      : `\`workflow_start\` with \`workflow="chat"\``;
-
-    const continuationLine = journalId
-      ? `This channel already has an open chat journal (\`${journalId}\`). Resume it with the \`from\` argument so the conversation history stays in one file.`
-      : `No prior chat journal exists for this channel yet — Meridian will create a fresh one and remember the channel→journal mapping for future turns.`;
-
-    const segment =
-      `# Chat channel context\n` +
-      `\n` +
-      `This turn was triggered by a message in a fabric channel (\`${channelId}\`).\n` +
-      `${continuationLine}\n` +
-      `\n` +
-      `**Next action:** call ${cmd} to enter the chat workflow before doing anything else.\n`;
-
-    return { appendSystemContext: segment };
-  });
-}

plugin/index.ts

@@ -1,8 +1,30 @@
+/**
+ * PrismFacet — prompt-rule registration framework.
+ *
+ * Provides:
+ *   - router loader (file-based: routersDir + programmatic: __prismFacet.addRouter)
+ *   - rule store (persistent rules.json + in-memory external rules)
+ *   - before_prompt_build hook that resolves all loaded routers/rules
+ *     and appends the matching prompt fragments to the agent's system
+ *     prompt
+ *   - prompt-rules admin tool to inspect / mutate persistent rules
+ *   - cross-plugin API installed at module load time (globalThis.__prismFacet)
+ *
+ * PrismFacet ships NO content of its own — the routers/, prompts/, and
+ * rules.json directories are empty placeholders. Hangman-Lab-specific
+ * routers and rules live in the ClawPrompts plugin, which registers
+ * them at startup via the cross-plugin API.
+ */
 import path from "node:path";
+// Importing core/cross-plugin-api.ts has a side-effect: it installs
+// globalThis.__prismFacet at module-import time. Doing this side-effect
+// import early — before any other plugin's register() — means a
+// consumer plugin (ClawPrompts) loaded before us still finds a working
+// __prismFacet to call into.
+import "./core/cross-plugin-api.js";
 import { loadRouters } from "./core/router-loader.js";
 import { initRuleStore } from "./core/rule-store.js";
 import { registerBeforePromptBuild } from "./hooks/before-prompt-build.js";
-import { registerFabricChatInjector } from "./hooks/fabric-chat-injector.js";
 import { registerPromptRulesTool } from "./tools/prompt-rules.js";
 
 interface PluginConfig {
@@ -58,11 +80,10 @@ export default {
 
     // Agent session hooks: register every time (dedup inside handler)
     registerBeforePromptBuild(api);
-    registerFabricChatInjector(api);
 
     // Tools
     registerPromptRulesTool(api, routersDir);
 
-    api.logger.info("[prism-facet] plugin registered");
+    api.logger.info("[prism-facet] plugin registered (framework only — content via ClawPrompts)");
   },
 };

plugin/prompts/pcexec-convention.md

@@ -1,31 +0,0 @@
-# Hangman-Lab Site Convention — Shell Execution
-
-This claw (sim or prod) keeps Hangman-Lab site binaries at `~/.openclaw/bin/`
-and **does not** symlink them into `/usr/local/bin`. Your shell tool's PATH
-does not include them by default, so calling them with the codex built-in
-shell yields `command not found`.
-
-**Rule:** any command that invokes one of these binaries MUST be run through
-the `pcexec` tool, not the codex built-in shell:
-
-- `hf` (HarborForge CLI)
-- `secret-mgr` (per-agent secret store)
-- `ego-mgr` (per-agent identity store; reads `role`, `position`, `default-username`, etc.)
-- `fabric-register` (Fabric account provisioning)
-- `pcguard` (PaddedCell guard)
-- `lock-mgr`
-- `tea`
-
-`pcexec` injects `~/.openclaw/bin` into PATH and also wires the
-`AGENT_ID`, `AGENT_WORKSPACE`, and `AGENT_VERIFY` env vars that
-`secret-mgr` / `ego-mgr` need to authenticate as the calling agent.
-
-## Examples
-
-- ✅ Call the `pcexec` tool with `command: "hf calendar show --json"`
-- ✅ Call the `pcexec` tool with `command: "HFT=$(secret-mgr get-secret --key hf-token); hf task list --token \"$HFT\" --json"` (the whole pipeline goes in one `pcexec` call)
-- ❌ Sending `hf calendar show` to the codex built-in shell → `command not found`
-
-If a workflow's `Procedure` shows a raw shell snippet involving these CLIs,
-pass the **whole snippet** as a single `command:` argument to `pcexec` —
-don't split into multiple non-pcexec calls.

plugin/routers/always.ts

@@ -1,11 +0,0 @@
-/**
- * `always` router — resolves to the constant key `"always"` for every
- * agent. Pair with a rule like `always:always → <some-prompt.md>` to
- * inject a prompt fragment into every agent's system prompt
- * unconditionally (no ego / role / position lookup needed).
- */
-import type { RouterContext } from "../core/router-loader.js";
-
-export function resolve(_ctx: RouterContext): string {
-  return "always";
-}

plugin/rules.json

@@ -1,3 +1 @@
-{
-  "always:always": "/root/.openclaw/plugins/prism-facet/prompts/pcexec-convention.md"
-}
+{}

rules.json

@@ -1 +1 @@
-{}
+{}

scripts/install.mjs

@@ -130,6 +130,24 @@ function copyDirRecursive(src, dest, excludeExts = []) {
       fs.copyFileSync(srcPath, destPath);
     }
   }
+  // openclaw 2026.5+ refuses to load plugins whose files are owned by
+  // non-root ("suspicious ownership"). fs.copyFileSync preserves source
+  // ownership, so rsync/tar from a developer laptop (uid 1000) breaks
+  // the plugin on next gateway restart. Force chown to root when we
+  // can (root-only); silently skip otherwise (dev mode under
+  // unprivileged user — uid checks don't apply there).
+  try {
+    if (process.getuid && process.getuid() === 0) chownRecursive(dest);
+  } catch {}
+}
+
+function chownRecursive(dir) {
+  fs.chownSync(dir, 0, 0);
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const p = path.join(dir, entry.name);
+    if (entry.isDirectory()) chownRecursive(p);
+    else fs.chownSync(p, 0, 0);
+  }
 }
 
 switch (action) {