@mccune1224/pi-pstack 0.1.0 → 0.2.0

package/extensions/compaction.test.ts

@@ -0,0 +1,132 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  POTETO_COMPACT_INSTRUCTIONS,
+  SUMMARY_SYSTEM_FRAME,
+  buildSummaryPrompt,
+  loadConversationHelpers,
+  runPotetoCompaction,
+} from "./compaction.ts";
+
+const PREPARATION = {
+  firstKeptEntryId: "entry-9",
+  messagesToSummarize: [{ role: "user", content: "fix the webhook" }],
+  turnPrefixMessages: [],
+  tokensBefore: 148_000,
+  previousSummary: undefined,
+};
+
+test("buildSummaryPrompt demands the poteto sections and keeps the conversation inline", () => {
+  const prompt = buildSummaryPrompt("<raw transcript>");
+  for (const section of [
+    "## Playbook and position",
+    "## Decision ledger",
+    "## Verified and unverified",
+    "## Files and artifacts",
+    "## Next actions",
+    "## Open questions",
+  ]) {
+    assert.ok(prompt.includes(section), section);
+  }
+  assert.ok(prompt.includes("<conversation><raw transcript></conversation>"));
+});
+
+test("buildSummaryPrompt folds in custom instructions and the previous summary", () => {
+  const prompt = buildSummaryPrompt("t", {
+    customInstructions: "focus on the retry path",
+    previousSummary: "earlier run fixed the parser",
+  });
+  assert.ok(prompt.includes("focus on the retry path"));
+  assert.ok(prompt.includes("<previous_summary>earlier run fixed the parser</previous_summary>"));
+});
+
+test("runPotetoCompaction returns the compaction Pi expects", async () => {
+  const seen: { model: unknown; context: unknown; options: unknown }[] = [];
+  const result = await runPotetoCompaction(PREPARATION, undefined, new AbortController().signal, {
+    model: { provider: "test", id: "parent-model" },
+    complete: async (model, context, options) => {
+      seen.push({ model, context, options });
+      return {
+        content: [{ type: "text", text: "## Playbook and position\nbug-fix, step 4" }],
+        usage: { input: 10, output: 5, cacheRead: 0, cacheWrite: 0 },
+      };
+    },
+    serialize: (messages) => `serialized:${messages.length}`,
+  });
+  assert.ok(result);
+  assert.equal(result.summary, "## Playbook and position\nbug-fix, step 4");
+  assert.equal(result.firstKeptEntryId, "entry-9");
+  assert.equal(result.tokensBefore, 148_000);
+  const call = seen[0];
+  assert.equal((call.context as { systemPrompt: string }).systemPrompt, SUMMARY_SYSTEM_FRAME);
+  assert.deepEqual(
+    (call.options as { maxTokens: number; cacheRetention: string }).maxTokens !== undefined,
+    true,
+  );
+  const text = (call.context as { messages: Array<{ content: Array<{ text: string }> }> }).messages[0]
+    .content[0].text;
+  assert.ok(text.includes("serialized:1"));
+});
+
+test("runPotetoCompaction falls back to default on empty summary, error, and missing model", async () => {
+  const notes: string[] = [];
+  const notify = (message: string) => notes.push(message);
+  const empty = await runPotetoCompaction(PREPARATION, undefined, new AbortController().signal, {
+    model: { provider: "test", id: "m" },
+    complete: async () => ({ content: [{ type: "text", text: "   " }] }),
+    serialize: () => "s",
+    notify,
+  });
+  assert.equal(empty, undefined);
+  assert.equal(notes.length, 1);
+
+  const failed = await runPotetoCompaction(PREPARATION, undefined, new AbortController().signal, {
+    model: { provider: "test", id: "m" },
+    complete: async () => {
+      throw new Error("provider down");
+    },
+    serialize: () => "s",
+    notify,
+  });
+  assert.equal(failed, undefined);
+  assert.ok(notes[1].includes("provider down"), notes[1]);
+
+  const noModel = await runPotetoCompaction(PREPARATION, undefined, new AbortController().signal, {
+    model: undefined,
+    complete: async () => {
+      throw new Error("must not be called");
+    },
+    serialize: () => "s",
+  });
+  assert.equal(noModel, undefined);
+});
+
+test("runPotetoCompaction honors an aborted signal without a fallback notify", async () => {
+  const controller = new AbortController();
+  controller.abort();
+  const notes: string[] = [];
+  const result = await runPotetoCompaction(PREPARATION, undefined, controller.signal, {
+    model: { provider: "test", id: "m" },
+    complete: async () => {
+      throw new Error("aborted");
+    },
+    serialize: () => "s",
+    notify: (message) => notes.push(message),
+  });
+  assert.equal(result, undefined);
+  assert.equal(notes.length, 0, "a user abort is not a failure worth reporting");
+});
+
+test("POTETO_COMPACT_INSTRUCTIONS covers the run state a compaction must keep", () => {
+  for (const needle of ["playbook", "decision ledger", "verified", "next actions"]) {
+    assert.ok(POTETO_COMPACT_INSTRUCTIONS.includes(needle), needle);
+  }
+});
+
+test("loadConversationHelpers resolves in a dev checkout and degrades gracefully", async () => {
+  const helpers = await loadConversationHelpers();
+  if (helpers) {
+    const text = helpers.serialize([{ role: "user", content: "hello" }]);
+    assert.ok(typeof text === "string" && text.length > 0);
+  }
+});

