pi-warden 0.7.0 → 0.9.0

package/dist/notify.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Desktop notifications for the moments the user has to come back to the terminal: a held call the agent will ask
+ * about, a confirm dialog waiting for an answer, a stopped runaway. The notifier is detected once per session with a
+ * probe (never inside a tool_call handler); sending is fire-and-forget, and a failure is silent.
+ */
+export type NotifierName = "osascript" | "notify-send" | "dunstify" | "gdbus" | "kdialog" | "zenity" | "powershell" | "wsl-powershell";
+export interface Notification {
+    title: string;
+    body: string;
+}
+export interface NotifierCommand {
+    file: string;
+    args: string[];
+    /** Text travels in the environment where the shell needs no quoting (PowerShell). */
+    env?: Record<string, string>;
+}
+interface Candidate {
+    name: NotifierName;
+    /** Probe: the command exists and answers. */
+    probe: {
+        file: string;
+        args: readonly string[];
+    };
+}
+/** Platform order: the native route first, then the desktop-agnostic tools, then the shells that reach another desktop (WSL). */
+export declare function candidates(platform?: NodeJS.Platform): readonly Candidate[];
+/** A user-configured argv: `{title}` and `{body}` in any argument are replaced; the text is also in PI_WARDEN_TITLE / PI_WARDEN_BODY. */
+export type NotifierTarget = NotifierName | readonly string[];
+/** The command that shows one notification with the given tool. Text goes as arguments or environment, never through a shell. */
+export declare function notifierCommand(target: NotifierTarget, notification: Notification): NotifierCommand;
+export type Runner = (file: string, args: readonly string[], options: {
+    timeoutMs: number;
+    env?: Record<string, string>;
+}) => Promise<boolean>;
+/** Runs a command detached from the terminal; resolves to whether it exited cleanly. Never throws. */
+export declare const run: Runner;
+/** First notifier whose probe answers on this machine, or undefined when the desktop cannot be reached. */
+export declare function detectNotifier(platform?: NodeJS.Platform, runner?: Runner, timeoutMs?: number): Promise<NotifierName | undefined>;
+/** Notifications truncate around a hundred characters; keep the reason first. */
+export declare function clipBody(text: string, limit?: number): string;
+export declare function sendNotification(target: NotifierTarget, notification: Notification, runner?: Runner, timeoutMs?: number): Promise<boolean>;
+export {};

package/dist/notify.js

