pi-warden 0.3.0 → 0.5.0

package/dist/prose.js

@@ -0,0 +1,98 @@
+import { noul, TypeSafeIntegrationError } from "pi-typesafe";
+import { redact } from "./redact.js";
+export const PROSE_SYMPTOMS = ["wordy", "cliches", "jargon"];
+export const proseQuestions = {
+    wordy: noul("Is `reply` longer than its content requires: a preamble, restating the request, summarising what it just said, or filler sentences that add no information?", {
+        true: "Yes: it opens with what it is about to do, repeats the question, ends with a summary of the same points, or pads with sentences that could be removed without losing anything.",
+        false: "No: each sentence carries information the reader needs; length matches the substance.",
+    }),
+    cliches: noul("Does `reply` use assistant clichés or filler phrasing: \"Great question\", \"Certainly!\", \"I hope this helps\", \"it's worth noting\", \"delve\", \"let me know if\", unrequested bullet lists of caveats, or emoji headings?", {
+        true: "Yes: one or more such phrases or patterns are present.",
+        false: "No: the wording is direct and specific to the subject.",
+    }),
+    jargon: noul("Would a reader described by `audience` struggle with `reply` because of unexplained technical terms or assumed background?", {
+        true: "Yes: terms, acronyms, or concepts appear without explanation that this audience would not know.",
+        false: "No: the reply matches what this audience can follow, or the audience is technical.",
+    }),
+};
+export const PROSE_LABELS = {
+    wordy: "longer than the content needs (preamble, restating, summarising, filler)",
+    cliches: "assistant clichés or filler phrasing",
+    jargon: "unexplained technical terms for the configured audience",
+};
+const AUDIENCES = {
+    technical: "a software developer who knows this codebase and its tools",
+    plain: "a non-programmer who owns the product and reads the reply as a status update",
+};
+/** Map the two built-in audience names to descriptions Jev can judge against; anything else is used as written. */
+export function describeAudience(audience) {
+    return AUDIENCES[audience.toLowerCase()] ?? audience;
+}
+export function buildProseRequest(task, reply, audience) {
+    return {
+        state: {
+            task: task?.trim() ? (task.trim().length > 1000 ? `${task.trim().slice(0, 1000)}…` : task.trim()) : "(no user request recorded in this session)",
+            audience: describeAudience(audience),
+            reply: redact(reply.length > 2500 ? `${reply.slice(0, 2500)}…` : reply),
+        },
+        questions: proseQuestions,
+    };
+}
+export async function evaluateProse(task, reply, options) {
+    try {
+        const timeout = AbortSignal.timeout(options.timeoutMs);
+        const result = await options.judge.evaluate(buildProseRequest(task, reply, options.config.audience), { signal: options.signal ? AbortSignal.any([options.signal, timeout]) : timeout });
+        const scores = { wordy: result.answers.wordy.noul, cliches: result.answers.cliches.noul, jargon: result.answers.jargon.noul };
+        const flagged = PROSE_SYMPTOMS.filter(symptom => scores[symptom] >= options.config.threshold).sort((a, b) => scores[b] - scores[a]);
+        return { scores, flagged, model: result.model, elapsedMs: result.elapsedMs };
+    }
+    catch (error) {
+        return { flagged: [], error: error instanceof TypeSafeIntegrationError ? error.message : "TypeSafe request failed." };
+    }
+}
+/**
+ * Remembers the last three replies' symptoms. A nudge needs a symptom in `trend` of them, so one long answer to a long
+ * question is not punished, and after a nudge the next two replies are given time to change.
+ */
+export class ProseTrend {
+    history = [];
+    cooldown = 0;
+    counts = { wordy: 0, cliches: 0, jargon: 0 };
+    record(flagged) {
+        this.history.push([...flagged]);
+        if (this.history.length > 3)
+            this.history.shift();
+        for (const symptom of flagged)
+            this.counts[symptom]++;
+        if (this.cooldown > 0)
+            this.cooldown--;
+    }
+    /** Symptoms that crossed the trend requirement, or an empty list during cool-down. */
+    due(trend) {
+        if (this.cooldown > 0)
+            return [];
+        return PROSE_SYMPTOMS.filter(symptom => this.history.filter(set => set.includes(symptom)).length >= trend);
+    }
+    markNudged() {
+        this.cooldown = 2;
+    }
+    reset() {
+        this.history.length = 0;
+        this.cooldown = 0;
+        for (const symptom of PROSE_SYMPTOMS)
+            this.counts[symptom] = 0;
+    }
+}
+/** Queued for the next user prompt, so it shapes the next reply without spending a turn. */
+export function proseNudge(symptoms, audience, counts) {
+    const parts = symptoms.map(symptom => `${PROSE_LABELS[symptom]}${counts[symptom] >= 3 ? ` (${counts[symptom]} replies this session)` : ""}`);
+    const fixes = [];
+    if (symptoms.includes("wordy"))
+        fixes.push("lead with the answer, cut preambles and closing summaries, and stop when the information is complete");
+    if (symptoms.includes("cliches"))
+        fixes.push("drop filler phrases and unrequested caveat lists");
+    if (symptoms.includes("jargon"))
+        fixes.push(`write for ${describeAudience(audience)}: explain or replace technical terms`);
+    const standing = symptoms.some(symptom => counts[symptom] >= 3) ? " Treat this as a standing rule for the rest of the session." : "";
+    return `pi-warden: your recent replies read as ${parts.join("; ")}. From the next reply on, ${fixes.join("; ")}.${standing}`;
+}

