pi-warden 0.2.1 → 0.4.0

package/dist/panel.js

@@ -0,0 +1,121 @@
+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" };
+/**
+ * Side panel listing the trace newest-first, live-updating while open. Keys: ↑/↓/j/k scroll a line, PgUp/PgDn a page,
+ * Home/End jump, c clears the trace, Esc or q closes. Wheel scrolling works in fullscreen mode.
+ */
+export class TracePanel {
+    trace;
+    theme;
+    close;
+    requestRender;
+    title;
+    focused = true;
+    scroll = 0;
+    viewport = 20;
+    unsubscribe;
+    constructor(trace, theme, close, requestRender, title = "pi-warden trace") {
+        this.trace = trace;
+        this.theme = theme;
+        this.close = close;
+        this.requestRender = requestRender;
+        this.title = title;
+        this.unsubscribe = trace.subscribe(() => this.requestRender());
+    }
+    dispose() {
+        this.unsubscribe();
+    }
+    /** Rendering is cheap and derived from the trace each time; nothing is cached. */
+    invalidate() { }
+    lines(width) {
+        const { theme } = this;
+        const entries = this.trace.entries();
+        const out = [];
+        out.push(theme.bold(theme.fg("accent", ` ${this.title}`)) + theme.fg("muted", ` · ${entries.length} event${entries.length === 1 ? "" : "s"} · ↑↓ PgUp PgDn scroll · c clear · esc close`));
+        out.push(theme.fg("muted", "─".repeat(Math.max(0, width))));
+        if (!entries.length) {
+            out.push(theme.fg("muted", " No guarded activity yet this session. Verdicts, Jev scores, and what the agent was told will appear here."));
+            return out.map(line => truncateToWidth(line, width, ""));
+        }
+        for (let index = entries.length - 1; index >= 0; index--) {
+            const entry = entries[index];
+            const status = entry.line.split(" · ").at(-1) ?? "";
+            const color = LEVEL_COLOR[status] ?? "text";
+            const head = `${theme.fg("muted", new Date(entry.at).toTimeString().slice(0, 8))} ${theme.fg(color, theme.bold(entry.guard.padEnd(6)))} `;
+            const headWidth = 9 + 7;
+            const body = wrapTextWithAnsi(theme.fg(color, entry.line), Math.max(10, width - headWidth));
+            out.push(head + (body[0] ?? ""));
+            for (const continuation of body.slice(1))
+                out.push(" ".repeat(headWidth) + continuation);
+            for (const detail of entry.details) {
+                const wrapped = wrapTextWithAnsi(detail, Math.max(10, width - headWidth - 2));
+                for (const [n, line] of wrapped.entries())
+                    out.push(" ".repeat(headWidth) + theme.fg("muted", n === 0 ? "· " : "  ") + theme.fg("dim", line));
+            }
+            out.push("");
+        }
+        return out.map(line => truncateToWidth(line, width, ""));
+    }
+    render(width) {
+        const all = this.lines(width);
+        const maxScroll = Math.max(0, all.length - this.viewport);
+        if (this.scroll > maxScroll)
+            this.scroll = maxScroll;
+        const visible = all.slice(this.scroll, this.scroll + this.viewport);
+        if (all.length > this.viewport) {
+            const last = visible.length - 1;
+            visible[last] = truncateToWidth(theme_fg(this.theme, "muted", ` … ${all.length - this.scroll - this.viewport > 0 ? `${all.length - this.scroll - this.viewport} more lines below` : "end"} · ${this.scroll} above`), width, "");
+        }
+        return visible;
+    }
+    /** The overlay tells us how tall we may be through the layout; fall back to a fixed viewport otherwise. */
+    setViewport(rows) {
+        this.viewport = Math.max(5, rows);
+    }
+    handleInput(data) {
+        if (matchesKey(data, Key.escape) || data === "q" || matchesKey(data, Key.ctrl("c"))) {
+            this.close();
+            return;
+        }
+        if (matchesKey(data, Key.up) || data === "k")
+            this.scroll = Math.max(0, this.scroll - 1);
+        else if (matchesKey(data, Key.down) || data === "j")
+            this.scroll += 1;
+        else if (matchesKey(data, Key.pageUp))
+            this.scroll = Math.max(0, this.scroll - this.viewport);
+        else if (matchesKey(data, Key.pageDown))
+            this.scroll += this.viewport;
+        else if (matchesKey(data, Key.home))
+            this.scroll = 0;
+        else if (matchesKey(data, Key.end))
+            this.scroll = Number.MAX_SAFE_INTEGER;
+        else if (data === "c")
+            this.trace.clear();
+        else
+            return;
+        this.requestRender();
+    }
+    handleMouse(event) {
+        if (event.type === "wheel") {
+            this.scroll = Math.max(0, this.scroll + (event.wheelDelta ?? 0) * 3);
+            return { handled: true, render: true };
+        }
+        return undefined;
+    }
+}
+function theme_fg(theme, color, text) {
+    return theme.fg(color, text);
+}
+/** Open the trace as a right-hand overlay. Resolves when the user closes it. */
+export function openTracePanel(ui, trace) {
+    return ui.custom((tui, theme, _keybindings, done) => {
+        const panel = new TracePanel(trace, theme, () => done(), () => tui.requestRender());
+        const rows = tui.terminal?.rows;
+        if (typeof rows === "number")
+            panel.setViewport(Math.floor(rows * 0.9) - 2);
+        return panel;
+    }, {
+        overlay: true,
+        overlayOptions: { anchor: "right-center", width: "48%", minWidth: 56, maxHeight: "90%", margin: { right: 1 } },
+    });
+}

