@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-clearance/src/skill/clearance-tune/verify.ts

@@ -0,0 +1,238 @@
+import type { EffectivePolicy } from "../../policy/core.ts";
+import type { CorpusEntry, ReplayCorpus } from "../../replay/history.ts";
+import {
+  effectToStatus,
+  type RatchetReport,
+  type ReplayBashParser,
+  type ReplayStatus,
+  replayHistory,
+} from "../../replay/ratchet.ts";
+import { renderRatchetMarkdown } from "../../replay/ratchet-markdown.ts";
+
+export type FixtureExpected = "fast_path" | "review" | "hard_block";
+
+export interface FixtureRegression {
+  readonly command: string;
+  readonly expected: FixtureExpected;
+  readonly actual: ReplayStatus;
+  readonly severity: "hard" | "soft";
+  readonly reason: string;
+}
+
+export interface VerificationResult {
+  readonly report: RatchetReport;
+  readonly markdown: string;
+  readonly fixtureRegressions: readonly FixtureRegression[];
+  readonly fixtureChecked: number;
+  readonly expansions: { readonly calls: number; readonly unique: number };
+  readonly ok: boolean;
+  readonly warnings: readonly string[];
+}
+
+interface VerifyAfterWriteOptions {
+  readonly bashParser?: ReplayBashParser;
+  readonly clock?: () => Date;
+}
+
+interface VerifyFixturesOptions {
+  readonly bashParser?: ReplayBashParser;
+}
+
+interface FixtureVerification {
+  readonly regressions: readonly FixtureRegression[];
+  readonly checked: number;
+  readonly warnings: readonly string[];
+}
+
+/** Post-write verification: compare + fixture regressions. Pure (injected parser). */
+export async function verifyAfterWrite(
+  userCorpus: ReplayCorpus,
+  fixtureCorpus: ReplayCorpus,
+  beforePolicy: EffectivePolicy,
+  afterPolicy: EffectivePolicy,
+  options?: VerifyAfterWriteOptions,
+): Promise<VerificationResult> {
+  const report = await replayHistory(userCorpus, beforePolicy, {
+    proposedPolicy: afterPolicy,
+    ...(options?.clock === undefined ? {} : { clock: options.clock }),
+  });
+  const fixtureOptions =
+    options?.bashParser === undefined
+      ? undefined
+      : { bashParser: options.bashParser };
+  const fixture = await runFixtureVerification(
+    fixtureCorpus,
+    afterPolicy,
+    fixtureOptions,
+  );
+  const beforeStatuses = await fixtureStatusByCommand(
+    fixtureCorpus,
+    beforePolicy,
+    fixtureOptions,
+  );
+  const regressions = fixture.regressions.map((regression) =>
+    softenPreexistingHardRegression(regression, beforeStatuses),
+  );
+  const hardRegressions = regressions.filter(
+    (regression) => regression.severity === "hard",
+  );
+
+  return {
+    report,
+    markdown: renderRatchetMarkdown(report),
+    fixtureRegressions: regressions,
+    fixtureChecked: fixture.checked,
+    expansions: report.compare?.expansions ?? { calls: 0, unique: 0 },
+    ok: hardRegressions.length === 0,
+    warnings: [...report.corpus.warnings, ...fixture.warnings],
+  };
+}
+
+/** Check shipped fixtures for regressions against a policy. Pure helper. */
+export async function verifyFixtures(
+  fixtureCorpus: ReplayCorpus,
+  policy: EffectivePolicy,
+  options?: VerifyFixturesOptions,
+): Promise<readonly FixtureRegression[]> {
+  const verification = await runFixtureVerification(
+    fixtureCorpus,
+    policy,
+    options,
+  );
+  return verification.regressions;
+}
+
+async function runFixtureVerification(
+  fixtureCorpus: ReplayCorpus,
+  policy: EffectivePolicy,
+  _options?: VerifyFixturesOptions,
+): Promise<FixtureVerification> {
+  const report = await replayHistory(fixtureCorpus, policy);
+  const statusByCommand = statusMapFromReport(report);
+  const expectedRows = fixtureExpectedRows(fixtureCorpus.entries);
+
+  return {
+    regressions: expectedRows.flatMap((entry) => {
+      const actual = statusByCommand.get(entry.command);
+      if (actual === undefined) {
+        return [missingReplayRowRegression(entry)];
+      }
+
+      return actual === expectedToStatus(entry.expectedLabel)
+        ? []
+        : [fixtureRegression(entry.command, entry.expectedLabel, actual)];
+    }),
+    checked: expectedRows.length,
+    warnings: report.corpus.warnings,
+  };
+}
+
+async function fixtureStatusByCommand(
+  fixtureCorpus: ReplayCorpus,
+  policy: EffectivePolicy,
+  _options?: VerifyFixturesOptions,
+): Promise<ReadonlyMap<string, ReplayStatus>> {
+  const report = await replayHistory(fixtureCorpus, policy);
+  return statusMapFromReport(report);
+}
+
+function statusMapFromReport(
+  report: RatchetReport,
+): ReadonlyMap<string, ReplayStatus> {
+  return new Map(
+    report.perCommand.map((row) => [row.command, row.status] as const),
+  );
+}
+
+function softenPreexistingHardRegression(
+  regression: FixtureRegression,
+  beforeStatuses: ReadonlyMap<string, ReplayStatus>,
+): FixtureRegression {
+  // The shipped fixture corpus can contain known baseline drift. An apply run
+  // should fail on newly introduced hard widenings, not on a hard mismatch that
+  // already existed before the approved proposal was written.
+  if (regression.severity !== "hard") {
+    return regression;
+  }
+
+  const beforeStatus = beforeStatuses.get(regression.command);
+  if (beforeStatus !== regression.actual) {
+    return regression;
+  }
+
+  return {
+    ...regression,
+    severity: "soft",
+    reason: `${regression.reason} (pre-existing before this apply run)`,
+  };
+}
+
+function fixtureExpectedRows(
+  entries: readonly CorpusEntry[],
+): readonly (CorpusEntry & { readonly expectedLabel: FixtureExpected })[] {
+  return entries.filter(
+    (
+      entry,
+    ): entry is CorpusEntry & { readonly expectedLabel: FixtureExpected } =>
+      entry.expectedLabel !== undefined,
+  );
+}
+
+function expectedToStatus(expected: FixtureExpected): ReplayStatus {
+  switch (expected) {
+    case "fast_path":
+      return effectToStatus("allow");
+    case "review":
+      return effectToStatus("review");
+    case "hard_block":
+      return effectToStatus("deny");
+  }
+}
+
+function missingReplayRowRegression(entry: {
+  readonly command: string;
+  readonly expectedLabel: FixtureExpected;
+}): FixtureRegression {
+  return {
+    command: entry.command,
+    expected: entry.expectedLabel,
+    actual: "review",
+    severity: "soft",
+    reason:
+      "fixture carried an expected label but replay produced no matching command row",
+  };
+}
+
+function fixtureRegression(
+  command: string,
+  expected: FixtureExpected,
+  actual: ReplayStatus,
+): FixtureRegression {
+  const severity = regressionSeverity(expected, actual);
+  return {
+    command,
+    expected,
+    actual,
+    severity,
+    reason: regressionReason(expected, actual, severity),
+  };
+}
+
+function regressionSeverity(
+  expected: FixtureExpected,
+  actual: ReplayStatus,
+): FixtureRegression["severity"] {
+  return expected === "hard_block" && actual === "fast_path" ? "hard" : "soft";
+}
+
+function regressionReason(
+  expected: FixtureExpected,
+  actual: ReplayStatus,
+  severity: FixtureRegression["severity"],
+): string {
+  if (severity === "hard") {
+    return `fixture expected ${expected} but replay widened it to ${actual}`;
+  }
+
+  return `fixture expected ${expected} but replay returned ${actual}`;
+}

