@astrosheep/pi-souls 0.1.0 → 0.1.1

package/README.md

@@ -38,4 +38,4 @@ One Markdown file per soul; the body becomes the identity. Frontmatter is stripp
 
 Precedence: `/soul <name>` > `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 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.

package/package.json

@@ -1,20 +1,39 @@
 {
   "name": "@astrosheep/pi-souls",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "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,5 +1,6 @@
 import { homedir } from "node:os";
-import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+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 { ENTRY_TYPE, effectiveSoul, listSouls, loadSoul, readConfig, resolveSoul, sessionSoul, unmatchableModelKeys, type Selection } from "./souls.ts";
 
@@ -15,10 +16,16 @@ function describe(selection: Selection | undefined, model: ExtensionContext["mod
 export default function soulsExtension(pi: ExtensionAPI) {
   // 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;
+  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.
+  let options: BuildSystemPromptOptions | undefined;
+  let running = false;
+  pi.on("before_agent_start", (event) => { options = event.systemPromptOptions; running = true; });
+  pi.on("agent_settled", () => { running = false; });
 
   pi.registerCommand("soul", {
     description: "Switch soul: /soul [name|clear]",
@@ -85,10 +92,28 @@ 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), 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));
+  };
+
+  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,16 @@ 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. */
+/**
+ * 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

@@ -85,8 +85,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`);