@astrosheep/pi-souls 0.1.1 → 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. `--system-prompt` and `SYSTEM.md` outrank a settings soul but not `/soul`. A bad entry only breaks the case that uses it. When a soul can't apply (a bad entry, a missing file, or another extension forcing the whole prompt), Pi's prompt is used and a warning shows once, not on every request.
+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,6 +1,6 @@
 {
   "name": "@astrosheep/pi-souls",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Session souls with model-specific defaults for Pi",
   "type": "module",
   "keywords": [

package/src/index.ts

@@ -1,30 +1,38 @@
 import { homedir } from "node:os";
 import type { AgentMessage } from "@earendil-works/pi-agent-core";
 import type { BuildSystemPromptOptions, ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
-import { applySoul } from "./prompt.ts";
+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();
   // A problem is reported when it appears or changes, not on every request of a tool loop.
   let reported: string | undefined;
-  pi.on("session_start", (_event, ctx) => { cwd = ctx.cwd; reported = undefined; });
-  // context_with_system cannot read prompt options. Hold the last run's live options, not a copy:
-  // handlers after ours may still set customPrompt or forceSystemPrompt. customPrompt is session
-  // configuration and stays valid; a forced prompt only applies while its run is going.
+  // Hold live options: handlers after ours can still set customPrompt or forceSystemPrompt.
   let options: BuildSystemPromptOptions | undefined;
   let running = false;
-  pi.on("before_agent_start", (event) => { options = event.systemPromptOptions; running = true; });
+  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", {
@@ -50,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") {
@@ -81,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(", ")}`] : []),
@@ -94,11 +102,27 @@ export default function soulsExtension(pi: ExtensionAPI) {
 
   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), options?.customPrompt);
+    const selection = effectiveSoul(resolveSoul(config, sessionSoul(ctx.sessionManager.getBranch()), ctx.model, soulless()), options?.customPrompt);
     if (!selection) return undefined;
-    // Pi projects a forced prompt after this hook, over whatever it returns.
-    if (running && options?.forceSystemPrompt !== undefined) throw new Error("Soul skipped: another extension replaced the whole prompt");
-    return applySoul(messages, loadSoul(config.dir, selection.name));
+    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) => {

package/src/prompt.ts

@@ -6,6 +6,14 @@ function hasPreamble(message: AgentMessage): message is SystemMessage {
   return message.role === "system" && typeof message.sections?.preamble === "string";
 }
 
+/** 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

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");