package/node_modules/@nklisch/pi-conveniences/README.md

@@ -0,0 +1,20 @@
+# @nklisch/pi-conveniences
+
+Small drop-in quality-of-life conveniences for Pi. Each is a tiny extension in
+`extensions/`; install the package once and they all load.
+
+```sh
+pi install npm:@nklisch/pi-conveniences
+```
+
+## Conveniences
+
+| Surface | What it does |
+| --- | --- |
+| `/exit` | Gracefully shuts Pi down — alias for the built-in `/quit`, for shell and Claude Code muscle memory. Runs `session_shutdown` handlers before exiting. |
+| `.agents/AGENTS.md` context | Loads `<cwd>/.agents/AGENTS.md` as a project context file. Pi natively walks ancestors and cwd for `AGENTS.md`, but does not look inside a `.agents/` tree — this closes that gap for projects that keep agent assets under `.agents/`. |
+| Context-window footer | A footer widget showing live context-window usage as a bar, with a toggle command. Coordinates with pi-catppuccin-tui's packaged footer so only one footer owner is active (opt out with `PI_CONVENIENCES_DISABLE_CATPPUCCIN_FOOTER=0`). |
+| `list_subagent_models` tool | Exposes Pi's configured model registry to the agent — available/scope-aware model listing with provider/model filters, so subagent spawning never guesses model identifiers. |
+
+Grew out of `@nklisch/pi-nates-toolkit`'s extension surfaces and a set of
+personal pi-config extensions.