@@ -0,0 +1,99 @@
+import { execFile } from "node:child_process";
+/** Windows PowerShell's own AppUserModelId: a toast needs a registered application, and this one exists on every install. */
+const POWERSHELL_APP_ID = "{1AC14E77-02E7-4E5D-B744-2EB1AE5198B7}\\WindowsPowerShell\\v1.0\\powershell.exe";
+const TOAST_SCRIPT = [
+    "[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null",
+    "[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null",
+    "$template = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent([Windows.UI.Notifications.ToastTemplateType]::ToastText02)",
+    "$text = $template.GetElementsByTagName('text')",
+    "$text.Item(0).AppendChild($template.CreateTextNode($env:PI_WARDEN_TITLE)) | Out-Null",
+    "$text.Item(1).AppendChild($template.CreateTextNode($env:PI_WARDEN_BODY)) | Out-Null",
+    "$toast = [Windows.UI.Notifications.ToastNotification]::new($template)",
+    `[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('${POWERSHELL_APP_ID}').Show($toast)`,
+].join("; ");
+/** Platform order: the native route first, then the desktop-agnostic tools, then the shells that reach another desktop (WSL). */
+export function candidates(platform = process.platform) {
+    const pwshProbe = ["-NoProfile", "-NonInteractive", "-Command", "exit 0"];
+    switch (platform) {
+        case "darwin":
+            return [{ name: "osascript", probe: { file: "osascript", args: ["-e", "return 0"] } }];
+        case "win32":
+            return [{ name: "powershell", probe: { file: "powershell", args: pwshProbe } }];
+        default:
+            return [
+                { name: "notify-send", probe: { file: "notify-send", args: ["--version"] } },
+                { name: "dunstify", probe: { file: "dunstify", args: ["--help"] } },
+                { name: "gdbus", probe: { file: "gdbus", args: ["help"] } },
+                { name: "kdialog", probe: { file: "kdialog", args: ["--version"] } },
+                { name: "zenity", probe: { file: "zenity", args: ["--version"] } },
+                // WSL: the Linux side has no notification daemon, but Windows PowerShell is on PATH and shows a toast.
+                { name: "wsl-powershell", probe: { file: "powershell.exe", args: pwshProbe } },
+            ];
+    }
+}
+/** AppleScript string literal: only backslash and double quote need escaping. */
+const appleScriptString = (text) => `"${text.replace(/\\/g, "\\\\").replace(/"/g, "\\\"")}"`;
+/** GVariant string literal for gdbus: single quotes with backslash escapes. */
+const gvariantString = (text) => `'${text.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+/** The command that shows one notification with the given tool. Text goes as arguments or environment, never through a shell. */
+export function notifierCommand(target, notification) {
+    const { title, body } = notification;
+    if (typeof target !== "string") {
+        const [file = "", ...rest] = target;
+        return { file, args: rest.map(arg => arg.replaceAll("{title}", title).replaceAll("{body}", body)), env: { PI_WARDEN_TITLE: title, PI_WARDEN_BODY: body } };
+    }
+    switch (target) {
+        case "osascript":
+            return { file: "osascript", args: ["-e", `display notification ${appleScriptString(body)} with title ${appleScriptString(title)} sound name "Submarine"`] };
+        case "notify-send":
+            return { file: "notify-send", args: ["--app-name=pi-warden", "--urgency=critical", "--icon=dialog-warning", title, body] };
+        case "dunstify":
+            return { file: "dunstify", args: ["--appname=pi-warden", "--urgency=critical", title, body] };
+        case "gdbus":
+            return {
+                file: "gdbus",
+                args: ["call", "--session", "--dest", "org.freedesktop.Notifications", "--object-path", "/org/freedesktop/Notifications", "--method", "org.freedesktop.Notifications.Notify",
+                    "pi-warden", "0", "dialog-warning", gvariantString(title), gvariantString(body), "[]", "{'urgency': <byte 2>}", "-1"],
+            };
+        case "kdialog":
+            return { file: "kdialog", args: ["--title", title, "--passivepopup", body, "15"] };
+        case "zenity":
+            return { file: "zenity", args: ["--notification", `--text=${title}: ${body}`] };
+        case "powershell":
+        case "wsl-powershell":
+            return {
+                file: target === "powershell" ? "powershell" : "powershell.exe",
+                args: ["-NoProfile", "-NonInteractive", "-Command", TOAST_SCRIPT],
+                env: { PI_WARDEN_TITLE: title, PI_WARDEN_BODY: body },
+            };
+    }
+}
+/** Runs a command detached from the terminal; resolves to whether it exited cleanly. Never throws. */
+export const run = (file, args, options) => new Promise(resolve => {
+    try {
+        const env = options.env ? { ...process.env, ...options.env } : process.env;
+        execFile(file, [...args], { timeout: options.timeoutMs, windowsHide: true, maxBuffer: 64 * 1024, env }, error => resolve(!error));
+    }
+    catch {
+        resolve(false);
+    }
+});
+/** First notifier whose probe answers on this machine, or undefined when the desktop cannot be reached. */
+export async function detectNotifier(platform = process.platform, runner = run, timeoutMs = 3000) {
+    for (const candidate of candidates(platform)) {
+        if (await runner(candidate.probe.file, candidate.probe.args, { timeoutMs }))
+            return candidate.name;
+    }
+    return undefined;
+}
+/** Notifications truncate around a hundred characters; keep the reason first. */
+export function clipBody(text, limit = 180) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= limit ? flat : `${flat.slice(0, limit - 1)}…`;
+}
+export async function sendNotification(target, notification, runner = run, timeoutMs = 8000) {
+    const command = notifierCommand(target, { title: notification.title, body: clipBody(notification.body) });
+    if (!command.file)
+        return false;
+    return runner(command.file, command.args, { timeoutMs, ...(command.env ? { env: command.env } : {}) });
+}

package/dist/panel.js

@@ -1,5 +1,5 @@
 import { Key, matchesKey, truncateToWidth, wrapTextWithAnsi } from "@earendil-works/pi-tui";
-const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", nudged: "warning", confirm: "error", stuck: "error", "false claim": "error" };
+const LEVEL_COLOR = { allow: "success", ok: "success", warn: "warning", unverified: "warning", nudged: "warning", confirm: "error", stuck: "error", "false claim": "error", stopped: "error", "stopped, recovering": "error", violation: "warning", skipped: "muted" };
 /**
  * Sidebar listing the trace newest-first, live-updating while open. It opens without taking keyboard input: the editor
  * keeps working while it is visible. A click inside it (fullscreen mode) focuses it; then ↑/↓/j/k scroll a line,

package/dist/rules.d.ts

@@ -0,0 +1,164 @@
+import type { IntegrationErrorCode } from "pi-typesafe";
+import type { RulesConfig } from "./config.js";
+import type { Judge } from "./jev.js";
+/**
+ * Project rules: Markdown headings become rules, Jev judges each write or edit against every rule on its own request, and the
+ * agent is steered, never held, with the violated rule. Path scoping and sensitive-path notes are code only.
+ *
+ * Sources, in order: `pi-warden.md` at the project root; else the files in `rules.files`; else, with `rules.fallback`, the
+ * first of README.md, CLAUDE.md, AGENTS.md as one aggregate rule set. Files are re-read when their mtime or size changes.
+ */
+export interface Rule {
+    id: string;
+    name: string;
+    /** Rule text under the heading, fences included, `paths:` line removed. */
+    body: string;
+    /** Globs the rule applies to; empty means every file. */
+    paths: string[];
+}
+export interface RuleSet {
+    /** Project-relative file names the rules came from. */
+    sources: string[];
+    rules: Rule[];
+    /** Fallback documents have no rule headings: one question judges the content against this whole text. */
+    aggregate?: string;
+    /** Rules past the request cap, dropped in file order. */
+    dropped: number;
+}
+export declare const RULES_FILE = "pi-warden.md";
+export declare const FALLBACK_FILES: string[];
+/** TypeSafe answers at most 32 questions per request; one is kept for the edit locator. */
+export declare const MAX_RULES = 31;
+/**
+ * A fallback document cut to `limit` characters while keeping its shape: every heading stays and each section keeps its
+ * head, so a rule stated in the last section of a very long AGENTS.md is still seen. Code inside fences is treated as text.
+ */
+export declare function condense(text: string, limit: number): string;
+/**
+ * Headings at the highest level present outside code fences delimit rules (`#` in a jev-rules style file, `##` under a
+ * document title). Text before the first such heading is not a rule. A `paths:` line at the top of a body scopes the rule.
+ */
+export declare function parseRules(markdown: string): Rule[];
+export declare function globToRegExp(pattern: string): RegExp;
+/** The first pattern that matches the path, or undefined. */
+export declare function matchGlob(path: string, patterns: readonly string[]): string | undefined;
+/** Project-relative path with forward slashes, or undefined when the target lies outside the project. */
+export declare function projectPath(target: string, cwd: string): string | undefined;
+export declare class RuleStore {
+    private readonly cache;
+    private read;
+    /** The active rule set for a project, or undefined when no source exists. Never throws. */
+    load(cwd: string, config: Pick<RulesConfig, "files" | "fallback" | "maxChars">): RuleSet | undefined;
+}
+/** Rules that apply to a path: unscoped rules plus those whose `paths` match. */
+export declare function rulesFor(set: RuleSet, path: string): Rule[];
+export declare function describeRuleSet(set: RuleSet | undefined): string;
+export interface EditView {
+    id: string;
+    /** Current file text around the replaced text, when the file exists and the text was found. */
+    before?: string;
+    newText: string;
+}
+export interface RulesTarget {
+    tool: "write" | "edit";
+    /** Project-relative path. */
+    path: string;
+    content?: string;
+    edits?: EditView[];
+    /** Edits beyond MAX_EDITS, not shown. */
+    moreEdits?: number;
+}
+/** The redacted content of a write or edit as Jev sees it, or undefined when the call carries nothing to judge. */
+export declare function describeTarget(tool: string, input: Record<string, unknown>, cwd: string): RulesTarget | undefined;
+export type RuleOutcome = "compliant" | "violation" | "not_applicable" | "insufficient_context";
+export declare const AGGREGATE_QUESTION = "rules";
+export declare const LOCATOR_QUESTION = "which_edit";
+export declare function ruleQuestion(rule: Rule): import("pi-typesafe").ChoiceQuestion<Record<RuleOutcome, string>>;
+export declare function buildRulesRequest(target: RulesTarget, set: RuleSet): {
+    state: {
+        rules?: string;
+        moreEdits?: number;
+        edits?: {
+            newText: string;
+            before?: string;
+            id: string;
+        }[];
+        content?: string;
+        path: string;
+    };
+    questions: Record<string, import("pi-typesafe").ChoiceQuestion<import("@typesafe-ai/sdk").ChoiceCriteria>>;
+    applicable: Rule[];
+};
+export interface RuleScore {
+    id: string;
+    name: string;
+    outcome: RuleOutcome;
+    violation: number;
+}
+export interface RuleFinding extends RuleScore {
+    body: string;
+}
+export interface RulesVerdict {
+    source: "skipped" | "typesafe" | "error";
+    path: string;
+    tool: "write" | "edit";
+    sources: string[];
+    /** Rules asked about, after path scoping; 1 for an aggregate document. */
+    asked: number;
+    aggregate: boolean;
+    scores?: RuleScore[];
+    /** Violations at or above the threshold, strongest first. */
+    findings: RuleFinding[];
+    /** The edit Jev points at when several edits were judged and something was flagged. */
+    editId?: string;
+    editPreview?: string;
+    model?: string;
+    elapsedMs?: number;
+    skippedReason?: string;
+    error?: string;
+    errorCode?: IntegrationErrorCode;
+}
+export interface RulesOptions {
+    cwd: string;
+    config: RulesConfig;
+    set: RuleSet | undefined;
+    judge?: Judge | undefined;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+/** Why a write or edit is not judged against the rules: nothing to judge, no rules, or a path the config keeps out. */
+export declare function skipReason(target: RulesTarget | undefined, set: RuleSet | undefined, config: RulesConfig): string | undefined;
+export declare function evaluateRules(tool: string, input: Record<string, unknown>, options: RulesOptions): Promise<RulesVerdict>;
+/** Names each violated rule with a short quote of its text; the third hit of one rule in a session makes it a standing rule. */
+export declare function rulesSteer(verdict: RulesVerdict, counts: ReadonlyMap<string, number>): string;
+export declare function formatRules(verdict: RulesVerdict, template?: string): string;
+export interface PathNote {
+    glob: string;
+    note: string;
+}
+export declare function pathNotes(path: string | undefined, notes: Readonly<Record<string, string>>): PathNote[];
+export declare function pathNoteSteer(path: string, hits: readonly PathNote[]): string;
+export interface RulesCallRef {
+    id: string;
+    tool: string;
+    input: Record<string, unknown>;
+}
+/**
+ * The Rules guard for one session: loads and caches the rule sources, judges each write or edit on its own request (fired
+ * together with the action guard's), prejudges sibling writes so their requests overlap, and counts hits per rule so a repeat
+ * becomes a standing rule.
+ */
+export declare class RulesGuard {
+    readonly store: RuleStore;
+    private readonly prejudged;
+    private readonly counts;
+    private readonly noted;
+    inspect(call: RulesCallRef, siblings: readonly RulesCallRef[], options: Omit<RulesOptions, "set">): Promise<RulesVerdict>;
+    /** Records the findings and returns the per-rule session counts the steer text uses. */
+    count(verdict: RulesVerdict): ReadonlyMap<string, number>;
+    /** Sensitive-path notes not yet given for this path in this session. */
+    notesFor(path: string | undefined, notes: Readonly<Record<string, string>>): PathNote[];
+    describe(cwd: string, config: Pick<RulesConfig, "files" | "fallback" | "maxChars">): string;
+    turnEnd(): void;
+    reset(): void;
+}