package/dist/trace.d.ts

@@ -1,7 +1,8 @@
 import type { DoneVerdict } from "./done.js";
 import type { Verdict } from "./guard.js";
+import type { ProseVerdict } from "./prose.js";
 import type { Attempt, StuckVerdict } from "./stuck.js";
-export type GuardName = "action" | "stuck" | "done";
+export type GuardName = "action" | "stuck" | "done" | "prose" | "security" | "context";
 export interface TraceEntry {
     at: number;
     guard: GuardName;
@@ -27,3 +28,4 @@ export declare function actionDetails(verdict: Verdict, extra?: {
 }): string[];
 export declare function stuckDetails(verdict: StuckVerdict, attempts: readonly Attempt[], told?: string): string[];
 export declare function doneDetails(verdict: DoneVerdict, finalMessage: string, told?: string): string[];
+export declare function proseDetails(verdict: ProseVerdict, reply: string, audience: string, told?: string): string[];

package/dist/trace.js

@@ -42,8 +42,10 @@ export function actionDetails(verdict, extra = {}) {
     if (judgment) {
         lines.push(`jev: irreversible ${percent(judgment.irreversible)} · off-task ${percent(judgment.offTask)} · ${judgment.scope.replace(/_/g, " ")} (${percent(judgment.scopeConfidence)})${judgment.approved !== undefined ? ` · approved ${percent(judgment.approved)}` : ""} · ${judgment.model} · ${judgment.elapsedMs} ms`);
     }
+    if (judgment?.securityRisk !== undefined)
+        lines.push(`security risk: ${percent(judgment.securityRisk)}`);
     if (verdict.slop)
-        lines.push(`slop: quality ${verdict.slop.quality.toFixed(2)}/2 · placeholder ${percent(verdict.slop.placeholder)}${verdict.slopReasons?.length ? ` → ${verdict.slopReasons.join("; ")}` : ""}`);
+        lines.push(`slop: stub ${percent(verdict.slop.stub)} · comments ${percent(verdict.slop.comments)} · dead ${percent(verdict.slop.dead)} · hedging ${percent(verdict.slop.hedging)}${verdict.slopReasons?.length ? ` → ${verdict.slopReasons.join("; ")}` : ""}`);
     if (verdict.reasons.length)
         lines.push(`why: ${verdict.reasons.join("; ")}`);
     if (verdict.error)
@@ -79,3 +81,15 @@ export function doneDetails(verdict, finalMessage, told) {
         lines.push(`agent told: ${clip(told, 400)}`);
     return lines;
 }
+export function proseDetails(verdict, reply, audience, told) {
+    const lines = [`reply: ${clip(reply.replace(/\s+/g, " "), 300)}`, `audience: ${audience}`];
+    if (verdict.scores)
+        lines.push(`jev: wordy ${percent(verdict.scores.wordy)} · clichés ${percent(verdict.scores.cliches)} · jargon ${percent(verdict.scores.jargon)}${verdict.model ? ` · ${verdict.model} · ${verdict.elapsedMs} ms` : ""}`);
+    if (verdict.flagged.length)
+        lines.push(`flagged: ${verdict.flagged.join(", ")}`);
+    if (verdict.error)
+        lines.push(`typesafe: ${verdict.error}`);
+    if (told)
+        lines.push(`agent told: ${clip(told, 400)}`);
+    return lines;
+}

package/dist/widget.d.ts

@@ -1,5 +1,6 @@
 import type { DoneVerdict } from "./done.js";
 import type { Verdict } from "./guard.js";
+import type { ProseVerdict } from "./prose.js";
 import type { StuckVerdict } from "./stuck.js";
 export type WidgetPlacement = "aboveEditor" | "belowEditor";
 export interface WidgetConfig {
@@ -11,11 +12,17 @@ export interface WidgetConfig {
     action: string;
     stuck: string;
     done: string;
+    prose: string;
+    security: string;
+    context: string;
 }
 export declare const DEFAULT_TEMPLATES: {
-    readonly action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop {slopQuality} · stub {slopStub} · patterns: {patterns} · {flags} · {level}";
+    readonly action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop: {slop} · patterns: {patterns} · {flags} · {level}";
     readonly stuck: "warden · stuck · {failures} failures · same strategy {sameStrategy} · change {approachChange} · progress {progress} · {flags} · {status}";
     readonly done: "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}";
+    readonly prose: "warden · prose · wordy {wordy} · clichés {cliches} · jargon {jargon} · {flags} · {status}";
+    readonly security: "warden · security · {tool} · injection {injection} · exfiltration {exfiltration} · {status}";
+    readonly context: "warden · context · {tool} · {retention} · saved {bytesSaved} bytes";
 };
 export declare function defaultWidgetConfig(): WidgetConfig;
 export type Tokens = Record<string, string | undefined>;
@@ -27,9 +34,13 @@ export declare function renderTemplate(template: string, tokens: Tokens): string
 export declare function actionTokens(verdict: Verdict, at?: number): Tokens;
 export declare function stuckTokens(verdict: StuckVerdict, at?: number): Tokens;
 export declare function doneTokens(verdict: DoneVerdict, at?: number): Tokens;
+export declare function proseTokens(verdict: ProseVerdict, at?: number): Tokens;
 /** Token names users can put in templates, for /warden status and the README. */
 export declare const TOKEN_NAMES: {
-    readonly action: readonly ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slopQuality", "slopStub", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"];
+    readonly security: readonly ["tool", "injection", "exfiltration", "status"];
+    readonly context: readonly ["tool", "retention", "bytesSaved"];
+    readonly action: readonly ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slop", "slopStub", "slopComments", "slopDead", "slopHedging", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"];
+    readonly prose: readonly ["wordy", "cliches", "jargon", "status", "reasons", "model", "ms", "flags", "time", "guard"];
     readonly stuck: readonly ["failures", "sameStrategy", "approachChange", "progress", "status", "source", "reasons", "model", "ms", "flags", "time", "guard"];
     readonly done: readonly ["changes", "checks", "checksPassed", "claimsDone", "claimsVerified", "checksApply", "outcome", "status", "reasons", "model", "ms", "flags", "time", "guard"];
 };

package/dist/widget.js

@@ -1,7 +1,10 @@
 export const DEFAULT_TEMPLATES = {
-    action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop {slopQuality} · stub {slopStub} · patterns: {patterns} · {flags} · {level}",
+    action: "warden · {tool} · irreversible {irreversible} · off-task {offTask} · {scope} · slop: {slop} · patterns: {patterns} · {flags} · {level}",
     stuck: "warden · stuck · {failures} failures · same strategy {sameStrategy} · change {approachChange} · progress {progress} · {flags} · {status}",
     done: "warden · done-check · {changes} changes · {checksPassed}/{checks} checks passed · claims done {claimsDone} · claims verified {claimsVerified} · checks apply {checksApply} · {outcome} · {status}",
+    prose: "warden · prose · wordy {wordy} · clichés {cliches} · jargon {jargon} · {flags} · {status}",
+    security: "warden · security · {tool} · injection {injection} · exfiltration {exfiltration} · {status}",
+    context: "warden · context · {tool} · {retention} · saved {bytesSaved} bytes",
 };
 export function defaultWidgetConfig() {
     return { enabled: true, placement: "aboveEditor", shortcut: "ctrl+shift+w", ...DEFAULT_TEMPLATES };
@@ -45,8 +48,11 @@ export function actionTokens(verdict, at = Date.now()) {
         offTask: fixed(verdict.judgment?.offTask),
         scope: verdict.judgment?.scope.replace(/_/g, " "),
         approved: fixed(verdict.judgment?.approved),
-        slopQuality: verdict.slop ? `${verdict.slop.quality.toFixed(1)}/2` : undefined,
-        slopStub: fixed(verdict.slop?.placeholder),
+        slop: verdict.slopSymptoms?.length ? verdict.slopSymptoms.map(symptom => `${symptom} ${verdict.slop[symptom].toFixed(2)}`).join(", ") : verdict.slop ? "none" : undefined,
+        slopStub: fixed(verdict.slop?.stub),
+        slopComments: fixed(verdict.slop?.comments),
+        slopDead: fixed(verdict.slop?.dead),
+        slopHedging: fixed(verdict.slop?.hedging),
         patterns: verdict.patterns.length ? verdict.patterns.map(hit => hit.id).join(", ") : undefined,
         reasons: verdict.reasons.length ? verdict.reasons.join("; ") : undefined,
         path: verdict.summary.path,
@@ -93,9 +99,26 @@ export function doneTokens(verdict, at = Date.now()) {
         flags: verdict.error ? "typesafe error" : undefined,
     };
 }
+export function proseTokens(verdict, at = Date.now()) {
+    return {
+        guard: "prose",
+        time: time(at),
+        wordy: fixed(verdict.scores?.wordy),
+        cliches: fixed(verdict.scores?.cliches),
+        jargon: fixed(verdict.scores?.jargon),
+        status: verdict.nudged ? "nudged" : verdict.flagged.length ? verdict.flagged.join(", ") : "ok",
+        reasons: verdict.flagged.length ? verdict.flagged.join(", ") : undefined,
+        model: verdict.model,
+        ms: verdict.elapsedMs === undefined ? undefined : String(verdict.elapsedMs),
+        flags: verdict.error ? "typesafe error" : undefined,
+    };
+}
 /** Token names users can put in templates, for /warden status and the README. */
 export const TOKEN_NAMES = {
-    action: ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slopQuality", "slopStub", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"],
+    security: ["tool", "injection", "exfiltration", "status"],
+    context: ["tool", "retention", "bytesSaved"],
+    action: ["tool", "level", "source", "irreversible", "offTask", "scope", "approved", "slop", "slopStub", "slopComments", "slopDead", "slopHedging", "patterns", "reasons", "path", "model", "ms", "flags", "time", "guard"],
+    prose: ["wordy", "cliches", "jargon", "status", "reasons", "model", "ms", "flags", "time", "guard"],
     stuck: ["failures", "sameStrategy", "approachChange", "progress", "status", "source", "reasons", "model", "ms", "flags", "time", "guard"],
     done: ["changes", "checks", "checksPassed", "claimsDone", "claimsVerified", "checksApply", "outcome", "status", "reasons", "model", "ms", "flags", "time", "guard"],
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-warden",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Guardrails for Pi built on pi-typesafe that steer the agent instead of interrupting you: Jev judges irreversible and off-task tool calls before they run, detects stuck loops, checks unverified done claims, and flags slop.",
   "type": "module",
   "license": "MIT",