pi-warden 1.0.0 → 1.4.0

package/dist/cause.js

@@ -0,0 +1,182 @@
+/**
+ * Cause-check: the sibling of the done-check.
+ *
+ * The done-check catches "done" with no check behind it. This one catches "the cause is X" with no check behind it: a
+ * final reply that names a likely cause, or hands a check to a person, when no tool result in the run tested it. The
+ * agent gets one follow-up turn: check it with its own tools and give the evidence, or say plainly that the cause is
+ * unverified and why it cannot check it. An unchecked cause is remembered per project for a week; a later unchecked
+ * cause of the same problem, matched by Jev, gets a stronger steer that names the earlier date.
+ *
+ * One offline pass runs first (`causePreFilter`), so a reply with no causal or hand-off wording costs no request.
+ */
+import { ask, choice, noul } from "pi-typesafe";
+import { redact } from "./redact.js";
+import { commandOf } from "./tools.js";
+import { DEFAULT_TEMPLATES, causeTokens, renderTemplate } from "./widget.js";
+/** P(checked) at or above which the stated cause counts as checked by the run. */
+const CHECKED_AT = 0.5;
+export function emptyCauseActivity() {
+    return { calls: [] };
+}
+const ACTIVITY_LIMIT = 40;
+const ACTIVITY_CALL_CHARS = 200;
+const ACTIVITY_OUTPUT_CHARS = 160;
+/** Earlier unchecked causes one request may carry for the repeat match, newest first. */
+const EARLIER_LIMIT = 5;
+/** Characters kept from the cause sentence for the stored summary and the repeat match. */
+const SUMMARY_CHARS = 300;
+/** Record one finished tool call: its redacted command or path, and a short redacted output sample. */
+export function recordCauseActivity(activity, tool, input, output) {
+    const view = commandOf(tool, input);
+    const path = typeof input.path === "string" ? input.path : typeof input.file_path === "string" ? input.file_path : undefined;
+    const call = view?.command ?? (path === undefined ? tool : `${tool} ${path}`);
+    const sample = output === undefined ? "" : redact(output.replace(/\s+/g, " ").slice(0, ACTIVITY_OUTPUT_CHARS));
+    activity.calls.push({ call: redact(call.length > ACTIVITY_CALL_CHARS ? `${call.slice(0, ACTIVITY_CALL_CHARS)}…` : call), output: sample });
+    if (activity.calls.length > ACTIVITY_LIMIT)
+        activity.calls.splice(0, activity.calls.length - ACTIVITY_LIMIT);
+}
+/** A cause named as likely or as fact: the wording that makes a final reply worth judging. */
+const CAUSE_WORDING = /\b(?:probably|likely|presumably|perhaps|maybe|i suspect|suspect(?:ed)? (?:that|the|this|it)|seems? to|appears? to|the cause|root cause|caused by|due to|the reason|reasons? (?:is|are)|the (?:bug|issue|problem|error|failure|regression|alert|warning) (?:is|was|comes|lies)|introduced by|stems from|traces? (?:back )?to|must have been|someone (?:changed|deleted|renamed|broke|edited)|points? to)\b/i;
+/** A check handed to a person: wording that asks someone else to inspect what the agent could inspect. */
+const HAND_OFF_WORDING = /\b(?:ask (?:them|him|her|someone|the team|the user|whoever|the owner)|check with|confirm with|find out (?:from|whether|if)|have (?:them|someone|the team) (?:check|confirm|verify|look)|(?:could|can|would) you (?:check|confirm|verify|find out|look)|please (?:check|confirm|verify)|worth (?:checking|verifying|confirming)|not sure (?:who|whether|if))\b/i;
+/**
+ * The offline pre-filter: true when the final reply carries causal or hand-off wording, so a reply about results or
+ * next steps sends no request. Deliberately broad: a Jev answer still decides, and a missed ask loses a real catch.
+ */
+export function causePreFilter(text) {
+    return CAUSE_WORDING.test(text) || HAND_OFF_WORDING.test(text);
+}
+/** The sentence that carries the first causal or hand-off match, or undefined when none does. */
+function causeSentence(text) {
+    const causal = CAUSE_WORDING.exec(text);
+    const handOff = HAND_OFF_WORDING.exec(text);
+    const match = causal !== null && handOff !== null ? (causal.index <= handOff.index ? causal : handOff) : causal ?? handOff;
+    if (match === null)
+        return undefined;
+    const at = match.index;
+    let start = 0;
+    for (let index = at - 1; index >= 0; index--) {
+        const character = text[index];
+        if (character === "." || character === "!" || character === "?" || character === "\n") {
+            start = index + 1;
+            break;
+        }
+    }
+    let end = text.length;
+    for (let index = at; index < text.length; index++) {
+        const character = text[index];
+        if (character === "." || character === "!" || character === "?" || character === "\n") {
+            end = index + 1;
+            break;
+        }
+    }
+    return text.slice(start, end).trim();
+}
+export const causeQuestions = {
+    states_cause: noul("Does `final_message` state a cause, explanation, or diagnosis for a problem, as a likely cause or as a fact?", {
+        true: "Yes: it names why something happened or what is wrong, for example a component, a change, a condition, or an action by someone.",
+        false: "No: it only reports status or results, names remaining work, asks a question, or describes a plan.",
+    }),
+    hands_off: noul("Does `final_message` ask a person to check, confirm, or find out something that the agent could inspect with its own tools?", {
+        true: "Yes: it asks someone else, such as the user, a colleague, or another team, to verify or investigate a fact the agent could query, read, or run itself.",
+        false: "No: it asks only for a decision a person must make, reports what it checked, or states a cause.",
+    }),
+    checked: noul("Did `run` check the cause `final_message` states, with a tool result that directly tested it?", {
+        true: "Yes: a tool result inspected the stated cause or its effect, so the cause rests on evidence from the run.",
+        false: "No: no tool result in `run` inspected the stated cause; the reply only asserts it or asks someone else.",
+    }),
+};
+/** One choice question: which earlier cause is the same cause of the same problem, or `none`. */
+function earlierCauseQuestion(earlier) {
+    const criteria = {
+        none: "The cause in `final_message` is not the same cause of the same problem as any earlier cause, or no earlier cause applies.",
+    };
+    for (const cause of earlier)
+        criteria[cause.key] = `The cause in \`final_message\` is the same cause of the same problem as ${cause.key} (recorded ${cause.date}): ${cause.summary}`;
+    return choice("Which earlier cause, if any, is the same cause of the same problem as the cause in `final_message`?", criteria);
+}
+export function buildCauseRequest(task, finalMessage, activity, earlier = []) {
+    return {
+        state: {
+            task: task?.trim() ? (task.trim().length > 1500 ? `${task.trim().slice(0, 1500)}…` : task.trim()) : "(no user request recorded in this session)",
+            final_message: redact(finalMessage.length > 2000 ? `${finalMessage.slice(0, 2000)}…` : finalMessage),
+            run: {
+                tool_calls: activity.calls.map(call => ({ call: call.call, output: call.output || "(no output recorded)" })),
+            },
+            ...(earlier.length ? { earlier_causes: earlier.map(cause => ({ key: cause.key, date: cause.date, cause: cause.summary })) } : {}),
+        },
+        questions: earlier.length ? { ...causeQuestions, same_cause: earlierCauseQuestion(earlier) } : causeQuestions,
+    };
+}
+function clip(text, limit = 160) {
+    const flat = text.replace(/\s+/g, " ").trim();
+    return flat.length <= limit ? flat : `${flat.slice(0, limit)}…`;
+}
+function day(at) {
+    return new Date(at).toISOString().slice(0, 10);
+}
+/** The project's earlier unchecked causes inside the window, newest first, at most `EARLIER_LIMIT`, each with a key. */
+async function readEarlierCauses(options, since, now) {
+    const store = options.store;
+    const projectRoot = options.projectRoot;
+    if (store === undefined || projectRoot === undefined)
+        return [];
+    // A store that answers outside the window cannot escalate; the guard owns the 7-day rule.
+    const rows = await store.recall(projectRoot, since, EARLIER_LIMIT);
+    return rows
+        .filter(row => row.at >= since && row.at < now)
+        .sort((a, b) => b.at - a.at)
+        .slice(0, EARLIER_LIMIT)
+        .map((row, index) => ({ key: `c${index + 1}`, date: day(row.at), summary: row.summary, at: row.at }));
+}
+export async function evaluateCause(task, finalMessage, activity, options) {
+    const summary = redact(clip(causeSentence(finalMessage) ?? finalMessage, SUMMARY_CHARS));
+    if (!options.config.enabled)
+        return { unchecked: false, handsOff: false, summary, reasons: [] };
+    const now = options.now ?? Date.now();
+    const earlier = await readEarlierCauses(options, now - options.config.windowDays * 86_400_000, now);
+    const result = await ask(options.judge, buildCauseRequest(task, finalMessage, activity, earlier), { timeoutMs: options.timeoutMs, ...(options.signal ? { signal: options.signal } : {}) });
+    if (!result.ok)
+        return { unchecked: false, handsOff: false, summary, reasons: [], error: result.error, ...(result.errorCode ? { errorCode: result.errorCode } : {}) };
+    // The request type is assembled at runtime, so the answer shape is read loosely here: the repeat question is asked
+    // only when an earlier cause exists.
+    const answers = result.answers;
+    const judgment = {
+        statesCause: answers.states_cause.noul,
+        handsOff: answers.hands_off.noul,
+        checked: answers.checked.noul,
+        model: result.model,
+        elapsedMs: result.elapsedMs,
+    };
+    const states = Math.max(judgment.statesCause, judgment.handsOff) >= options.config.claimsCause;
+    const unchecked = states && judgment.checked < CHECKED_AT;
+    const handsOff = judgment.handsOff > judgment.statesCause;
+    // Escalate only when Jev says the reply repeats a cause it was shown, never on a shared label.
+    const matched = unchecked && earlier.length ? answers.same_cause?.choice : undefined;
+    const previous = matched === undefined || matched === "none" ? undefined : earlier.find(cause => cause.key === matched);
+    const reasons = [];
+    if (unchecked) {
+        const stated = handsOff
+            ? `hands a check to a person (${judgment.handsOff.toFixed(2)})`
+            : `states a cause (${judgment.statesCause.toFixed(2)})`;
+        reasons.push(`the final reply ${stated} and no tool result in the run checked it (checked ${judgment.checked.toFixed(2)})`);
+        if (previous !== undefined)
+            reasons.push(`the same unchecked cause was recorded on ${day(previous.at)}`);
+    }
+    if (unchecked && options.store !== undefined && options.projectRoot !== undefined) {
+        await options.store.record(options.projectRoot, { summary, at: now });
+    }
+    return { unchecked, handsOff, summary, reasons, judgment, ...(previous !== undefined ? { previous: { summary: previous.summary, at: previous.at } } : {}) };
+}
+/** The follow-up for the agent: check the cause with its own tools, or say plainly that it is unverified. */
+export function causeNudge(verdict) {
+    const base = "check it with your own tools (a query, a log, a file, or a command) and give the evidence, or say plainly that the cause is unverified and why you cannot check it";
+    const opening = verdict.handsOff
+        ? "the final reply asks a person to check something that the agent can check itself, and nothing in the run checked it"
+        : "the final reply states a cause that nothing in the run checked";
+    const repeat = verdict.previous === undefined ? "" : ` You gave the same unchecked cause on ${day(verdict.previous.at)}.`;
+    return `pi-warden: ${opening}.${repeat} ${base[0].toUpperCase()}${base.slice(1)}.`;
+}
+export function formatCause(verdict, template = DEFAULT_TEMPLATES.cause) {
+    return renderTemplate(template, causeTokens(verdict));
+}