package/extensions/compaction.ts

@@ -0,0 +1,183 @@
+/**
+ * Poteto-flavored compaction for Poteto Mode.
+ *
+ * Pi's default compaction summarizes the conversation generically. When Poteto
+ * Mode is on, the run's value lives in specific places: the matched playbook
+ * and its step position, the decision ledger with the principles cited, the
+ * evidence of what has been verified, and the next actions. This module asks
+ * the session model for a summary shaped around those, and falls back to Pi's
+ * default compaction for any failure.
+ */
+
+import { randomUUID } from "node:crypto";
+import type { CompactionResult } from "@earendil-works/pi-coding-agent";
+
+/** Passed to ctx.compact() when the context guard offers a one-key compaction. */
+export const POTETO_COMPACT_INSTRUCTIONS =
+  "Preserve the pstack run state: the active playbook and its current step, " +
+  "the decision ledger with the principle each decision cited, what has been " +
+  "verified and how, file paths touched, and the next actions. Drop narration, " +
+  "raw tool output, and abandoned branches.";
+
+export const SUMMARY_SYSTEM_FRAME =
+  "You are summarizing a coding-agent session so work can continue after the " +
+  "oldest messages are dropped. The session ran under Pstack Poteto Mode. " +
+  "Be dense and concrete. No narration about the summarization itself.";
+
+export function buildSummaryPrompt(conversationText: string, extra?: {
+  previousSummary?: string;
+  customInstructions?: string;
+}): string {
+  const sections = [
+    "Summarize the conversation between the <conversation> tags. Structure the summary as markdown with exactly these sections:",
+    "",
+    "## Playbook and position",
+    "The matched playbook, the step the run is on, and the steps completed with their verdicts.",
+    "",
+    "## Decision ledger",
+    "One row per decision: what was decided, the principle cited for it, the evidence behind it.",
+    "",
+    "## Verified and unverified",
+    "What has been proven against the real artifact, with the proof. What is still claimed but unverified.",
+    "",
+    "## Files and artifacts",
+    "Every file touched or produced, with its path and what changed in it.",
+    "",
+    "## Next actions",
+    "The exact next steps, in order, with enough detail to execute them without re-reading the dropped messages.",
+    "",
+    "## Open questions",
+    "Blockers, unanswered questions, and promises made to the operator.",
+    "",
+    "Keep every file path, command, and measurement exact. Drop small talk, retries that ended in revert, and tool output that a file on disk already holds.",
+  ];
+  if (extra?.customInstructions) {
+    sections.push("", `The operator added this instruction for the summary: ${extra.customInstructions}`);
+  }
+  if (extra?.previousSummary) {
+    sections.push(
+      "",
+      "An earlier compaction produced this summary. Fold it in: keep what it holds that still matters, and update anything the newer conversation changed.",
+      "",
+      `<previous_summary>${extra.previousSummary}</previous_summary>`,
+    );
+  }
+  sections.push("", `<conversation>${conversationText}</conversation>`);
+  return sections.join("\n");
+}
+
+export interface CompactionPreparationLike {
+  firstKeptEntryId: string;
+  messagesToSummarize: unknown[];
+  turnPrefixMessages: unknown[];
+  tokensBefore: number;
+  previousSummary?: string;
+}
+
+interface TextBlockLike {
+  type: string;
+  text?: unknown;
+}
+
+function extractText(content: unknown): string {
+  if (typeof content === "string") return content;
+  if (!Array.isArray(content)) return "";
+  return (content as TextBlockLike[])
+    .filter((block) => block.type === "text" && typeof block.text === "string")
+    .map((block) => block.text as string)
+    .join("\n");
+}
+
+/**
+ * Runs the poteto compaction. Returns the compaction result Pi expects, or
+ * undefined to let Pi run its default compaction. Never throws: every failure
+ * path degrades to the default.
+ */
+export type UsageLike = NonNullable<CompactionResult["usage"]>;
+
+export async function runPotetoCompaction(
+  preparation: CompactionPreparationLike,
+  customInstructions: string | undefined,
+  signal: AbortSignal,
+  deps: {
+    model: unknown;
+    complete: (model: unknown, context: unknown, options: unknown) => Promise<unknown>;
+    serialize: (messages: unknown[]) => string;
+    notify?: (message: string, level?: "info" | "warning" | "error") => void;
+  },
+): Promise<{
+  summary: string;
+  firstKeptEntryId: string;
+  tokensBefore: number;
+  usage?: UsageLike;
+} | undefined> {
+  if (!deps.model) return undefined;
+  try {
+    const messages = [...preparation.messagesToSummarize, ...preparation.turnPrefixMessages];
+    const conversationText = deps.serialize(messages);
+    const prompt = buildSummaryPrompt(conversationText, {
+      previousSummary: preparation.previousSummary,
+      customInstructions,
+    });
+    const response = (await deps.complete(
+      deps.model,
+      {
+        messages: [
+          {
+            role: "user",
+            content: [{ type: "text", text: prompt }],
+            timestamp: Date.now(),
+          },
+        ],
+        systemPrompt: SUMMARY_SYSTEM_FRAME,
+      },
+      {
+        maxTokens: 8192,
+        signal,
+        cacheRetention: "none",
+        sessionId: randomUUID(),
+      },
+    )) as { content?: unknown; usage?: UsageLike } | undefined;
+
+    const summary = extractText(response?.content).trim();
+    if (!summary) {
+      deps.notify?.("pstack compaction: empty summary, using Pi's default", "warning");
+      return undefined;
+    }
+    return {
+      summary,
+      firstKeptEntryId: preparation.firstKeptEntryId,
+      tokensBefore: preparation.tokensBefore,
+      usage: response?.usage,
+    };
+  } catch (error) {
+    if (signal.aborted) return undefined;
+    const message = error instanceof Error ? error.message : String(error);
+    deps.notify?.(`pstack compaction failed (${message}); using Pi's default`, "warning");
+    return undefined;
+  }
+}
+
+/**
+ * Loads the runtime conversation helpers from the pi-coding-agent install.
+ * Returns undefined when they cannot be resolved, which is the signal to fall
+ * back to default compaction. Static imports would make the whole extension
+ * fail to load on installs where the host package is not resolvable from the
+ * package directory.
+ */
+export async function loadConversationHelpers(): Promise<{
+  serialize: (messages: unknown[]) => string;
+} | undefined> {
+  try {
+    const core = (await import("@earendil-works/pi-coding-agent")) as {
+      convertToLlm?: (messages: unknown[]) => unknown[];
+      serializeConversation?: (messages: unknown[]) => string;
+    };
+    if (!core.convertToLlm || !core.serializeConversation) return undefined;
+    return {
+      serialize: (messages: unknown[]) => core.serializeConversation!(core.convertToLlm!(messages)),
+    };
+  } catch {
+    return undefined;
+  }
+}

