@astrosheep/pi-souls 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,41 @@
-# Temporary Holding Version
+# pi-souls
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Swap [Pi](https://github.com/earendil-works/pi)'s identity per session, per model, or by default. Only the identity changes; tools, rules, skills, and project context stay as they are.
+
+```bash
+pi install npm:@astrosheep/pi-souls
+```
+
+## Usage
+
+```text
+/soul          # current soul and list
+/soul faye     # use faye for this session
+/soul clear    # back to defaults
+```
+
+Names tab-complete.
+
+## Souls
+
+One Markdown file per soul; the body becomes the identity. Frontmatter is stripped, and edits apply on the next request.
+
+```text
+~/.agents/souls/
+├── faye.md
+└── reviewer.md
+```
+
+## Settings
+
+```json
+{
+  "defaultSoul": "faye",
+  "modelSouls": { "anthropic/claude-sonnet-5": "reviewer" },
+  "soulsDir": "~/.agents/souls"
+}
+```
+
+Precedence: `/soul <name>` > `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.

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@astrosheep/pi-souls",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "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"
+  },
+  "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": "*"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-coding-agent": "1.1.0",
+    "@earendil-works/pi-agent-core": "1.1.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^6.0.3"
+  }
+}

package/src/index.ts

@@ -0,0 +1,119 @@
+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 { 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";
+  if (selection.source === "model") return `${selection.name} (${model?.provider}/${model?.id})`;
+  return `${selection.name} (${selection.source})`;
+}
+
+export default function soulsExtension(pi: ExtensionAPI) {
+  // 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.
+  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]",
+    getArgumentCompletions: (prefix) => {
+      try {
+        const souls = listSouls(readConfig(pi.getSettings(), cwd).dir).map((name) => ({ value: name, label: name }));
+        const items = [...souls, { value: "clear", label: "clear", description: "Follow defaults" }];
+        const matches = items.filter((item) => item.value.startsWith(prefix.trim()));
+        return matches.length ? matches : null;
+      } catch {
+        return null;
+      }
+    },
+    handler: async (args, ctx) => {
+      const notify = (text: string) => ctx.ui.notify(text, "info");
+      if (!ctx.isIdle()) {
+        ctx.ui.notify("Busy. Switch souls after this run.", "warning");
+        return;
+      }
+      try {
+        const name = args.trim();
+        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 now = () => {
+          const configured = resolved();
+          const active = effectiveSoul(configured, prompt);
+          return describe(active, ctx.model, active === undefined && configured !== undefined);
+        };
+
+        if (name === "clear") {
+          let selected = true; // A corrupted selection counts as something to clear.
+          try { selected = override() !== undefined; } catch {}
+          if (!selected) return notify(`No session soul. Soul: ${now()}`);
+          pi.appendEntry(ENTRY_TYPE, { version: 1, name: null });
+          return notify(`Cleared. Soul: ${now()}`);
+        }
+
+        const available = listSouls(config.dir);
+        if (name) {
+          if (override() === name) return notify(`Already ${name}.`);
+          if (!available.includes(name)) {
+            throw new Error(`No soul "${name}". Souls: ${available.join(", ") || "none"}`);
+          }
+          loadSoul(config.dir, name); // Validate content before changing durable session state.
+          pi.appendEntry(ENTRY_TYPE, { version: 1, name });
+          return notify(`Soul: ${name}`);
+        }
+
+        const configured = resolved();
+        const selection = effectiveSoul(configured, prompt);
+        const missing = selection && !available.includes(selection.name) ? " (missing)" : "";
+        const ignored = unmatchableModelKeys(config);
+        notify([
+          `Soul: ${describe(selection, ctx.model, selection === undefined && configured !== undefined)}${missing}`,
+          `Souls: ${available.join(", ") || "none"}`,
+          `Dir: ${tilde(config.dir)}`,
+          ...(ignored.length ? [`Ignored keys: ${ignored.join(", ")}`] : []),
+        ].join("\n"));
+      } catch (error) {
+        ctx.ui.notify(error instanceof Error ? error.message : String(error), "error");
+      }
+    },
+  });
+
+  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);
+    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

@@ -0,0 +1,17 @@
+import type { AgentMessage } from "@earendil-works/pi-agent-core";
+
+type SystemMessage = Extract<AgentMessage, { role: "system" }>;
+
+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.
+ * 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[] {
+  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

@@ -0,0 +1,95 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { stripFrontmatter, type SessionEntry } from "@earendil-works/pi-coding-agent";
+
+export const ENTRY_TYPE = "pi-souls:selection";
+export interface SoulConfig {
+  defaultSoul?: unknown;
+  modelSouls: Record<string, unknown>;
+  dir: string;
+}
+export interface Selection {
+  name: string;
+  source: "session" | "model" | "default";
+}
+
+export function isSoulName(value: unknown): value is string {
+  return typeof value === "string" && /^[\p{L}\p{N}_-][\p{L}\p{N}_.-]*$/u.test(value) && value !== "clear";
+}
+
+function object(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+/** Only the shape is checked here; soul names are checked when used, so one bad entry never disables the rest. */
+export function readConfig(settings: unknown, cwd: string): SoulConfig {
+  if (!object(settings)) throw new Error("Invalid Pi settings");
+  const { defaultSoul, modelSouls = {}, soulsDir = "~/.agents/souls" } = settings;
+  if (!object(modelSouls)) throw new Error("modelSouls must be an object");
+  if (typeof soulsDir !== "string" || !soulsDir.trim()) throw new Error("soulsDir must be a path");
+  const dir = soulsDir === "~" || soulsDir.startsWith("~/") ? join(homedir(), soulsDir.slice(2)) : resolve(cwd, soulsDir);
+  return { defaultSoul, modelSouls, dir };
+}
+
+/** Keys that can never match a model; surfaced by /soul instead of failing every request. */
+export function unmatchableModelKeys(config: SoulConfig): string[] {
+  return Object.keys(config.modelSouls).filter((key) => !/^[^/]+\/.+$/.test(key));
+}
+
+/** Read the active branch, never the whole session file or a second in-memory authority. */
+export function sessionSoul(branch: readonly SessionEntry[]): string | undefined {
+  for (let i = branch.length - 1; i >= 0; i--) {
+    const entry = branch[i];
+    if (entry.type !== "custom" || entry.customType !== ENTRY_TYPE) continue;
+    if (!object(entry.data) || entry.data.version !== 1 || !(entry.data.name === null || isSoulName(entry.data.name))) {
+      throw new Error("Corrupted soul entry. Run /soul clear");
+    }
+    return entry.data.name ?? undefined;
+  }
+  return undefined;
+}
+
+function named(name: unknown, source: Selection["source"], setting: string): Selection {
+  if (!isSoulName(name)) throw new Error(`${setting}: invalid soul ${JSON.stringify(name)}`);
+  return { name, source };
+}
+
+export function resolveSoul(config: SoulConfig, override: string | undefined, model?: { provider: string; id: string }): Selection | undefined {
+  if (override) return { name: override, source: "session" };
+  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");
+  return undefined;
+}
+
+/** A settings soul is only a default: the user's explicit system prompt outranks it, a session choice does not. */
+export function effectiveSoul(selection: Selection | undefined, customPrompt: string | undefined): Selection | undefined {
+  return selection?.source === "session" || !customPrompt ? selection : undefined;
+}
+
+export function listSouls(dir: string): string[] {
+  try {
+    return readdirSync(dir).filter((file) => file.endsWith(".md")).map((file) => file.slice(0, -3)).filter(isSoulName).sort();
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return [];
+    throw error;
+  }
+}
+
+/** Small local files are read fresh; no cache invalidation protocol or watchers needed. */
+export function loadSoul(dir: string, name: string): string {
+  if (!isSoulName(name)) throw new Error(`Invalid soul name: ${name}`);
+  const path = join(dir, `${name}.md`);
+  let text: string;
+  try {
+    text = readFileSync(path, "utf8");
+  } catch (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`);
+  return body;
+}