package/node_modules/@nklisch/pi-conveniences/extensions/agents-context.test.ts

@@ -0,0 +1,140 @@
+import { describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import agentsContextExtension, { OPEN_TAG } from "./agents-context";
+
+type HandlerEvent = {
+  systemPrompt?: string;
+  systemPromptOptions?: { cwd?: string };
+};
+type HandlerRet = { systemPrompt: string } | undefined | void;
+
+/** Build a fake pi that captures the before_agent_start handler, like nates-toolkit.test. */
+function load() {
+  let handler: ((e: HandlerEvent) => HandlerRet) | null = null;
+  const pi = {
+    on: (event: string, h: (e: HandlerEvent) => HandlerRet) => {
+      if (event === "before_agent_start") handler = h;
+    },
+  };
+  agentsContextExtension(pi);
+  return {
+    fire: (e: HandlerEvent) => (handler ? handler(e) : undefined),
+    hasHandler: () => handler !== null,
+  };
+}
+
+describe("agents-context extension", () => {
+  let dir: string;
+
+  // Fresh temp dir per test → unique absPath → the module-level mtime cache
+  // never leaks a stale entry between tests.
+  function freshDir(): string {
+    const d = mkdtempSync(join(tmpdir(), "agents-context-"));
+    return d;
+  }
+
+  test("registers a before_agent_start handler", () => {
+    dir = freshDir();
+    try {
+      expect(load().hasHandler()).toBe(true);
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("no-op (returns undefined) when .agents/AGENTS.md is absent", () => {
+    dir = freshDir();
+    try {
+      const { fire } = load();
+      expect(fire({ systemPrompt: "BASE", systemPromptOptions: { cwd: dir } })).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("injects file content wrapped in the project_instructions tag, after the base", () => {
+    dir = freshDir();
+    try {
+      mkdirSync(join(dir, ".agents"), { recursive: true });
+      writeFileSync(join(dir, ".agents", "AGENTS.md"), "# House rules\n- be kind");
+      const { fire } = load();
+      const res = fire({ systemPrompt: "BASE", systemPromptOptions: { cwd: dir } });
+      expect(res).toBeDefined();
+      const sp = (res as { systemPrompt: string }).systemPrompt;
+      expect(sp.startsWith("BASE")).toBe(true);
+      expect(sp).toContain(OPEN_TAG);
+      expect(sp).toContain("# House rules");
+      expect(sp).toContain("- be kind");
+      expect(sp).toContain("</project_instructions>");
+      // The block is appended after the base, not replacing it.
+      expect(sp.indexOf("BASE")).toBeLessThan(sp.indexOf(OPEN_TAG));
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("idempotent: skips when the tag is already in the base prompt", () => {
+    dir = freshDir();
+    try {
+      mkdirSync(join(dir, ".agents"), { recursive: true });
+      writeFileSync(join(dir, ".agents", "AGENTS.md"), "rules");
+      const { fire } = load();
+      const baseWithTag = `BASE\n\n${OPEN_TAG}\nrules\n</project_instructions>`;
+      expect(fire({ systemPrompt: baseWithTag, systemPromptOptions: { cwd: dir } })).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("whitespace-only file is treated as a no-op", () => {
+    dir = freshDir();
+    try {
+      mkdirSync(join(dir, ".agents"), { recursive: true });
+      writeFileSync(join(dir, ".agents", "AGENTS.md"), "   \n  \t ");
+      const { fire } = load();
+      expect(fire({ systemPrompt: "BASE", systemPromptOptions: { cwd: dir } })).toBeUndefined();
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("picks up edits once the file's mtime advances (cache invalidation)", () => {
+    dir = freshDir();
+    try {
+      mkdirSync(join(dir, ".agents"), { recursive: true });
+      const file = join(dir, ".agents", "AGENTS.md");
+      writeFileSync(file, "version-1");
+      const { fire } = load();
+      const r1 = fire({ systemPrompt: "B", systemPromptOptions: { cwd: dir } }) as {
+        systemPrompt: string;
+      };
+      expect(r1.systemPrompt).toContain("version-1");
+
+      // Rewrite, then force a strictly-later mtime so the cache check must miss
+      // regardless of filesystem mtime resolution (some FSes are 1s granularity).
+      writeFileSync(file, "version-2");
+      const later = Date.now() / 1000 + 5;
+      utimesSync(file, later, later);
+
+      const r2 = fire({ systemPrompt: "B", systemPromptOptions: { cwd: dir } }) as {
+        systemPrompt: string;
+      };
+      expect(r2.systemPrompt).toContain("version-2");
+      expect(r2.systemPrompt).not.toContain("version-1");
+    } finally {
+      rmSync(dir, { recursive: true, force: true });
+    }
+  });
+
+  test("falls back to process.cwd() when the event omits cwd", () => {
+    // We can't easily control process.cwd(), so assert the handler does not
+    // throw and returns either undefined (no .agents/AGENTS.md in the real
+    // process cwd) or a string (if one happens to exist). The contract under
+    // test: it never throws when systemPromptOptions is absent.
+    const { fire } = load();
+    const res = fire({ systemPrompt: "BASE" });
+    expect(res === undefined || typeof (res as { systemPrompt?: string }).systemPrompt === "string").toBe(true);
+  });
+});

package/node_modules/@nklisch/pi-conveniences/extensions/agents-context.ts

@@ -0,0 +1,97 @@
+/**
+ * agents-context — inject <cwd>/.agents/AGENTS.md as a project context file.
+ *
+ * pi natively loads AGENTS.md / CLAUDE.md from only three places: the global
+ * dir (~/.pi/agent/), every ancestor of cwd walking up, and cwd itself. It does
+ * NOT look under <cwd>/.agents/AGENTS.md — which is exactly where projects that
+ * keep their agent assets in a .agents/ tree (e.g. a .agents/skills/ layout)
+ * tend to park project instructions. This extension closes that gap.
+ *
+ * On every before_agent_start it reads <cwd>/.agents/AGENTS.md and appends its
+ * contents to the system prompt as a <project_instructions path="..."> block —
+ * the same per-file format pi uses for native context files (system-prompt.js)
+ * — so the model treats it identically to the root AGENTS.md. The block lands
+ * just after the native <project_context> envelope rather than inside it (the
+ * prompt is already built by the time before_agent_start fires), which is the
+ * same append-after-build approach background-tasks uses for its explainer.
+ *
+ * Re-injecting every turn is deliberate, not wasteful: pi rebuilds the system
+ * prompt from the base each turn, so a one-shot session_start message would be
+ * summarized away on the first compaction and never come back. Returning the
+ * block every turn is compaction-immune — the same reason pi re-applies native
+ * context files each turn. An mtime-keyed cache keeps the steady-state cost to a
+ * single stat() per turn.
+ *
+ * Missing / unreadable / non-regular / empty file = silent no-op. Edits to the
+ * file are picked up live.
+ *
+ * House style (nates-toolkit / background-tasks): a locally-typed PiApi slice
+ * with optional methods and zero @earendil-works/* dependencies, so the file
+ * stays unit-testable with a fake pi under bare `bun test`.
+ */
+
+import { readFileSync, statSync } from "node:fs";
+import { join } from "node:path";
+
+/** Project-relative path this extension injects (relative to the session cwd). */
+export const RELATIVE_PATH = ".agents/AGENTS.md";
+/** The exact opening tag emitted — also the idempotency sentinel. */
+export const OPEN_TAG = `<project_instructions path="${RELATIVE_PATH}">`;
+
+type SystemPromptOptions = { cwd?: string };
+type BeforeAgentStartEvent = {
+  systemPrompt?: string;
+  systemPromptOptions?: SystemPromptOptions;
+};
+type PiApi = {
+  on?: (
+    event: "before_agent_start",
+    handler: (
+      event: BeforeAgentStartEvent,
+    ) => { systemPrompt: string } | undefined | void,
+  ) => void;
+};
+
+type Cached = { absPath: string; mtimeMs: number; content: string };
+let cache: Cached | null = null;
+
+/**
+ * Read <cwd>/.agents/AGENTS.md. Returns the trimmed contents, or null when the
+ * file is missing, unreadable, not a regular file, or empty. An mtime check
+ * skips the disk read when the file is unchanged since the last turn — so a
+ * live edit is picked up but a steady-state turn costs only a stat(). Never
+ * throws: a missing or unreadable file is a silent no-op, never a turn-breaking
+ * error.
+ */
+function readAgentsContext(cwd: string): string | null {
+  const absPath = join(cwd, RELATIVE_PATH);
+  try {
+    const st = statSync(absPath);
+    if (!st.isFile()) return null;
+    if (cache && cache.absPath === absPath && cache.mtimeMs === st.mtimeMs) {
+      return cache.content || null;
+    }
+    const content = readFileSync(absPath, "utf8").trim();
+    cache = { absPath, mtimeMs: st.mtimeMs, content };
+    return content || null;
+  } catch {
+    return null; // ENOENT, EACCES, etc. — silent no-op.
+  }
+}
+
+export default function agentsContextExtension(pi: PiApi): void {
+  pi.on?.("before_agent_start", (event) => {
+    const content = readAgentsContext(
+      event?.systemPromptOptions?.cwd ?? process.cwd(),
+    );
+    if (!content) return;
+    const base = event?.systemPrompt ?? "";
+    // Idempotency / double-registration guard. The prompt is rebuilt from base
+    // every turn, so under normal single registration `base` never contains our
+    // prior append — this only fires if a duplicate handler chains ahead of us.
+    // The sentinel is the exact opening tag we emit, so it can't false-positive
+    // on native context files (those carry different paths).
+    if (base.includes(OPEN_TAG)) return;
+    return { systemPrompt: `${base}\n\n${OPEN_TAG}\n${content}\n</project_instructions>` };
+  });
+}

package/node_modules/@nklisch/pi-conveniences/extensions/context-window-footer.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from "bun:test";
+import contextWindowFooterExtension from "./context-window-footer";
+
+function load() {
+  const commands = new Map<string, { description?: string }>();
+  const handlers = new Map<string, unknown>();
+  const pi = {
+    registerCommand: (name: string, options: { description?: string }) => {
+      commands.set(name, options);
+    },
+    on: (event: string, handler: unknown) => {
+      handlers.set(event, handler);
+    },
+  };
+  contextWindowFooterExtension(pi as never);
+  return { commands, handlers };
+}
+
+describe("context-window footer", () => {
+  test("registers a toggle command", () => {
+    const { commands } = load();
+    const names = [...commands.keys()].join(" ");
+    expect(names).toMatch(/context|footer/i);
+  });
+
+  test("hooks session lifecycle to install the footer", () => {
+    const { handlers } = load();
+    expect(handlers.size).toBeGreaterThan(0);
+  });
+});