package/dist/prose.d.ts

@@ -0,0 +1,57 @@
+import type { ProseConfig } from "./config.js";
+import type { Judge } from "./guard.js";
+export type ProseSymptom = "wordy" | "cliches" | "jargon";
+export declare const PROSE_SYMPTOMS: readonly ProseSymptom[];
+export declare const proseQuestions: {
+    wordy: import("pi-typesafe").NoulQuestion;
+    cliches: import("pi-typesafe").NoulQuestion;
+    jargon: import("pi-typesafe").NoulQuestion;
+};
+export declare const PROSE_LABELS: Record<ProseSymptom, string>;
+/** Map the two built-in audience names to descriptions Jev can judge against; anything else is used as written. */
+export declare function describeAudience(audience: string): string;
+export interface ProseVerdict {
+    scores?: Record<ProseSymptom, number>;
+    /** Symptoms at or above the threshold for this reply, strongest first. */
+    flagged: ProseSymptom[];
+    /** Set by the caller when a nudge was sent. */
+    nudged?: boolean;
+    model?: string;
+    elapsedMs?: number;
+    error?: string;
+}
+export declare function buildProseRequest(task: string | undefined, reply: string, audience: string): {
+    state: {
+        task: string;
+        audience: string;
+        reply: string;
+    };
+    questions: {
+        wordy: import("pi-typesafe").NoulQuestion;
+        cliches: import("pi-typesafe").NoulQuestion;
+        jargon: import("pi-typesafe").NoulQuestion;
+    };
+};
+export interface ProseOptions {
+    config: ProseConfig;
+    judge: Judge;
+    timeoutMs: number;
+    signal?: AbortSignal | undefined;
+}
+export declare function evaluateProse(task: string | undefined, reply: string, options: ProseOptions): Promise<ProseVerdict>;
+/**
+ * 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 declare class ProseTrend {
+    private readonly history;
+    private cooldown;
+    readonly counts: Record<ProseSymptom, number>;
+    record(flagged: readonly ProseSymptom[]): void;
+    /** Symptoms that crossed the trend requirement, or an empty list during cool-down. */
+    due(trend: number): ProseSymptom[];
+    markNudged(): void;
+    reset(): void;
+}
+/** Queued for the next user prompt, so it shapes the next reply without spending a turn. */
+export declare function proseNudge(symptoms: readonly ProseSymptom[], audience: string, counts: Record<ProseSymptom, number>): string;

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/stuck.d.ts

@@ -32,8 +32,11 @@ export declare function resultText(content: ReadonlyArray<{
     type: string;
     text?: string;
 }>): string;
