@astrosheep/pi-souls 0.1.0 → 0.1.2

package/README.md

@@ -16,6 +16,13 @@ pi install npm:@astrosheep/pi-souls
 
 Names tab-complete.
 
+```bash
+pi --soulless
+SOULLESS=1 pi
+```
+
+Skip settings souls for this process. `SOULLESS=1` or `true` enables it; `0`, `false`, or unset does not. A session `/soul <name>` still wins, including resumed selections; `/soul clear` returns to soulless.
+
 ## Souls
 
 One Markdown file per soul; the body becomes the identity. Frontmatter is stripped, and edits apply on the next request.
@@ -36,6 +43,6 @@ One Markdown file per soul; the body becomes the identity. Frontmatter is stripp
 }
 ```
 
-Precedence: `/soul <name>` > `modelSouls` (exact `provider/modelId`) > `defaultSoul` > Pi default.
+Precedence: `/soul <name>` > `--soulless` / `SOULLESS` / explicit system prompt > `modelSouls` (exact `provider/modelId`) > `defaultSoul` > Pi default.
 
-The session choice follows resume, fork, and tree navigation. A bad entry only breaks the case that uses it; that request falls back to Pi's prompt with an error. `--system-prompt` and `SYSTEM.md` outrank a settings soul but not `/soul`. If another extension forces the whole prompt, souls are skipped.
+The session choice follows resume, fork, and tree navigation. `--system-prompt` and `SYSTEM.md` outrank a settings soul but not `/soul`. A bad entry only breaks the case that uses it. When another extension forces the whole prompt, souls warns but still replaces the latest preamble if its exact text remains in the forced prompt, preserving surrounding instructions. When a soul can't apply (a bad entry, a missing file, or no matching preamble), Pi's prompt is used and a warning shows once, not on every request.

package/package.json

@@ -1,20 +1,39 @@
 {
   "name": "@astrosheep/pi-souls",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Session souls with model-specific defaults for Pi",
   "type": "module",
-  "keywords": ["pi-package"],
-  "repository": { "type": "git", "url": "https://github.com/astrosheep-zero/pi-souls.git" },
-  "publishConfig": { "access": "public" },
-  "files": ["src", "README.md"],
-  "pi": { "extensions": ["./src/index.ts"] },
-  "engines": { "node": ">=22.18" },
+  "keywords": [
+    "pi-package"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/astrosheep-zero/pi-souls.git"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "engines": {
+    "node": ">=22.18"
+  },
   "scripts": {
     "test": "node --experimental-strip-types --test test/*.test.ts",
     "typecheck": "tsc --noEmit",
     "check:load": "pi --no-extensions -e ./src/index.ts --list-models __load_check__"
   },
-  "peerDependencies": { "@earendil-works/pi-coding-agent": "*", "@earendil-works/pi-agent-core": "*" },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*",
+    "@earendil-works/pi-agent-core": "*"
+  },
   "devDependencies": {
     "@earendil-works/pi-coding-agent": "1.1.0",
     "@earendil-works/pi-agent-core": "1.1.0",

package/src/index.ts

@@ -1,24 +1,39 @@
 import { homedir } from "node:os";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { applySoul } from "./prompt.ts";
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+import type { BuildSystemPromptOptions, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { applySoul, replaceForcedPreamble } from "./prompt.ts";
 import { ENTRY_TYPE, effectiveSoul, listSouls, loadSoul, readConfig, resolveSoul, sessionSoul, unmatchableModelKeys, type Selection } from "./souls.ts";
 
 const home = homedir();
 const tilde = (path: string) => (path === home || path.startsWith(`${home}/`) ? `~${path.slice(home.length)}` : path);
 
-function describe(selection: Selection | undefined, model: ExtensionContext["model"], suppressed = false): string {
-  if (!selection) return suppressed ? "none (custom prompt)" : "none";
+function describe(selection: Selection | undefined, model: ExtensionContext["model"], suppressed = false, soulless = false): string {
+  if (!selection) return soulless ? "none (soulless)" : suppressed ? "none (custom prompt)" : "none";
   if (selection.source === "model") return `${selection.name} (${model?.provider}/${model?.id})`;
   return `${selection.name} (${selection.source})`;
 }
 
 export default function soulsExtension(pi: ExtensionAPI) {
+  pi.registerFlag("soulless", { description: "Skip default souls (session /soul still wins)", type: "boolean", default: false });
+  const soulless = () => pi.getFlag("soulless") === true || /^(1|true)$/i.test(process.env.SOULLESS ?? "");
   // Argument completion has no context; remember where the session runs for relative soulsDir.
   let cwd = process.cwd();
-  pi.on("session_start", (_event, ctx) => { cwd = ctx.cwd; });
-  // context_with_system cannot read prompt options; before_agent_start can, and runs first.
-  let customPrompt: string | undefined;
-  pi.on("before_agent_start", (event) => { customPrompt = event.systemPromptOptions.customPrompt; });
+  // A problem is reported when it appears or changes, not on every request of a tool loop.
+  let reported: string | undefined;
+  // Hold live options: handlers after ours can still set customPrompt or forceSystemPrompt.
+  let options: BuildSystemPromptOptions | undefined;
+  let running = false;
+  let forceReported = false;
+  // Retain the original text so tool-loop requests and soul edits do not patch our own output.
+  let forcedProjection: { original: string; projected: string } | undefined;
+  pi.on("session_start", (_event, ctx) => {
+    cwd = ctx.cwd; reported = undefined; forceReported = false;
+    options = undefined; running = false; forcedProjection = undefined;
+  });
+  pi.on("before_agent_start", (event) => {
+    options = event.systemPromptOptions; running = true; forcedProjection = undefined;
+  });
+  pi.on("agent_settled", () => { running = false; });
 
   pi.registerCommand("soul", {
     description: "Switch soul: /soul [name|clear]",
@@ -43,11 +58,11 @@ export default function soulsExtension(pi: ExtensionAPI) {
         const config = readConfig(pi.getSettings(), ctx.cwd);
         const prompt = ctx.getSystemPromptOptions().customPrompt;
         const override = () => sessionSoul(ctx.sessionManager.getBranch());
-        const resolved = () => resolveSoul(config, override(), ctx.model);
+        const resolved = () => resolveSoul(config, override(), ctx.model, soulless());
         const now = () => {
           const configured = resolved();
           const active = effectiveSoul(configured, prompt);
-          return describe(active, ctx.model, active === undefined && configured !== undefined);
+          return describe(active, ctx.model, active === undefined && configured !== undefined, soulless());
         };
 
         if (name === "clear") {
@@ -74,7 +89,7 @@ export default function soulsExtension(pi: ExtensionAPI) {
         const missing = selection && !available.includes(selection.name) ? " (missing)" : "";
         const ignored = unmatchableModelKeys(config);
         notify([
-          `Soul: ${describe(selection, ctx.model, selection === undefined && configured !== undefined)}${missing}`,
+          `Soul: ${describe(selection, ctx.model, selection === undefined && configured !== undefined, soulless())}${missing}`,
           `Souls: ${available.join(", ") || "none"}`,
           `Dir: ${tilde(config.dir)}`,
           ...(ignored.length ? [`Ignored keys: ${ignored.join(", ")}`] : []),
@@ -85,10 +100,44 @@ export default function soulsExtension(pi: ExtensionAPI) {
     },
   });
 
-  pi.on("context_with_system", (event, ctx) => {
+  const project = (messages: AgentMessage[], ctx: ExtensionContext): AgentMessage[] | undefined => {
     const config = readConfig(pi.getSettings(), ctx.cwd);
-    const selection = effectiveSoul(resolveSoul(config, sessionSoul(ctx.sessionManager.getBranch()), ctx.model), customPrompt);
-    if (!selection) return;
-    return { messages: applySoul(event.messages, loadSoul(config.dir, selection.name)) };
+    const selection = effectiveSoul(resolveSoul(config, sessionSoul(ctx.sessionManager.getBranch()), ctx.model, soulless()), options?.customPrompt);
+    if (!selection) return undefined;
+    const body = loadSoul(config.dir, selection.name);
+    const projected = applySoul(messages, body);
+    // Pi projects forced text after this hook; patch that too, not just its transcript sections.
+    if (running && options?.forceSystemPrompt !== undefined) {
+      if (!forceReported) {
+        const warning = "Soul: another extension forced the prompt; attempting preamble replacement";
+        if (ctx.hasUI) ctx.ui.notify(warning, "warning");
+        else console.warn(warning);
+        forceReported = true;
+      }
+      const forced = options.forceSystemPrompt;
+      const original = forced === forcedProjection?.projected ? forcedProjection.original : forced;
+      const patched = replaceForcedPreamble(messages, original, body);
+      forcedProjection = { original, projected: patched };
+      options.forceSystemPrompt = patched;
+    } else {
+      forceReported = false;
+    }
+    return projected;
+  };
+
+  pi.on("context_with_system", (event, ctx) => {
+    try {
+      const messages = project(event.messages, ctx);
+      reported = undefined;
+      return messages && { messages };
+    } catch (error) {
+      // The request goes out with Pi's own prompt; an unchanged problem skips quietly.
+      const problem = error instanceof Error ? error.message : String(error);
+      if (problem === reported) return;
+      reported = problem;
+      // Without a UI (print mode), only a thrown error reaches the user, on stderr.
+      if (!ctx.hasUI) throw error;
+      ctx.ui.notify(problem, "warning");
+    }
   });
 }

package/src/prompt.ts

@@ -2,16 +2,24 @@ import type { AgentMessage } from "@earendil-works/pi-agent-core";
 
 type SystemMessage = Extract<AgentMessage, { role: "system" }>;
 
-function hasPreamble(message: AgentMessage | undefined): message is SystemMessage {
-  return message?.role === "system" && typeof message.sections?.preamble === "string";
+function hasPreamble(message: AgentMessage): message is SystemMessage {
+  return message.role === "system" && typeof message.sections?.preamble === "string";
 }
 
-/** Request-only projection. Keep runtime sections, declaration deltas and conversation intact. */
+/** Forced prompts render the latest replayed preamble; leave appended instructions intact. */
+export function replaceForcedPreamble(messages: AgentMessage[], prompt: string, body: string): string {
+  const preamble = messages.findLast(hasPreamble)?.sections?.preamble;
+  if (!preamble || !prompt.includes(preamble)) throw new Error("Soul skipped: the forced prompt has no preamble");
+  // Use a callback so $ sequences in a soul are literal, not replacement patterns.
+  return prompt.replace(preamble, () => body);
+}
+
+/**
+ * Request-only projection. Keep runtime sections, declaration deltas and conversation intact.
+ * Pi replays every system message in order and the preamble can sit in a later one (sessions older
+ * than system messages), so every preamble patch carries the soul: an old identity must not win.
+ */
 export function applySoul(messages: AgentMessage[], body: string): AgentMessage[] {
-  const head = messages[0];
-  if (!hasPreamble(head) || head.content) {
-    throw new Error("Soul skipped: system prompt fully replaced");
-  }
-  // Rewrite historical preamble deltas too: an old identity must not override today's soul.
+  if (!messages.some(hasPreamble)) throw new Error("Soul skipped: the prompt has no preamble");
   return messages.map((message) => hasPreamble(message) ? { ...message, sections: { ...message.sections, preamble: body } } : message);
 }

package/src/souls.ts

@@ -55,8 +55,9 @@ function named(name: unknown, source: Selection["source"], setting: string): Sel
   return { name, source };
 }
 
-export function resolveSoul(config: SoulConfig, override: string | undefined, model?: { provider: string; id: string }): Selection | undefined {
+export function resolveSoul(config: SoulConfig, override: string | undefined, model?: { provider: string; id: string }, soulless = false): Selection | undefined {
   if (override) return { name: override, source: "session" };
+  if (soulless) return undefined;
   const key = model && `${model.provider}/${model.id}`;
   if (key && Object.hasOwn(config.modelSouls, key)) return named(config.modelSouls[key], "model", `modelSouls["${key}"]`);
   if (config.defaultSoul !== undefined) return named(config.defaultSoul, "default", "defaultSoul");
@@ -85,8 +86,9 @@ export function loadSoul(dir: string, name: string): string {
   try {
     text = readFileSync(path, "utf8");
   } catch (error) {
-    if ((error as NodeJS.ErrnoException).code === "ENOENT") throw new Error(`Soul "${name}" not found: ${path}`);
-    throw error;
+    const code = (error as NodeJS.ErrnoException).code;
+    if (code === "ENOENT") throw new Error(`Soul "${name}" not found: ${path}`);
+    throw new Error(`Soul "${name}" unreadable: ${path} (${code ?? String(error)})`);
   }
   const body = stripFrontmatter(text).trim();
   if (!body) throw new Error(`Soul "${name}" is empty`);