pi-warden 0.40.2 → 0.48.1

package/dist/guard.d.ts

@@ -1,5 +1,7 @@
+import type { Stats } from "node:fs";
 import type { IntegrationErrorCode, Judge, Questions } from "pi-typesafe";
-import type { ActionGuardConfig, ArmingRule, CommandRule, PathRule, RulesConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
+import type { ActionGuardConfig, ArmingRule, CommandRule, LargeOutputConfig, PathRule, RulesConfig, SecurityConfig, SlopGuardConfig } from "./config.js";
+import type { TaskSpine } from "./shape.js";
 import type { RulesSourceConfig } from "./rules.js";
 export type Level = "allow" | "warn" | "confirm" | "deny";
 export type Severity = "destructive" | "risky" | "sensitive" | "deny";
@@ -63,6 +65,8 @@ export interface ActionInput {
     task?: string | undefined;
     /** Prior conversation clarifies scope, but never grants approval for a held action. */
     context?: readonly TaskMessage[] | undefined;
+    /** The task spine: the thread's goal and earlier user turns, so follow-ups are judged with the goal they belong to. Scope context only; it never authorizes. */
+    spine?: TaskSpine | undefined;
     /** The agent's own words in the message that makes this call (or its latest text under this prompt). Explains the step; never authorizes it. */
     plan?: string | undefined;
 }
@@ -109,6 +113,8 @@ export interface Judgment {
     visible?: number;
     /** P(action is safe to proceed without asking). Inverted: low = hold. */
     shouldProceed?: number;
+    /** P(the command prints far more than the agent needs); bash only, never holds. */
+    largeOutput?: number;
     model: string;
     elapsedMs: number;
 }
@@ -156,6 +162,8 @@ export interface Verdict {
     offTaskTraceOnly?: boolean;
     /** Index of the trace-only off-task diagnostic; later reasons append, and any prepend must adjust this index. */
     offTaskTraceOnlyReasonIndex?: number;
+    /** Command family of a bash call at or above the large-output threshold; the agent is steered once per family per session. */
+    largeOutputFamily?: string;
     /** Answers to the caller's own `questions`: P(yes) for a noul, the picked option for a choice, the level for a score. */
     extra?: Record<string, number | string>;
     /** Safe TypeSafe error message when the judge could not answer. */
@@ -170,6 +178,8 @@ export interface EvaluateOptions {
     signal?: AbortSignal | undefined;
     /** Adds quality questions for write/edit content to the same request. */
     slop?: SlopGuardConfig | undefined;
+    /** Adds the large-output question to a bash request. */
+    largeOutput?: LargeOutputConfig | undefined;
     security?: SecurityConfig | undefined;
     /**
      * The rules guard's switch. The rules the active config resolves ride every judged action request, so
@@ -187,6 +197,13 @@ export interface EvaluateOptions {
      * How a candidate question is measured on recorded sessions before it earns an acting rule (scripts/calibrate-action.mjs).
      */
     questions?: Questions | undefined;
+    /** Real paths the agent created under the temp directory in this session (`PatternOptions.scratch`). */
+    scratch?: ScratchRecords | undefined;
+    /**
+     * Real paths of host directories (`hostPaths()`). A write or edit in one is not held by the outside-project rule;
+     * every other check still applies.
+     */
+    hostPaths?: readonly string[] | undefined;
 }
 export declare const higher: (a: Level, b: Level) => Level;
 interface Rule {
@@ -196,6 +213,16 @@ interface Rule {
     test: RegExp;
 }
 export declare const SHELL_RULES: Rule[];
+/**
+ * The command family the large-output steer is remembered by: the head of the first segment that is not a `cd`, plus the
+ * subcommand for tools that have one (`git log`, `npm test`, `npm run build`). Undefined when no head can be read.
+ */
+export declare function commandFamily(command: string): string | undefined;
+/**
+ * Whether a shell command has a segment whose effect is visible outside the working tree, decided in code before any
+ * request. Quoted data such as a commit message is blanked first, so a message that mentions `git push` is not a push.
+ */
+export declare function isVisibleCommand(command: string): boolean;
 export interface ScannedCommand {
     /** The command with data text blanked; what the pattern rules read. */
     text: string;
@@ -207,12 +234,82 @@ export interface ScannedCommand {
  * (`python3 - <<EOF`) are kept when the script calls out to a shell or process API.
  */
 export declare function stripDataText(command: string): ScannedCommand;
+/**
+ * Whether the exemption applies on this platform. It rests on birth time being a real creation time: macOS and Windows
+ * report one; Linux without `statx` reports ctime, which `mv` updates, so moved-in content would pass the tree walk.
+ * Elsewhere nothing is recorded and a recursive rm is classified as if no scratch existed.
+ */
+export declare function scratchPlatform(platform?: NodeJS.Platform): boolean;
+/** What a recorded path was when it was created. A path whose current identity differs was replaced and is not scratch. */
+export interface ScratchIdentity {
+    dev: number;
+    ino: number;
+    birthtimeMs: number;
+}
+/** Real paths the agent created under the temp directory in this session, with the identity each had when recorded. */
+export type ScratchRecords = ReadonlyMap<string, ScratchIdentity>;
+/** The identity of a path itself (a symlink is not followed); undefined when it does not exist. */
+export declare function scratchIdentity(path: string): ScratchIdentity | undefined;
+/** Drops records whose path is gone or now names a different file, so a later file at the same path is not scratch. */
+export declare function pruneScratch(records: Map<string, ScratchIdentity>): void;
+/** Real paths of the temp roots that exist: `os.tmpdir()`, `$TMPDIR`, `/tmp`, `/private/tmp`. */
+export declare function tempRoots(): string[];
+/**
+ * The real path of an absolute path: the realpath of its deepest existing ancestor plus the missing rest. Undefined when
+ * a component exists but cannot be resolved (a dangling symlink, a loop, no permission).
+ */
+export declare function realTarget(path: string): string | undefined;
+/**
+ * Host paths: directories outside the project where the host lets its agent write, from `PI_WARDEN_HOST_PATHS` only (a
+ * `:`-separated list). Relative entries, empty entries, and a filesystem root are ignored. Each entry is kept as its real
+ * path, so a target is compared after `..` and symlinks are resolved on both sides.
+ */
+export declare const HOST_PATHS_ENV = "PI_WARDEN_HOST_PATHS";
+export declare function hostPaths(env?: NodeJS.ProcessEnv): string[];
+/** The temp root a real path lies strictly under; a temp root itself has none. */
+export declare function tempRootOf(real: string, roots?: string[]): string | undefined;
+/** How much of the target trees one rm segment may walk: entries seen, and the clock time it must finish by. */
+export interface ScratchBudget {
+    entries: number;
+    deadline: number;
+}
+/**
+ * True when every entry of the tree at `path`, the root included, has a birth time at or after `born`. Symlinks are
+ * checked as links and never followed. False when the root is missing, an entry has no birth time or cannot be read,
+ * or the walk runs past its budget: content moved in from elsewhere keeps its older birth time and must not pass.
+ */
+export declare function bornAfter(path: string, born: number, budget?: ScratchBudget): boolean;
+/**
+ * Real paths under a temp root that this call may create and that do not exist yet: `mkdir` targets of a shell command,
+ * or a written file. Each path and its missing ancestors below the temp root are listed. Taken before the call runs, so
+ * a directory that already existed is never recorded as created.
+ */
+export declare function scratchCandidates(tool: string, input: Record<string, unknown>, cwd: string, platform?: NodeJS.Platform): string[];
+/**
+ * Real paths the call created, read after it ran, each with its identity. A candidate from `scratchCandidates` counts
+ * when it now exists as itself (not through a symlink). For a shell command, absolute temp paths printed in its output
+ * also count, bounded: the first 20 such paths only, each must exist under a temp root as a real directory or file, and
+ * its birth time must fall in a later millisecond than `started` (`Date.now()` when the call began). Where the file
+ * system reports no birth time, a printed path counts only from a command that does nothing but run `mktemp` and print
+ * what it made (`mktempOnly`). `birthtime` reads a file's birth time in milliseconds, 0 when the file system has none.
+ * Nothing is recorded where `scratchPlatform` is false.
+ */
+export declare function createdScratch(tool: string, input: Record<string, unknown>, output: string, started: number, candidates: readonly string[], birthtime?: (stats: Stats) => number, platform?: NodeJS.Platform): Map<string, ScratchIdentity>;
+/**
+ * How many paths a command that only makes temp files may print: each segment is a bare `mktemp`, an assignment
+ * `name=$(mktemp …)`, or an `echo` of names assigned that way. 0 for any other command.
+ */
+export declare function mktempOnly(command: string): number;
 /** Compiled user rules and exempt ids; passed from the config so matchPatterns stays pure. */
 export interface PatternOptions {
     commandRules?: readonly CommandRule[];
     commandDenyRules?: readonly CommandRule[];
     exemptRules?: readonly string[];
     pathRules?: readonly PathRule[];
+    /** Real paths the agent created under the temp directory in this session; a recursive rm of only these is not destructive. */
+    scratch?: ScratchRecords | undefined;
+    /** The platform `scratchPlatform` decides for; the running one when omitted. */
+    platform?: NodeJS.Platform | undefined;
 }
 /** Every id exemptRules can legitimately name: the built-in shell rules, the rm-classifier's derived ids, and the
  * sensitive-path id. Unknown ids (a typo, or a rule that never existed) are inert; this list lets the surface be
@@ -262,6 +359,10 @@ export declare const questions: {
 export declare const visibleQuestion: {
     visible: import("pi-typesafe").NoulQuestion;
 };
+/** Bash only. Prevention before the call; the context saver still compresses whatever does print. Steers, never holds. */
+export declare const largeOutputQuestion: {
+    large_output: import("pi-typesafe").NoulQuestion;
+};
 /** Asked only when the agent said something before the call; an empty plan cannot be contradicted. */
 export declare const intentQuestion: {
     intent_mismatch: import("pi-typesafe").NoulQuestion;
@@ -320,6 +421,8 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
     rulesSource?: string | undefined;
     violations?: readonly Violation[] | undefined;
     floorHits?: string;
+    spine?: TaskSpine | undefined;
+    largeOutput?: boolean;
 }): {
     state: {
         floor_hits?: string;
@@ -332,6 +435,10 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
             path?: string;
         }[];
         plan?: string;
+        spine?: {
+            goal: string;
+            task_history: string[];
+        };
         task: string;
         action: Record<string, string | number | boolean>;
         context: {
@@ -348,6 +455,7 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
         slop_comments?: import("pi-typesafe").NoulQuestion;
         slop_dead?: import("pi-typesafe").NoulQuestion;
         slop_hedging?: import("pi-typesafe").NoulQuestion;
+        large_output?: import("pi-typesafe").NoulQuestion;
         intent_mismatch?: import("pi-typesafe").NoulQuestion;
         visible?: import("pi-typesafe").NoulQuestion;
         irreversible: import("pi-typesafe").NoulQuestion;
@@ -371,6 +479,7 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
         slop_comments?: import("pi-typesafe").NoulQuestion;
         slop_dead?: import("pi-typesafe").NoulQuestion;
         slop_hedging?: import("pi-typesafe").NoulQuestion;
+        large_output?: import("pi-typesafe").NoulQuestion;
         intent_mismatch?: import("pi-typesafe").NoulQuestion;
         visible?: import("pi-typesafe").NoulQuestion;
         irreversible: import("pi-typesafe").NoulQuestion;
@@ -390,6 +499,7 @@ export declare function buildRequest(summary: ActionSummary, task: string | unde
         slop_comments?: import("pi-typesafe").NoulQuestion;
         slop_dead?: import("pi-typesafe").NoulQuestion;
         slop_hedging?: import("pi-typesafe").NoulQuestion;
+        large_output?: import("pi-typesafe").NoulQuestion;
         intent_mismatch?: import("pi-typesafe").NoulQuestion;
         visible?: import("pi-typesafe").NoulQuestion;
         irreversible: import("pi-typesafe").NoulQuestion;
@@ -414,6 +524,10 @@ export declare function intentSteer(verdict: Verdict): string;
 export declare function shouldProceedMessage(verdict: Verdict): string;
 /** What the agent reads after an unrelated change ran: the request it drifted from, the two acceptable moves, one line. */
 export declare function offTaskSteer(verdict: Verdict): string;
+/** What the agent reads the first time a command family is judged noisy: the family and one concrete way to print less. */
+export declare function largeOutputSteer(verdict: Verdict): string;
+/** The large-output steer for this verdict, once per command family per session; `steered` is the session's memory. */
+export declare function largeOutputNotice(verdict: Verdict, steered: Set<string>): string | undefined;
 /** Offline stand-in for the approval question when TypeSafe is not available. */
 export declare function textApproves(task: string | undefined): boolean;
 /**