package/extensions/context-guard.test.ts

@@ -0,0 +1,53 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  GUARD_THRESHOLDS,
+  formatPercent,
+  guardAdvice,
+  guardLevel,
+  isStronger,
+  meterLine,
+} from "./context-guard.ts";
+
+test("guardLevel maps usage percentages onto the ladder", () => {
+  assert.equal(guardLevel(null), "ok");
+  assert.equal(guardLevel(undefined), "ok");
+  assert.equal(guardLevel(Number.NaN), "ok");
+  assert.equal(guardLevel(0), "ok");
+  assert.equal(guardLevel(GUARD_THRESHOLDS.watch - 1), "ok");
+  assert.equal(guardLevel(GUARD_THRESHOLDS.watch), "watch");
+  assert.equal(guardLevel(GUARD_THRESHOLDS.warn - 1), "watch");
+  assert.equal(guardLevel(GUARD_THRESHOLDS.warn), "warn");
+  assert.equal(guardLevel(GUARD_THRESHOLDS.compact - 1), "warn");
+  assert.equal(guardLevel(GUARD_THRESHOLDS.compact), "compact");
+  assert.equal(guardLevel(100), "compact");
+});
+
+test("isStronger orders the ladder", () => {
+  assert.ok(isStronger("warn", "watch"));
+  assert.ok(isStronger("compact", "warn"));
+  assert.ok(!isStronger("watch", "warn"));
+  assert.ok(!isStronger("ok", "ok"));
+});
+
+test("formatPercent rounds and tolerates unknown usage", () => {
+  assert.equal(formatPercent(42.4), "42%");
+  assert.equal(formatPercent(42.5), "43%");
+  assert.equal(formatPercent(null), "?");
+  assert.equal(formatPercent(undefined), "?");
+});
+
+test("guardAdvice names the percentage and an action at every level", () => {
+  for (const level of ["watch", "warn", "compact"] as const) {
+    const advice = guardAdvice(level, 91);
+    assert.ok(advice.startsWith("pstack context guard: 91%"), advice);
+    assert.ok(advice.length > 40, `level ${level} carries real advice`);
+  }
+  assert.equal(guardAdvice("ok", 10), "");
+});
+
+test("meterLine renders the HUD line", () => {
+  const line = meterLine({ tokens: 42000, contextWindow: 200000, percent: 21 }, "medium");
+  assert.equal(line, "context: 21% of 200k | budget: medium");
+  assert.equal(meterLine(undefined, "unlimited"), "context: ? of 0k | budget: unlimited");
+});

