pi-incarnate 0.1.0 → 0.2.0

package/scripts/persona-eval.mjs

@@ -0,0 +1,211 @@
+import assert from "node:assert/strict";
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { loadCharacter } from "../src/character-loader.ts";
+import { appendPersonaPrompt } from "../src/persona.ts";
+
+const projectRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const scenarioPath = resolve(projectRoot, "evals/persona-scenarios.json");
+const scenarios = JSON.parse(await readFile(scenarioPath, "utf8"));
+const character = await loadCharacter(resolve(projectRoot, "characters"), scenarios.character);
+
+function validatePlan() {
+  assert.equal(scenarios.version, 1);
+  assert.ok(Array.isArray(scenarios.scenarios) && scenarios.scenarios.length >= 6);
+  assert.deepEqual(scenarios.rubric.scoreRange, [0, 2]);
+  assert.ok(scenarios.rubric.passingScore > 0);
+  assert.ok(scenarios.rubric.criticalFailures.length > 0);
+
+  const ids = new Set();
+  const comparisonGroups = new Map();
+  for (const scenario of scenarios.scenarios) {
+    assert.match(scenario.id, /^[a-z0-9]+(?:-[a-z0-9]+)*$/);
+    assert.equal(ids.has(scenario.id), false, `duplicate scenario id: ${scenario.id}`);
+    ids.add(scenario.id);
+    assert.ok(scenario.prompt.trim());
+    assert.ok(Array.isArray(scenario.expect) && scenario.expect.length >= 2);
+    if (scenario.comparisonGroup) {
+      const group = comparisonGroups.get(scenario.comparisonGroup) ?? [];
+      group.push(scenario);
+      comparisonGroups.set(scenario.comparisonGroup, group);
+    }
+    if (scenario.mood === "off") {
+      const base = "BASE SYSTEM PROMPT";
+      assert.doesNotMatch(base, /pi-incarnate|Active character|Current mood preset/);
+      continue;
+    }
+    assert.ok(character.mood.presets.has(scenario.mood), `unknown mood: ${scenario.mood}`);
+    const prompt = appendPersonaPrompt("BASE SYSTEM PROMPT", character, scenario.mood);
+    assert.ok(prompt.startsWith("BASE SYSTEM PROMPT\n\n"));
+    assert.match(prompt, /Never invent tool results/);
+    assert.match(prompt, /Active character: 弥拉 \(mira\)/);
+    assert.match(prompt, new RegExp(`Current mood preset: ${scenario.mood}`));
+    assert.match(prompt, /Only this named preset is active; do not blend in other preset definitions/);
+    assert.match(prompt, /The response must visibly demonstrate this preset/);
+    assert.match(prompt, /Make it perceptible in wording, pacing, and response strategy without exaggerating it/);
+  }
+
+  for (const [groupId, group] of comparisonGroups) {
+    assert.ok(group.length >= 2, `comparison group must contain at least two scenarios: ${groupId}`);
+    assert.equal(new Set(group.map((scenario) => scenario.prompt)).size, 1, `comparison prompts differ: ${groupId}`);
+    assert.equal(new Set(group.map((scenario) => scenario.mood)).size, group.length, `comparison moods repeat: ${groupId}`);
+  }
+}
+
+function argument(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 ? process.argv[index + 1] : fallback;
+}
+
+function rpcProcess(model, thinking) {
+  const child = spawn(
+    "pi",
+    [
+      "--mode", "rpc",
+      "--no-session",
+      "--no-extensions",
+      "--no-skills",
+      "--no-prompt-templates",
+      "--no-themes",
+      "--no-context-files",
+      "--no-tools",
+      "-e", resolve(projectRoot, "extensions/index.ts"),
+      "--model", model,
+      "--thinking", thinking,
+    ],
+    { cwd: projectRoot, stdio: ["pipe", "pipe", "pipe"] },
+  );
+  child.stdout.setEncoding("utf8");
+  child.stderr.setEncoding("utf8");
+  let stdoutBuffer = "";
+  let stderr = "";
+  const events = [];
+  const waiters = new Set();
+
+  const dispatch = (event) => {
+    events.push(event);
+    for (const waiter of [...waiters]) {
+      if (!waiter.predicate(event)) continue;
+      waiters.delete(waiter);
+      clearTimeout(waiter.timer);
+      waiter.resolve(event);
+    }
+  };
+  child.stdout.on("data", (chunk) => {
+    stdoutBuffer += chunk;
+    while (true) {
+      const newline = stdoutBuffer.indexOf("\n");
+      if (newline < 0) break;
+      const line = stdoutBuffer.slice(0, newline).replace(/\r$/, "");
+      stdoutBuffer = stdoutBuffer.slice(newline + 1);
+      if (line) dispatch(JSON.parse(line));
+    }
+  });
+  child.stderr.on("data", (chunk) => void (stderr += chunk));
+
+  const waitFor = (predicate, label, timeout = 180_000) => new Promise((resolvePromise, reject) => {
+    const existing = events.find(predicate);
+    if (existing) {
+      resolvePromise(existing);
+      return;
+    }
+    const waiter = {
+      predicate,
+      resolve: resolvePromise,
+      timer: setTimeout(() => {
+        waiters.delete(waiter);
+        child.kill("SIGTERM");
+        reject(new Error(`Timed out waiting for ${label}${stderr ? `: ${stderr.trim()}` : ""}`));
+      }, timeout),
+    };
+    waiters.add(waiter);
+  });
+
+  const send = async (command) => {
+    const response = waitFor((event) => event.type === "response" && event.id === command.id, command.id);
+    child.stdin.write(`${JSON.stringify(command)}\n`);
+    const result = await response;
+    assert.equal(result.success, true, result.error ?? `RPC command failed: ${command.id}`);
+  };
+
+  return { child, events, send, waitFor, stderr: () => stderr };
+}
+
+function assistantText(events, startIndex) {
+  const messages = events
+    .slice(startIndex)
+    .filter((event) => event.type === "message_end" && event.message?.role === "assistant")
+    .map((event) => event.message);
+  const message = messages.at(-1);
+  assert.ok(message, "model produced no assistant message");
+  return (message.content ?? [])
+    .filter((part) => part.type === "text")
+    .map((part) => part.text)
+    .join("")
+    .trim();
+}
+
+async function runScenario(scenario, model, thinking) {
+  const rpc = rpcProcess(model, thinking);
+  try {
+    await rpc.send({ id: "activate", type: "prompt", message: "/incarnate use mira" });
+    if (scenario.mood === "off") {
+      await rpc.send({ id: "off", type: "prompt", message: "/incarnate off" });
+    } else if (scenario.mood !== "warm") {
+      await rpc.send({ id: "mood", type: "prompt", message: `/incarnate mood ${scenario.mood}` });
+    }
+    const startIndex = rpc.events.length;
+    const settled = rpc.waitFor((event) => event.type === "agent_settled", `${scenario.id} agent_settled`);
+    await rpc.send({ id: "scenario", type: "prompt", message: scenario.prompt });
+    await settled;
+    const response = assistantText(rpc.events, startIndex);
+    rpc.child.stdin.end();
+    return { ...scenario, response };
+  } finally {
+    if (!rpc.child.killed) rpc.child.kill("SIGTERM");
+  }
+}
+
+validatePlan();
+
+const requestedIds = argument("--scenario", "")
+  .split(",")
+  .map((id) => id.trim())
+  .filter(Boolean);
+const selectedScenarios = requestedIds.length === 0
+  ? scenarios.scenarios
+  : requestedIds.map((id) => {
+      const scenario = scenarios.scenarios.find((candidate) => candidate.id === id);
+      assert.ok(scenario, `unknown scenario id: ${id}`);
+      return scenario;
+    });
+
+if (!process.argv.includes("--run")) {
+  process.stdout.write(`Persona evaluation plan passed: ${scenarios.scenarios.length} scenarios for ${character.name} (${character.id})\n`);
+  process.stdout.write("Use --run --model <provider/model> [--scenario <id,id>] [--repeat <n>] to collect real model responses.\n");
+} else {
+  const model = argument("--model", "openai-codex/gpt-5.6-luna");
+  const thinking = argument("--thinking", "low");
+  const repeatText = argument("--repeat", "1");
+  assert.match(repeatText, /^[1-9]\d*$/, "--repeat must be a positive integer");
+  const repeat = Number(repeatText);
+  const results = [];
+  for (const scenario of selectedScenarios) {
+    for (let sample = 1; sample <= repeat; sample += 1) {
+      process.stderr.write(`Running ${scenario.id} (${sample}/${repeat})...\n`);
+      results.push({ ...await runScenario(scenario, model, thinking), sample });
+    }
+  }
+  process.stdout.write(`${JSON.stringify({
+    generatedAt: new Date().toISOString(),
+    model,
+    thinking,
+    repeat,
+    character: character.id,
+    rubric: scenarios.rubric,
+    results,
+  }, null, 2)}\n`);
+}