-/** Non-zero exit codes count as failures even when the tool did not flag an error. */
-export declare function resultFailed(isError: boolean, details: unknown): boolean;
+/** Non-zero exit codes count as failures even when the tool did not flag an error; context-mode reports them in the text. */
+export declare function resultFailed(isError: boolean, details: unknown, content?: ReadonlyArray<{
+    type: string;
+    text?: string;
+}>): boolean;
 export declare function makeAttempt(tool: string, input: Record<string, unknown>, content: ReadonlyArray<{
     type: string;
     text?: string;
@@ -85,4 +88,4 @@ export interface StuckOptions {
 export declare function evaluateStuck(window: AttemptWindow, task: string | undefined, options: StuckOptions): Promise<StuckVerdict>;
 /** Steering text for the agent. Names the pattern and asks for a change of method, not another retry. */
 export declare function stuckNudge(verdict: StuckVerdict): string;
-export declare function formatStuck(verdict: StuckVerdict): string;
+export declare function formatStuck(verdict: StuckVerdict, template?: string): string;

package/dist/stuck.js

@@ -1,6 +1,8 @@
 import { createHash } from "node:crypto";
 import { noul, score, TypeSafeIntegrationError } from "pi-typesafe";
 import { redact } from "./redact.js";
+import { commandOf, outputReportsFailure } from "./tools.js";
+import { DEFAULT_TEMPLATES, renderTemplate, stuckTokens } from "./widget.js";
 const CALL_LIMIT = 300;
 const OUTPUT_LIMIT = 400;
 function head(text, limit) {
@@ -13,12 +15,14 @@ function tail(text, limit) {
 export function resultText(content) {
     return content.filter(part => part.type === "text" && typeof part.text === "string").map(part => part.text).join("\n");
 }
-/** Non-zero exit codes count as failures even when the tool did not flag an error. */
-export function resultFailed(isError, details) {
+/** Non-zero exit codes count as failures even when the tool did not flag an error; context-mode reports them in the text. */
+export function resultFailed(isError, details, content = []) {
     if (isError)
         return true;
     const exitCode = details && typeof details === "object" ? details.exitCode : undefined;
-    return typeof exitCode === "number" && exitCode !== 0;
+    if (typeof exitCode === "number" && exitCode !== 0)
+        return true;
+    return outputReportsFailure(resultText(content));
 }
 /** Durations, timestamps, PIDs, and addresses change between identical runs; counts and line numbers stay. */
 function normaliseOutput(text) {
@@ -29,7 +33,8 @@ function normaliseOutput(text) {
         .replace(/\d{4}-\d{2}-\d{2}[T ]\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?Z?/g, "#date");
 }
 export function makeAttempt(tool, input, content, failed) {
-    const call = typeof input.command === "string" ? input.command
+    const command = commandOf(tool, input)?.command;
+    const call = command !== undefined ? command
         : typeof input.path === "string" ? `${tool} ${input.path}`
             : JSON.stringify(input);
     const text = resultText(content).trim();
@@ -135,14 +140,6 @@ export async function evaluateStuck(window, task, options) {
 export function stuckNudge(verdict) {
     return `pi-warden: ${verdict.reasons.join("; ")}. Stop retrying. Re-read the last error output carefully, state a new hypothesis about the cause, and either gather the missing information (read the relevant file, check versions or paths) or try a different method. If two different methods have failed, report the blocker to the user with the exact error instead of trying again.`;
 }
-export function formatStuck(verdict) {
-    const parts = [`warden · stuck · ${verdict.failures} failures`];
-    if (verdict.judgment)
-        parts.push(`same strategy ${verdict.judgment.sameStrategy.toFixed(2)}`, `change ${verdict.judgment.approachChange.toFixed(1)}/2`, `progress ${verdict.judgment.progress.toFixed(2)}`);
-    if (verdict.source === "repeat" && verdict.stuck)
-        parts.push("exact repeat");
-    if (verdict.source === "error")
-        parts.push("typesafe error");
-    parts.push(verdict.stuck ? "stuck" : "ok");
-    return parts.join(" · ");
+export function formatStuck(verdict, template = DEFAULT_TEMPLATES.stuck) {
+    return renderTemplate(template, stuckTokens(verdict));
 }

package/dist/tools.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Knowledge of which tool inputs carry shell commands. Pi's built-ins plus context-mode's ctx_* tools, which many Pi users
+ * run instead of bash. Unknown tools return nothing and are judged from their JSON input only.
+ */
+export interface CommandView {
+    /** Shell text to pattern-match and judge. Several commands are joined with newlines. */
+    command: string;
+    /** False when the code is not shell (JavaScript, Python …); pattern rules still run, the read-only shortcut does not. */
+    shell: boolean;
+}
+/** Extract the command text a tool call would execute, or undefined for tools that run no commands. */
+export declare function commandOf(tool: string, input: Record<string, unknown>): CommandView | undefined;
+/** Tools whose calls carry commands and should be guarded by default. */
+export declare const COMMAND_TOOLS: string[];
+/** Text that signals failure in tool output when the tool itself did not flag an error (context-mode reports exit codes inline). */
+export declare function outputReportsFailure(text: string): boolean;

package/dist/tools.js

@@ -0,0 +1,37 @@
+/**
+ * Knowledge of which tool inputs carry shell commands. Pi's built-ins plus context-mode's ctx_* tools, which many Pi users
+ * run instead of bash. Unknown tools return nothing and are judged from their JSON input only.
+ */
+const SHELL_LANGUAGES = new Set(["shell", "bash", "sh", "zsh", "powershell"]);
+function commandsOf(value) {
+    if (!Array.isArray(value))
+        return [];
+    return value.map(item => (item && typeof item === "object" ? item.command : undefined)).filter((command) => typeof command === "string");
+}
+/** Extract the command text a tool call would execute, or undefined for tools that run no commands. */
+export function commandOf(tool, input) {
+    switch (tool) {
+        case "bash":
+        case "powershell":
+            return typeof input.command === "string" ? { command: input.command, shell: true } : undefined;
+        case "ctx_execute":
+        case "ctx_execute_file": {
+            if (typeof input.code !== "string")
+                return undefined;
+            const language = typeof input.language === "string" ? input.language.toLowerCase() : "";
+            return { command: input.code, shell: SHELL_LANGUAGES.has(language) };
+        }
+        case "ctx_batch_execute": {
+            const commands = commandsOf(input.commands);
+            return commands.length ? { command: commands.join("\n"), shell: true } : undefined;
+        }
+        default:
+            return undefined;
+    }
+}
+/** Tools whose calls carry commands and should be guarded by default. */
+export const COMMAND_TOOLS = ["bash", "powershell", "ctx_execute", "ctx_batch_execute", "ctx_execute_file"];
+/** Text that signals failure in tool output when the tool itself did not flag an error (context-mode reports exit codes inline). */
+export function outputReportsFailure(text) {
+    return /(?:^|\n)\s*Command exited with code [1-9]\d*\b/.test(text) || /(?:^|\n)\s*\(timed out\)\s*$/.test(text);
+}

package/dist/trace.d.ts

@@ -0,0 +1,31 @@
+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" | "prose";
+export interface TraceEntry {
+    at: number;
+    guard: GuardName;
+    /** The widget line for this event. */
+    line: string;
+    /** Redacted details: what was inspected, what Jev answered, what the agent was told. */
+    details: string[];
+}
+/** Session memory of guard decisions; the widget shows the latest line per guard, the panel shows the history. */
+export declare class Trace {
+    private readonly limit;
+    private readonly items;
+    private readonly listeners;
+    constructor(limit?: number);
+    push(entry: TraceEntry): void;
+    entries(): readonly TraceEntry[];
+    clear(): void;
+    subscribe(listener: () => void): () => void;
+}
+export declare function actionDetails(verdict: Verdict, extra?: {
+    mode?: string;
+    told?: string;
+}): 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

@@ -0,0 +1,93 @@
+/** Session memory of guard decisions; the widget shows the latest line per guard, the panel shows the history. */
+export class Trace {
+    limit;
+    items = [];
+    listeners = new Set();
+    constructor(limit = 100) {
+        this.limit = limit;
+    }
+    push(entry) {
+        this.items.push(entry);
+        if (this.items.length > this.limit)
+            this.items.splice(0, this.items.length - this.limit);
+        for (const listener of this.listeners)
+            listener();
+    }
+    entries() {
+        return this.items;
+    }
+    clear() {
+        this.items.length = 0;
+        for (const listener of this.listeners)
+            listener();
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => { this.listeners.delete(listener); };
+    }
+}
+const clip = (text, limit) => (text.length <= limit ? text : `${text.slice(0, limit)}…`);
+const percent = (value) => value.toFixed(2);
+export function actionDetails(verdict, extra = {}) {
+    const { summary, judgment } = verdict;
+    const lines = [];
+    if (summary.command !== undefined)
+        lines.push(`ran: ${clip(summary.command.replace(/\s+/g, " "), 300)}`);
+    if (summary.path !== undefined)
+        lines.push(`${summary.tool} ${summary.path}${summary.location === "outside_project" ? " (outside the project)" : ""}${summary.exists === false ? " (new file)" : ""}${summary.bytes !== undefined ? ` · ${summary.bytes} bytes` : ""}${summary.editCount !== undefined ? ` · ${summary.editCount} edit${summary.editCount === 1 ? "" : "s"}` : ""}`);
+    if (summary.input !== undefined)
+        lines.push(`input: ${clip(summary.input, 300)}`);
+    if (verdict.patterns.length)
+        lines.push(`patterns: ${verdict.patterns.map(hit => `${hit.id} (${hit.severity})`).join(", ")}`);
+    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 (verdict.slop)
+        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)
+        lines.push(`typesafe: ${verdict.error}`);
+    if (extra.mode && verdict.level === "confirm")
+        lines.push(`mode: ${extra.mode}`);
+    if (extra.told)
+        lines.push(`agent told: ${clip(extra.told, 400)}`);
+    return lines;
+}
+export function stuckDetails(verdict, attempts, told) {
+    const lines = attempts.map((attempt, index) => `${index + 1}. ${attempt.failed ? "✗" : "✓"} ${clip(attempt.call.replace(/\s+/g, " "), 120)}${attempt.failed && attempt.output ? ` → ${clip(attempt.output.replace(/\s+/g, " "), 120)}` : ""}`);
+    if (verdict.judgment)
+        lines.push(`jev: same strategy ${percent(verdict.judgment.sameStrategy)} · approach change ${verdict.judgment.approachChange.toFixed(2)}/2 · progress ${percent(verdict.judgment.progress)} · ${verdict.judgment.model} · ${verdict.judgment.elapsedMs} ms`);
+    if (verdict.reasons.length)
+        lines.push(`why: ${verdict.reasons.join("; ")}`);
+    if (verdict.error)
+        lines.push(`typesafe: ${verdict.error}`);
+    if (told)
+        lines.push(`agent told: ${clip(told, 400)}`);
+    return lines;
+}
+export function doneDetails(verdict, finalMessage, told) {
+    const lines = [`final message: ${clip(finalMessage.replace(/\s+/g, " "), 300)}`];
+    lines.push(`evidence: ${verdict.evidence.mutations} code change${verdict.evidence.mutations === 1 ? "" : "s"}${verdict.evidence.checks.length ? `; checks: ${verdict.evidence.checks.map(check => `${clip(check.call, 60)} → ${check.passed ? "passed" : "failed"}`).join(", ")}` : "; no checks ran"}`);
+    if (verdict.judgment)
+        lines.push(`jev: claims done ${percent(verdict.judgment.claimsDone)} · claims verified ${percent(verdict.judgment.claimsVerified)} · checks apply ${percent(verdict.judgment.verificationApplies)} · ${verdict.judgment.outcome} · ${verdict.judgment.model} · ${verdict.judgment.elapsedMs} ms`);
+    if (verdict.reasons.length)
+        lines.push(`why: ${verdict.reasons.join("; ")}`);
+    if (verdict.error)
+        lines.push(`typesafe: ${verdict.error}`);
+    if (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

@@ -0,0 +1,40 @@
+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 {
+    enabled: boolean;
+    placement: WidgetPlacement;
+    /** Keyboard shortcut that opens the trace panel; empty string disables it. */
+    shortcut: string;
+    /** Templates per guard. Segments are separated by " · "; a segment whose token has no value is dropped. */
+    action: string;
+    stuck: string;
+    done: string;
+    prose: string;
+}
+export declare const DEFAULT_TEMPLATES: {
+    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}";
+};
+export declare function defaultWidgetConfig(): WidgetConfig;
+export type Tokens = Record<string, string | undefined>;
+/**
+ * Fill `{token}` placeholders. The template is split on " · "; a segment is dropped when any of its tokens is empty,
+ * so optional information disappears together with its label. Unknown tokens render as empty (and drop their segment).
+ */
+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", "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"];
+};