package/extensions/context-guard.ts

@@ -0,0 +1,65 @@
+/**
+ * Context guard for Poteto Mode.
+ *
+ * Pi meters context usage; the harness can act on it in a way no skill file
+ * can. This module holds the pure decision logic: map a usage percentage to a
+ * guard level, and say what to do about it. The wiring lives in index.ts.
+ *
+ * The thresholds back the guard-the-context-window principle: finish the
+ * current step, capture the decision state, then free context deliberately
+ * instead of letting the automatic cut take the tail of the run.
+ */
+
+export interface ContextUsageLike {
+  tokens: number | null;
+  contextWindow: number;
+  percent: number | null;
+}
+
+export type GuardLevel = "ok" | "watch" | "warn" | "compact";
+
+/** Percent-of-context-window thresholds, ascending. */
+export const GUARD_THRESHOLDS = {
+  watch: 70,
+  warn: 85,
+  compact: 92,
+} as const;
+
+const LEVEL_ORDER: Record<GuardLevel, number> = { ok: 0, watch: 1, warn: 2, compact: 3 };
+
+export function guardLevel(percent: number | null | undefined): GuardLevel {
+  if (percent === null || percent === undefined || Number.isNaN(percent)) return "ok";
+  if (percent >= GUARD_THRESHOLDS.compact) return "compact";
+  if (percent >= GUARD_THRESHOLDS.warn) return "warn";
+  if (percent >= GUARD_THRESHOLDS.watch) return "watch";
+  return "ok";
+}
+
+export function isStronger(a: GuardLevel, b: GuardLevel): boolean {
+  return LEVEL_ORDER[a] > LEVEL_ORDER[b];
+}
+
+export function formatPercent(percent: number | null | undefined): string {
+  if (percent === null || percent === undefined || Number.isNaN(percent)) return "?";
+  return `${Math.round(percent)}%`;
+}
+
+const ADVICE: Record<Exclude<GuardLevel, "ok">, string> = {
+  watch:
+    "Context is filling up. Finish the current step, then hand long output to a file and point at it instead of pasting it back.",
+  warn:
+    "Context is high. Capture the decision state now: the active playbook, the step it is on, and what has been verified. Then run /compact, or accept the compaction offer.",
+  compact:
+    "Context is nearly full. Pi is about to compact on its own and the cut point is not yours to choose. Run /compact now to keep the playbook and evidence state intact.",
+};
+
+export function guardAdvice(level: GuardLevel, percent: number | null | undefined): string {
+  if (level === "ok") return "";
+  return `pstack context guard: ${formatPercent(percent)} of the context window. ${ADVICE[level]}`;
+}
+
+/** One HUD line for the poteto-mode widget. */
+export function meterLine(usage: ContextUsageLike | undefined, budget: string): string {
+  const percent = usage?.percent ?? null;
+  return `context: ${formatPercent(percent)} of ${Math.round((usage?.contextWindow ?? 0) / 1000)}k | budget: ${budget}`;
+}