package/dist/config.d.ts

@@ -157,6 +157,15 @@ export interface DoneGuardConfig {
     uiFiles: string[];
     visualTools: VisualToolsConfig;
 }
+export interface CauseGuardConfig {
+    enabled: boolean;
+    /** P(the final reply states a cause or hands a check to a person) at or above this is judged. */
+    claimsCause: number;
+    /** Also send the agent a follow-up asking it to check the cause. Triggers one more LLM turn. */
+    nudge: boolean;
+    /** Days an unchecked cause is remembered for the repeat steer. */
+    windowDays: number;
+}
 /** Tool calls that show the rendered UI. Matching is case-insensitive. */
 export interface VisualToolsConfig {
     /** Heads of a shell command segment: `agent-browser`, `npx playwright`. */
@@ -423,6 +432,7 @@ export interface WardenConfig {
     action: ActionGuardConfig;
     stuck: StuckGuardConfig;
     done: DoneGuardConfig;
+    cause: CauseGuardConfig;
     slop: SlopGuardConfig;
     security: SecurityConfig;
     rules: RulesConfig;
@@ -461,7 +471,7 @@ export interface WardenConfig {
 }
 export declare const PACKAGE_NAME = "pi-warden";
 /** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
-export declare const CONFIG_SCHEMA = 12;
+export declare const CONFIG_SCHEMA = 13;
 export declare const PROJECT_CONFIG_FILE = "pi-warden.json";
 export declare function defaultConfig(): WardenConfig;
 /** The user file is in the host's agent directory: `~/.pi/agent` on Pi, `~/.omp/agent` on oh-my-pi. `PI_CODING_AGENT_DIR` overrides it. */

package/dist/config.js

@@ -12,9 +12,12 @@ export const DEFAULT_UI_FILES = [
 ];
 export function defaultVisualTools() {
     return {
-        commands: ["agent-browser", "playwright", "npx playwright", "flutter test", "fvm flutter test", "idb", "xcrun simctl io", "chrome", "chromium", "google-chrome"],
-        commandWords: ["screenshot"],
-        tools: ["screenshot", "take_snapshot", "navigate"],
+        // A head names the command that shows the page: a page text snapshot, or a browser or device test run. A screenshot
+        // subcommand only writes a file (`agent-browser screenshot PATH`, `idb screenshot`, `chrome --headless --screenshot`),
+        // so it is not a head; the saved image counts once something reads it.
+        commands: ["agent-browser snapshot", "agent-browser get text", "playwright test", "npx playwright test", "flutter test", "fvm flutter test"],
+        commandWords: [],
+        tools: ["take_snapshot"],
         images: ["png", "jpg", "jpeg", "webp"],
     };
 }
@@ -24,7 +27,7 @@ export function isRecallTool(value) {
 }
 export const PACKAGE_NAME = "pi-warden";
 /** Bumped when WardenConfig gains a section; extension.ts checks it so a half-updated module graph is reported, not crashed on. */
-export const CONFIG_SCHEMA = 12;
+export const CONFIG_SCHEMA = 13;
 export const PROJECT_CONFIG_FILE = `${PACKAGE_NAME}.json`;
 export function defaultConfig() {
     return {
@@ -60,6 +63,7 @@ export function defaultConfig() {
         },
         stuck: { enabled: true, window: 12, minFailures: 3, cooldown: 3, sameStrategy: 0.7, churnThreshold: 5, nudge: true, repeatSteer: true, evidence: true, diffLimit: 3000, tailLimit: 1000 },
         done: { enabled: true, claimsDone: 0.7, nudge: true, uiProof: true, uiFiles: [...DEFAULT_UI_FILES], visualTools: defaultVisualTools() },
+        cause: { enabled: true, claimsCause: 0.7, nudge: true, windowDays: 7 },
         slop: { enabled: true, threshold: 0.7, prose: { enabled: true, audience: "technical", threshold: 0.7, trend: 2, minChars: 200 } },
         security: { enabled: true, threshold: 0.7, maskOutput: true },
         rules: { enabled: true, threshold: 0.7, softThreshold: 0, files: [], fallback: true, maxChars: 8000, exclude: [], skip: [], sensitivePaths: {} },
@@ -471,6 +475,16 @@ function applyDone(base, raw) {
         },
     };
 }
+function applyCause(base, raw) {
+    if (!isObject(raw))
+        return base;
+    return {
+        enabled: boolean(raw.enabled, base.enabled),
+        claimsCause: probability(raw.claimsCause, base.claimsCause),
+        nudge: boolean(raw.nudge, base.nudge),
+        windowDays: Math.max(1, positiveInteger(raw.windowDays, base.windowDays)),
+    };
+}
 function applyProse(base, raw) {
     if (!isObject(raw))
         return base;
@@ -523,6 +537,7 @@ function applyWidget(base, raw) {
         action: template(raw.action, base.action),
         stuck: template(raw.stuck, base.stuck),
         done: template(raw.done, base.done),
+        cause: template(raw.cause, base.cause),
         prose: template(raw.prose, base.prose),
         security: template(raw.security, base.security),
         context: template(raw.context, base.context),
@@ -553,6 +568,7 @@ function applyGuards(base, raw, timeoutMs, source, warnings) {
         action: applyAction(base.action, raw.action, timeoutMs, source, warnings),
         stuck: applyStuck(base.stuck, raw.stuck),
         done: applyDone(base.done, raw.done),
+        cause: applyCause(base.cause, raw.cause),
         slop: applySlop(base.slop, raw.slop),
         security: isObject(raw.security) ? {
             enabled: source === "project" ? projectSwitch("security.enabled", raw.security.enabled, base.security.enabled, warnings) : boolean(raw.security.enabled, base.security.enabled),

package/dist/done.d.ts

@@ -3,14 +3,17 @@ import type { DoneGuardConfig, VisualToolsConfig } from "./config.js";
 export type ToolOutcome = "read" | "mutation" | "check-pass" | "check-fail" | "unknown";
 /**
  * What a finished tool call contributes to the run's evidence. Only write/edit inside the project count as code changes: shell side effects
- * (deleting a temp dir, installing a package) are too varied to demand a test run for. Custom tools are unknown.
+ * (deleting a temp dir, installing a package) are too varied to demand a test run for. Custom tools are unknown. A shell command counts as a
+ * check only when a check runner starts one of its shell segments; a runner name in an argument (`grep -n jest package.json`) does not.
  */
 export declare function classifyToolResult(tool: string, input: Record<string, unknown>, failed: boolean, output?: string, cwd?: string): ToolOutcome;
+/** Why a run that names a check runner is not counted as a check (for one trace detail); undefined when it counts or names no runner. */
+export declare function checkSkipReason(tool: string, input: Record<string, unknown>, failed: boolean, output?: string, cwd?: string): string | undefined;
 /**
- * Recognise a test/type-check runner's own summary in tool output: node:test, jest/vitest, pytest, cargo, go test,
- * tsc. Returns the outcome the summary reports, or undefined when no runner summary is present.
+ * Recognise a runner's own summary in tool output. A failure marker anywhere in the tail wins over a passing one; the
+ * caller sees a pass only when no failure marker is present.
  */
-export declare function checkSummary(output: string): "pass" | "fail" | undefined;
+export declare function checkSummary(output: string, command?: string): "pass" | "fail" | undefined;
 export interface RunEvidence {
     mutations: number;
     checks: Array<{
@@ -22,14 +25,17 @@ export interface RunEvidence {
     unseenUi?: string;
 }
 export declare function emptyEvidence(): RunEvidence;
-export declare function recordOutcome(evidence: RunEvidence, outcome: ToolOutcome, input: Record<string, unknown>, tool?: string): void;
+export declare function recordOutcome(evidence: RunEvidence, outcome: ToolOutcome, input: Record<string, unknown>, tool?: string): string | undefined;
 /** A path matches when some glob matches it and no `!` glob does. */
 export declare function isUiFile(path: string, globs: readonly string[]): boolean;
 /**
- * Whether a successful tool call showed the rendered UI: a browser or device command, a screenshot, a browser MCP tool, or
- * reading an image. A test run proves the code runs; only this proves what the user will see.
+ * Whether a successful tool call showed the rendered UI to the agent: an image in the result, a page text snapshot, a browser or device test
+ * run, or reading an image file. A test run proves the code runs; only this proves what the user will see. A screenshot command that only
+ * writes a file shows nothing until something reads that file.
  */
-export declare function isVisualCheck(tool: string, input: Record<string, unknown>, failed: boolean, visual: VisualToolsConfig): boolean;
+export declare function isVisualCheck(tool: string, input: Record<string, unknown>, failed: boolean, visual: VisualToolsConfig, content?: ReadonlyArray<{
+    type: string;
+}>): boolean;
 /** Paths a successful call changed that match the UI globs: `write`/`edit` paths, plus files a shell command writes. */
 export declare function recordUi(evidence: RunEvidence, changed: readonly string[], visual: boolean, globs: readonly string[]): void;
 interface MessageLike {
@@ -102,7 +108,22 @@ export interface DoneOptions {
     signal?: AbortSignal | undefined;
 }
 export declare function evaluateDone(task: string | undefined, finalMessage: string, evidence: RunEvidence, options: DoneOptions): Promise<DoneVerdict>;
+export declare function localUrl(text: string): string | undefined;
+/**
+ * The project's own check command: the `check` then `test` script of its `package.json`, else the same Makefile targets. Only files in the
+ * project root are read; a project with neither keeps the generic nudge.
+ */
+export declare function projectCheckCommand(root: string): string | undefined;
+/** Session facts the nudge can name instead of a generic ask. */
+export interface NudgeHint {
+    /** The last check command that passed earlier in this session in this project. */
+    lastCheck?: string | undefined;
+    /** The project's own check command (`projectCheckCommand`). */
+    projectCheck?: string | undefined;
+    /** The last local URL a tool result printed in this session. */
+    localUrl?: string | undefined;
+}
 /** Follow-up for the agent: verify or say plainly that nothing was verified. */
-export declare function doneNudge(verdict: DoneVerdict): string;
+export declare function doneNudge(verdict: DoneVerdict, hint?: NudgeHint): string;
 export declare function formatDone(verdict: DoneVerdict, template?: string): string;
 export {};