package/src/avatar-manager.ts

@@ -0,0 +1,156 @@
+import { lstat, readFile, rename, rm, writeFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { extname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { visibleWidth } from "@earendil-works/pi-tui";
+
+import {
+  AVATAR_MAX_BYTES,
+  AVATAR_MAX_COLUMNS,
+  AVATAR_MAX_LINES,
+  sanitizeAnsiAvatar,
+  sanitizeAvatar,
+} from "./avatar.ts";
+import { CharacterEditError, resolvePersonalDirectory } from "./character-editor.ts";
+
+export type AvatarFileName = "avatar.ansi" | "avatar.txt";
+
+export interface PreparedAvatarImport {
+  filename: AvatarFileName;
+  content: string;
+  width: number;
+  height: number;
+}
+
+function stripWrappingQuotes(value: string): string {
+  if (value.length < 2) return value;
+  const first = value[0];
+  return (first === "'" || first === '"') && value.at(-1) === first ? value.slice(1, -1) : value;
+}
+
+export function resolveUserPath(input: string, cwd: string, userHome = homedir()): string {
+  let value = stripWrappingQuotes(input.trim()).replace(/\\([\\ ])/g, "$1");
+  if (value.startsWith("file://")) return fileURLToPath(value);
+  if (value === "~") value = userHome;
+  else if (value.startsWith("~/")) value = join(userHome, value.slice(2));
+  return resolve(cwd, value);
+}
+
+export function resolveAvatarSourcePath(input: string, cwd: string, userHome = homedir()): string {
+  return resolveUserPath(input, cwd, userHome);
+}
+
+export function prepareAvatarContent(filename: AvatarFileName, raw: string): PreparedAvatarImport {
+  if (Buffer.byteLength(raw, "utf8") > AVATAR_MAX_BYTES) {
+    throw new CharacterEditError(`Avatar exceeds the ${AVATAR_MAX_BYTES}-byte limit`);
+  }
+  const avatar = filename === "avatar.ansi" ? sanitizeAnsiAvatar(raw) : sanitizeAvatar(raw);
+  if (avatar.lines.length === 0) throw new CharacterEditError("Avatar contains no visible content");
+  if (avatar.truncated) {
+    throw new CharacterEditError(`Avatar must fit within ${AVATAR_MAX_COLUMNS} columns and ${AVATAR_MAX_LINES} lines`);
+  }
+  return {
+    filename,
+    content: `${avatar.lines.join("\n")}\n`,
+    width: avatar.lines.reduce((maximum, line) => Math.max(maximum, visibleWidth(line)), 0),
+    height: avatar.lines.length,
+  };
+}
+
+export async function prepareAvatarImport(sourcePath: string): Promise<PreparedAvatarImport> {
+  const extension = extname(sourcePath).toLowerCase();
+  let filename: AvatarFileName;
+  if (extension === ".ansi") filename = "avatar.ansi";
+  else if (extension === ".txt") filename = "avatar.txt";
+  else throw new CharacterEditError("Avatar file must end in .ansi or .txt");
+
+  let bytes: Buffer;
+  try {
+    const info = await lstat(sourcePath);
+    if (!info.isFile() || info.isSymbolicLink()) {
+      throw new CharacterEditError(`Avatar source must be a regular file: ${sourcePath}`);
+    }
+    if (info.size > AVATAR_MAX_BYTES) {
+      throw new CharacterEditError(`Avatar exceeds the ${AVATAR_MAX_BYTES}-byte limit: ${sourcePath}`);
+    }
+    bytes = await readFile(sourcePath);
+    if (bytes.byteLength > AVATAR_MAX_BYTES) {
+      throw new CharacterEditError(`Avatar exceeds the ${AVATAR_MAX_BYTES}-byte limit: ${sourcePath}`);
+    }
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    throw new CharacterEditError(`Cannot read avatar source: ${sourcePath}`);
+  }
+
+  let raw: string;
+  try {
+    raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+  } catch {
+    throw new CharacterEditError(`Avatar source is not valid UTF-8: ${sourcePath}`);
+  }
+  return prepareAvatarContent(filename, raw);
+}
+
+async function assertReplaceable(path: string): Promise<void> {
+  try {
+    const info = await lstat(path);
+    if (info.isDirectory()) throw new CharacterEditError(`Avatar target is a directory: ${path}`);
+  } catch (error) {
+    if (error instanceof CharacterEditError) throw error;
+    if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+  }
+}
+
+export async function installPersonalAvatar(
+  personalRoot: string,
+  id: string,
+  prepared: PreparedAvatarImport,
+): Promise<string> {
+  const directory = await resolvePersonalDirectory(personalRoot, id);
+  const targetPath = join(directory, prepared.filename);
+  const alternatePath = join(directory, prepared.filename === "avatar.ansi" ? "avatar.txt" : "avatar.ansi");
+  await assertReplaceable(targetPath);
+  await assertReplaceable(alternatePath);
+
+  const nonce = crypto.randomUUID();
+  const temporaryPath = join(directory, `.avatar-import-${nonce}.tmp`);
+  const alternateBackup = join(directory, `.avatar-replaced-${nonce}.tmp`);
+  let movedAlternate = false;
+  try {
+    await writeFile(temporaryPath, prepared.content, { encoding: "utf8", flag: "wx" });
+    try {
+      await rename(alternatePath, alternateBackup);
+      movedAlternate = true;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") throw error;
+    }
+    await rename(temporaryPath, targetPath);
+    if (movedAlternate) await rm(alternateBackup, { force: true });
+  } catch (error) {
+    if (movedAlternate) await rename(alternateBackup, alternatePath).catch(() => undefined);
+    throw new CharacterEditError(`Cannot install avatar for ${id}: ${error instanceof Error ? error.message : "unknown error"}`);
+  } finally {
+    await rm(temporaryPath, { force: true });
+  }
+  return targetPath;
+}
+
+export async function removePersonalAvatars(personalRoot: string, id: string): Promise<number> {
+  const directory = await resolvePersonalDirectory(personalRoot, id);
+  let removed = 0;
+  for (const filename of ["avatar.ansi", "avatar.txt"] as const) {
+    const path = join(directory, filename);
+    try {
+      const info = await lstat(path);
+      if (info.isDirectory()) throw new CharacterEditError(`Avatar target is a directory: ${path}`);
+      await rm(path);
+      removed += 1;
+    } catch (error) {
+      if (error instanceof CharacterEditError) throw error;
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        throw new CharacterEditError(`Cannot remove avatar: ${path}`);
+      }
+    }
+  }
+  return removed;
+}

package/src/avatar.ts

@@ -5,7 +5,11 @@ import { stripTerminalSequences, truncateToWidth, visibleWidth } from "@earendil
 import type { Character } from "./character-loader.ts";
 
 export const AVATAR_MAX_COLUMNS = 48;
-export const AVATAR_MAX_LINES = 12;
+export const AVATAR_MAX_LINES = 16;
+export const AVATAR_MAX_BYTES = 64 * 1024;
+const ANSI_RESET = "\u001b[0m";
+const CSI_SEQUENCE_PATTERN = /\u001b\[[0-?]*[ -/]*[@-~]/g;
+const CONTROL_CHARACTER_PATTERN = /[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F-\u009F]/g;
 
 export interface Avatar {
   lines: string[];
@@ -19,6 +23,66 @@ export class AvatarLoadError extends Error {
   }
 }
 
+function isSafeSgr(sequence: string): boolean {
+  const match = sequence.match(/^\u001b\[([0-9;]*)m$/);
+  if (!match) return false;
+  const parameters = match[1] === "" ? [0] : match[1].split(";").map(Number);
+  if (parameters.some((value) => !Number.isInteger(value))) return false;
+  if (parameters.length === 1) {
+    const value = parameters[0]!;
+    return (
+      value === 0 ||
+      value === 39 ||
+      value === 49 ||
+      (value >= 30 && value <= 37) ||
+      (value >= 40 && value <= 47) ||
+      (value >= 90 && value <= 97) ||
+      (value >= 100 && value <= 107)
+    );
+  }
+  if (parameters.length === 3 && (parameters[0] === 38 || parameters[0] === 48) && parameters[1] === 5) {
+    return parameters[2]! >= 0 && parameters[2]! <= 255;
+  }
+  if (parameters.length === 5 && (parameters[0] === 38 || parameters[0] === 48) && parameters[1] === 2) {
+    return parameters.slice(2).every((value) => value >= 0 && value <= 255);
+  }
+  return false;
+}
+
+function preserveSafeSgr(raw: string): string {
+  const sequences: string[] = [];
+  const tokenized = raw
+    .replace(/[\uE000\uE001]/g, "")
+    .replace(CSI_SEQUENCE_PATTERN, (sequence) => {
+      if (!isSafeSgr(sequence)) return "";
+      const index = sequences.push(sequence) - 1;
+      return `\uE000${index}\uE001`;
+    });
+  return stripTerminalSequences(tokenized)
+    .replace(CONTROL_CHARACTER_PATTERN, "")
+    .replace(/\uE000(\d+)\uE001/g, (_token, index: string) => sequences[Number(index)] ?? "");
+}
+
+function isVisuallyBlank(line: string): boolean {
+  return stripTerminalSequences(line).trim() === "";
+}
+
+function limitAvatarLines(lines: string[], maxColumns: number, maxLines: number): Avatar {
+  let truncated = false;
+  const limited = lines.map((line) => {
+    if (visibleWidth(line) <= maxColumns) return line;
+    truncated = true;
+    return truncateToWidth(line, maxColumns, "…");
+  });
+  while (limited.length > 0 && isVisuallyBlank(limited[0]!)) limited.shift();
+  while (limited.length > 0 && isVisuallyBlank(limited.at(-1)!)) limited.pop();
+  if (limited.length > maxLines) {
+    limited.splice(maxLines);
+    truncated = true;
+  }
+  return { lines: limited, truncated };
+}
+
 function isWithin(parent: string, child: string): boolean {
   const pathFromParent = relative(parent, child);
   return pathFromParent !== ".." && !pathFromParent.startsWith(`..${sep}`);
@@ -26,26 +90,30 @@ function isWithin(parent: string, child: string): boolean {
 
 export function sanitizeAvatar(raw: string, maxColumns = AVATAR_MAX_COLUMNS, maxLines = AVATAR_MAX_LINES): Avatar {
   const normalized = raw.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
-  let truncated = false;
-  let lines = normalized.split("\n").map((line) => {
+  const lines = normalized.split("\n").map((line) => {
     const safe = stripTerminalSequences(line.replace(/\t/g, "    "))
-      .replace(/[\u0000-\u0008\u000B\u000C\u000E-\u001F\u007F]/g, "")
+      .replace(CONTROL_CHARACTER_PATTERN, "")
       .trimEnd();
-    if (visibleWidth(safe) <= maxColumns) return safe;
-    truncated = true;
-    return truncateToWidth(safe, maxColumns, "…");
+    return safe;
   });
-  while (lines[0] === "") lines.shift();
-  while (lines.at(-1) === "") lines.pop();
-  if (lines.length > maxLines) {
-    lines = lines.slice(0, maxLines);
-    truncated = true;
-  }
-  return { lines, truncated };
+  return limitAvatarLines(lines, maxColumns, maxLines);
 }
 
-export async function loadAvatar(character: Character): Promise<Avatar | undefined> {
-  const avatarPath = join(character.directory, "avatar.txt");
+export function sanitizeAnsiAvatar(
+  raw: string,
+  maxColumns = AVATAR_MAX_COLUMNS,
+  maxLines = AVATAR_MAX_LINES,
+): Avatar {
+  const normalized = raw.replace(/^\uFEFF/, "").replace(/\r\n?/g, "\n");
+  const lines = normalized.split("\n").map((line) => {
+    const safe = preserveSafeSgr(line.replace(/\t/g, "    "));
+    return safe.includes("\u001b[") ? `${safe}${ANSI_RESET}` : safe;
+  });
+  return limitAvatarLines(lines, maxColumns, maxLines);
+}
+
+async function loadAvatarFile(character: Character, filename: string, allowAnsi: boolean): Promise<Avatar | undefined> {
+  const avatarPath = join(character.directory, filename);
   let canonicalAvatarPath: string;
   try {
     canonicalAvatarPath = await realpath(avatarPath);
@@ -63,18 +131,21 @@ export async function loadAvatar(character: Character): Promise<Avatar | undefin
   } catch {
     throw new AvatarLoadError(`Cannot read avatar: ${avatarPath}`);
   }
+  if (bytes.byteLength > AVATAR_MAX_BYTES) {
+    throw new AvatarLoadError(`${filename} exceeds the ${AVATAR_MAX_BYTES}-byte limit: ${avatarPath}`);
+  }
 
   let raw: string;
   try {
     raw = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
   } catch {
-    throw new AvatarLoadError(`avatar.txt is not valid UTF-8: ${avatarPath}`);
+    throw new AvatarLoadError(`${filename} is not valid UTF-8: ${avatarPath}`);
   }
-  return sanitizeAvatar(raw);
+  return allowAnsi ? sanitizeAnsiAvatar(raw) : sanitizeAvatar(raw);
 }
 
-export function renderAvatarWidget(character: Character, mood: string | undefined, avatar: Avatar | undefined): string[] {
-  const moodLabel = mood ? ` · mood: ${mood}` : "";
-  const header = truncateToWidth(`pi-incarnate · ${character.name}${moodLabel}`, AVATAR_MAX_COLUMNS, "…");
-  return [header, ...(avatar?.lines ?? [])];
+export async function loadAvatar(character: Character): Promise<Avatar | undefined> {
+  const ansi = await loadAvatarFile(character, "avatar.ansi", true);
+  if (ansi) return ansi;
+  return await loadAvatarFile(character, "avatar.txt", false);
 }