package/extensions/doctor.test.ts

@@ -0,0 +1,85 @@
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  checkAgentFrontmatter,
+  checkModelMap,
+  checkModelValue,
+  checkThinkingValue,
+  renderReport,
+} from "./doctor.ts";
+
+test("checkModelValue accepts inherit and provider/id shapes only", () => {
+  assert.equal(checkModelValue("inherit"), null);
+  assert.equal(checkModelValue("opencode-go/hy3"), null);
+  assert.ok(checkModelValue("just-a-slug")?.includes("provider/id"));
+  assert.ok(checkModelValue("openrouter anthropic/claude")?.includes("provider/id"));
+});
+
+test("checkThinkingValue rejects anything off Pi's ladder", () => {
+  assert.equal(checkThinkingValue("high"), null);
+  assert.equal(checkThinkingValue("xhigh"), null);
+  assert.ok(checkThinkingValue("inherit")?.includes("not a Pi level"));
+  assert.ok(checkThinkingValue("maximum")?.includes("not a Pi level"));
+});
+
+test("checkModelMap flags typos, bad values, and bad fallbacks", () => {
+  const problems = checkModelMap(
+    {
+      defaultModel: "inherit",
+      defaultThinking: "medium",
+      agentOverrides: {
+        scout: { thinking: "low" },
+        wroker: { model: "nope" },
+        oracle: { model: "a/b", thinking: "max", fallbackModels: ["inherit", "bad fallback"] },
+      },
+    },
+    ["scout", "worker", "reviewer", "oracle"],
+  );
+  assert.equal(problems.length, 2, problems.join("; "));
+  assert.ok(problems.some((line) => line.includes("wroker") && line.includes("unknown role")));
+  assert.ok(problems.some((line) => line.includes("fallbackModels") && line.includes("provider/id")));
+});
+
+test("checkModelMap passes a healthy map", () => {
+  const problems = checkModelMap(
+    {
+      defaultModel: "inherit",
+      defaultThinking: "xhigh",
+      agentOverrides: {
+        scout: { model: "inherit", thinking: "low" },
+        oracle: { model: "a/b", fallbackModels: ["c/d"] },
+      },
+    },
+    ["scout", "oracle"],
+  );
+  assert.deepEqual(problems, []);
+});
+
+test("checkAgentFrontmatter requires a frontmatter block with name and description", () => {
+  assert.deepEqual(
+    checkAgentFrontmatter("poteto-agent.md", "---\nname: poteto-agent\ndescription: runs the mode\n---\nbody"),
+    [],
+  );
+  assert.equal(
+    checkAgentFrontmatter("broken.md", "no frontmatter here").length,
+    1,
+  );
+  const missing = checkAgentFrontmatter("thin.md", "---\nname: thin\n---\nbody");
+  assert.equal(missing.length, 1);
+  assert.ok(missing[0].includes("description"));
+});
+
+test("renderReport summarizes and counts findings", () => {
+  const clean = renderReport([
+    { name: "settings", status: "ok", detail: "parsed" },
+    { name: "agents", status: "ok", detail: "2 registered" },
+  ]);
+  assert.ok(clean.endsWith("pstack doctor: clean. Nothing to fix."));
+  const noisy = renderReport([
+    { name: "settings", status: "warn", detail: "unknown role" },
+    { name: "pin", status: "fail", detail: "stale" },
+  ]);
+  assert.ok(noisy.includes("warn  settings"));
+  assert.ok(noisy.includes("FAIL  pin"));
+  assert.ok(noisy.endsWith("pstack doctor: 2 findings."));
+});

package/extensions/doctor.ts

@@ -0,0 +1,100 @@
+/**
+ * /pstack-doctor: one command that checks the install the way a colleague
+ * would, offline. Pure validators live here; index.ts gathers the inputs.
+ */
+
+import type { ModelMap, ThinkingLevel } from "./settings.ts";
+
+export const PI_THINKING_LEVELS: readonly string[] = [
+  "off",
+  "minimal",
+  "low",
+  "medium",
+  "high",
+  "xhigh",
+  "max",
+];
+
+export interface DoctorCheck {
+  name: string;
+  status: "ok" | "warn" | "fail";
+  detail: string;
+}
+
+/** "inherit" is always valid. Anything else must look like provider/id. */
+export function checkModelValue(value: string): string | null {
+  if (value === "inherit") return null;
+  if (!value.includes("/") || /\s/.test(value)) {
+    return `model "${value}" is neither inherit nor provider/id`;
+  }
+  return null;
+}
+
+export function checkThinkingValue(value: string): string | null {
+  return PI_THINKING_LEVELS.includes(value) ? null : `thinking "${value}" is not a Pi level (${PI_THINKING_LEVELS.join(", ")})`;
+}
+
+/** Returns one human line per problem found in the map. */
+export function checkModelMap(map: ModelMap, knownRoles: readonly string[]): string[] {
+  const problems: string[] = [];
+  if (map.defaultModel) {
+    const problem = checkModelValue(map.defaultModel);
+    if (problem) problems.push(`defaultModel: ${problem}`);
+  }
+  if (map.defaultThinking) {
+    const problem = checkThinkingValue(map.defaultThinking);
+    if (problem) problems.push(`defaultThinking: ${problem}`);
+  }
+  for (const [role, spec] of Object.entries(map.agentOverrides ?? {})) {
+    if (!knownRoles.includes(role)) {
+      problems.push(
+        `agentOverrides.${role}: unknown role (known: ${knownRoles.join(", ")}) - a typo here silently does nothing`,
+      );
+      continue;
+    }
+    if (spec?.model) {
+      const problem = checkModelValue(spec.model);
+      if (problem) problems.push(`agentOverrides.${role}.model: ${problem}`);
+    }
+    if (spec?.thinking) {
+      const problem = checkThinkingValue(spec.thinking);
+      if (problem) problems.push(`agentOverrides.${role}.thinking: ${problem}`);
+    }
+    for (const fallback of spec?.fallbackModels ?? []) {
+      const problem = checkModelValue(fallback);
+      if (problem) problems.push(`agentOverrides.${role}.fallbackModels: ${problem}`);
+    }
+  }
+  return problems;
+}
+
+/**
+ * Minimal frontmatter check for a package agent file. Returns one line per
+ * problem. pi-subagents reads name and description from this block.
+ */
+export function checkAgentFrontmatter(fileName: string, content: string): string[] {
+  const problems: string[] = [];
+  const frontmatter = /^---\n([\s\S]*?)\n---/.exec(content)?.[1];
+  if (!frontmatter) {
+    problems.push(`${fileName}: no frontmatter block; pi-subagents cannot register it`);
+    return problems;
+  }
+  for (const field of ["name", "description"]) {
+    if (!new RegExp(`^${field}:`, "m").test(frontmatter)) {
+      problems.push(`${fileName}: frontmatter is missing "${field}"`);
+    }
+  }
+  return problems;
+}
+
+export function renderReport(checks: readonly DoctorCheck[]): string {
+  const mark = { ok: "ok  ", warn: "warn", fail: "FAIL" } as const;
+  const lines = checks.map((check) => `${mark[check.status]}  ${check.name}: ${check.detail}`);
+  const warnings = checks.filter((check) => check.status !== "ok").length;
+  lines.push(
+    warnings === 0
+      ? "pstack doctor: clean. Nothing to fix."
+      : `pstack doctor: ${warnings} finding${warnings === 1 ? "" : "s"}.`,
+  );
+  return lines.join("\n");
+}