pi-lens 4.3.0 → 4.4.0

package/dist/clients/agent-behavior-client.js

@@ -1,147 +0,0 @@
-/**
- * AgentBehaviorClient for pi-lens
- *
- * Tracks tool call sequences and flags anti-patterns in real-time:
- * - Blind writes: editing or writing without reading first (a same-session
- *   write/edit of the same path counts as file knowledge)
- * - Thrashing: repeated identical tool calls with no progress
- *
- * No external dependencies — purely tracks tool call history.
- */
-import { isMutatingToolName } from "./mutating-tool.js";
-import { normalizeMapKey } from "./path-utils.js";
-// --- Constants ---
-// #2423: mutating-tool membership comes from the seam
-// (`clients/mutating-tool.ts`), the single source of truth for the built-in
-// table. The hand-maintained set this replaced also carried a dead
-// `"multiedit"` entry that no host emits.
-//
-// Known gap, stated rather than hidden: this client is handed a tool NAME and a
-// path, never the event, so it cannot see a third-party mutating tool the way
-// the shape adapters can. Blind-write and thrash detection covers pi's
-// built-ins only.
-const READ_OPS = new Set(["read", "bash", "grep", "glob", "find", "rg"]);
-const BLIND_WRITE_WINDOW = 5; // Check last N tool calls for a read
-const THRASH_THRESHOLD = 3; // Flag after N consecutive identical tool+file pairs
-const THRASH_TIMEOUT_MS = 30_000; // Reset thrash counter if gap > 30s
-// --- Client ---
-export class AgentBehaviorClient {
-    toolHistory = [];
-    consecutiveCount = 0;
-    lastToolName = null;
-    lastToolFilePath = null;
-    lastToolTimestamp = 0;
-    // Per-file tracking
-    fileEditCount = new Map();
-    static FILE_EDIT_IDLE_MS = 30 * 60_000;
-    /**
-     * Record a tool call and return any warnings triggered.
-     * Called from tool_result handler.
-     */
-    recordToolCall(toolName, filePath) {
-        const warnings = [];
-        const now = Date.now();
-        // Track consecutive identical tool+file pairs (thrashing).
-        // Editing different files in sequence is normal agent behaviour — only flag
-        // when the same tool is called on the same file N times without making
-        // progress on anything else.
-        const normalizedPath = filePath ? normalizeMapKey(filePath) : null;
-        if (toolName === this.lastToolName &&
-            normalizedPath === this.lastToolFilePath &&
-            now - this.lastToolTimestamp < THRASH_TIMEOUT_MS) {
-            this.consecutiveCount++;
-        }
-        else {
-            this.consecutiveCount = 1;
-        }
-        this.lastToolName = toolName;
-        this.lastToolFilePath = normalizedPath;
-        this.lastToolTimestamp = now;
-        // Check for thrashing
-        if (this.consecutiveCount === THRASH_THRESHOLD) {
-            const fileLabel = filePath ? ` on \`${filePath}\`` : "";
-            warnings.push({
-                type: "thrashing",
-                message: `🔴 THRASHING — ${THRASH_THRESHOLD} consecutive \`${toolName}\`${fileLabel} calls with no progress. Consider fixing the root cause instead of re-running.`,
-                severity: "error",
-                details: {
-                    toolName,
-                    filePath,
-                    callCount: this.consecutiveCount,
-                },
-            });
-        }
-        // Check for blind writes
-        if (isMutatingToolName(toolName)) {
-            const recentWindow = this.toolHistory.slice(-BLIND_WRITE_WINDOW);
-            // A read in the window proves file knowledge; so does a same-session
-            // write/edit of THIS path — the agent authored the content, so the
-            // write-then-edit loop on a self-authored file is not a blind write.
-            const hasRecentRead = recentWindow.some((r) => READ_OPS.has(r.toolName) ||
-                (isMutatingToolName(r.toolName) &&
-                    r.filePath !== undefined &&
-                    normalizedPath !== null &&
-                    normalizeMapKey(r.filePath) === normalizedPath));
-            if (!hasRecentRead && recentWindow.length > 0) {
-                // Count how many writes in the window without reads
-                const writesWithoutRead = recentWindow.filter((r) => isMutatingToolName(r.toolName)).length;
-                if (writesWithoutRead >= 2) {
-                    warnings.push({
-                        type: "blind-write",
-                        message: `⚠ BLIND WRITE — editing \`${filePath ?? "file"}\` without reading in the last ${BLIND_WRITE_WINDOW} tool calls. Read the file first to avoid assumptions.`,
-                        severity: "warning",
-                        details: {
-                            filePath,
-                            windowSize: recentWindow.length,
-                        },
-                    });
-                }
-            }
-            // Track edits per file
-            if (filePath) {
-                const key = normalizeMapKey(filePath);
-                this.fileEditCount.set(key, {
-                    count: (this.fileEditCount.get(key)?.count ?? 0) + 1,
-                    lastUsedAt: now,
-                });
-                for (const [pathKey, entry] of this.fileEditCount) {
-                    if (now - entry.lastUsedAt > AgentBehaviorClient.FILE_EDIT_IDLE_MS) {
-                        this.fileEditCount.delete(pathKey);
-                    }
-                }
-            }
-        }
-        // Add to history (keep last 50 entries)
-        this.toolHistory.push({ toolName, filePath, timestamp: now });
-        if (this.toolHistory.length > 50) {
-            this.toolHistory = this.toolHistory.slice(-50);
-        }
-        return warnings;
-    }
-    /**
-     * Format warnings for LLM consumption.
-     */
-    formatWarnings(warnings) {
-        if (warnings.length === 0)
-            return "";
-        return warnings.map((w) => w.message).join("\n");
-    }
-    /**
-     * Get edit count for a file in this session.
-     */
-    getEditCount(filePath) {
-        return this.fileEditCount.get(normalizeMapKey(filePath))?.count ?? 0;
-    }
-    /**
-     * Reset state (e.g., on session start).
-     */
-    reset() {
-        this.toolHistory = [];
-        this.consecutiveCount = 0;
-        this.lastToolName = null;
-        this.lastToolTimestamp = 0;
-        this.fileEditCount.clear();
-    }
-}
-/** Process-wide behaviour history, independent of analyzer bootstrap residency. */
-export const agentBehaviorClient = new AgentBehaviorClient();

package/dist/clients/agent-nudge.js

@@ -1,325 +0,0 @@
-import { logLatency } from "./latency-logger.js";
-import { normalizeMapKey } from "./path-utils.js";
-const BUS_FILES_TOUCHED_EVENT = "pilens:files:touched";
-const MAX_NAMES_SHOWN = 5;
-// Module-level accumulator: one process/session, so a plain map keyed via
-// normalizeMapKey (house style — every map/set key in this module MUST go
-// through it; a hand-rolled replace() is the exact trap that cost two red CI
-// rounds on #458's reconcile tests, PR #491) is sufficient. Cleared ONLY
-// inside consumeAgentNudge() (i.e. only at actual injection into a `context`
-// call) — deliberately NOT tied to turn_start/agent_end/agent_settled, so
-// entries accumulated during run A's turn_end survive until run B's first
-// `context` call in the same session (the cross-run `git status` case).
-const _touched = new Map();
-// Count of bus-reported paths dropped by the relevance filter (file never
-// read/edited this session) since the last consume — drained alongside the
-// accumulator so the `agent_nudge` phase can report how much the filter
-// actually suppresses, which is the metric that validates (or indicts) the
-// "only nudge for files the session saw" rule.
-let _relevanceFilteredCount = 0;
-/** Test-only: clear accumulator state between test files/cases. */
-export function _resetAgentNudgeForTests() {
-    _touched.clear();
-    _relevanceFilteredCount = 0;
-    _enabledCache = undefined;
-}
-// --- Kill switch (lazy, memoized — house style per clients/quiet-window.ts) ---
-let _enabledCache;
-/** `PI_LENS_AGENT_NUDGE=0` disables accumulation and injection outright. */
-export function isAgentNudgeEnabled() {
-    if (_enabledCache === undefined) {
-        _enabledCache = process.env.PI_LENS_AGENT_NUDGE !== "0";
-    }
-    return _enabledCache;
-}
-function isValidPayload(data) {
-    if (!data || typeof data !== "object")
-        return false;
-    const p = data;
-    return (p.v === 1 &&
-        p.source === "pi-lens" &&
-        (p.reason === "autofix" || p.reason === "format") &&
-        Array.isArray(p.paths));
-}
-/**
- * Record a `pilens:files:touched` event into the accumulator, filtered to
- * files the session has actually read or edited (read-guard is the source of
- * truth — `getReadHistory`/`getEditHistory` both key internally via
- * `normalizeFilePath`, so either separator form on the incoming bus payload
- * or the guard's stored records resolves to the same record regardless of
- * which form was recorded first).
- */
-function recordTouchedEvent(payload, getReadGuard) {
-    const readGuard = getReadGuard();
-    if (!readGuard)
-        return;
-    for (const rawPath of payload.paths) {
-        const isRelevant = readGuard.getReadHistory(rawPath).length > 0 ||
-            readGuard.getEditHistory(rawPath).length > 0;
-        if (!isRelevant) {
-            _relevanceFilteredCount++;
-            continue;
-        }
-        const mapKey = normalizeMapKey(rawPath);
-        const existing = _touched.get(mapKey);
-        if (existing) {
-            existing.reasons.add(payload.reason);
-            // "local" is sticky — see AccumulatedFileOrigin doc. A file already
-            // recorded via the cross-process feed, now also reported by this
-            // session's own bus, upgrades to "local".
-            existing.origin = "local";
-            // #1464: a fresh touch invalidates any content already delivered for
-            // this path (the default deferred format at agent_end, a cascade
-            // autofix) — those bytes no longer describe the file.
-            existing.contentDelivered = false;
-        }
-        else {
-            _touched.set(mapKey, {
-                displayPath: rawPath,
-                reasons: new Set([payload.reason]),
-                origin: "local",
-                contentDelivered: false,
-            });
-        }
-    }
-}
-/**
- * Feed entries read from the cross-process `recent-touches.json` record
- * (#492, clients/recent-touches.ts) into the SAME accumulator #485 uses for
- * in-process bus events — one accumulator, one `consumeAgentNudge` call, one
- * batched context message regardless of how many files came from which
- * channel.
- *
- * Relevance filtering differs by call site (#492 point 6) and is therefore
- * the CALLER's responsibility, not this function's:
- *   - parent at turn_start: read-guard history FIRST (a parent usually has
- *     one), falling back to recency-only for files it hasn't read (a parent
- *     about to `git commit` needs attribution even for unread files);
- *   - child at session_start: recency + file-existence only (no read
- *     history exists yet this early).
- * `readCrossProcessTouchesForTurnStart` / `...ForSessionStart` in
- * recent-touches.ts already apply their own recency/existence/self-pid
- * filtering before entries reach here — this function does not re-derive
- * relevance, it only merges into the accumulator and marks provenance.
- *
- * Self-exclusion (an entry this process itself published never nudges
- * itself) and path+ts dedup across repeated reads of the record are both
- * handled upstream in recent-touches.ts (pid filter + last-consumed cursor),
- * so entries reaching this function are already the "new, foreign" set.
- */
-export function recordCrossProcessTouches(entries) {
-    if (!isAgentNudgeEnabled())
-        return;
-    for (const entry of entries) {
-        const mapKey = normalizeMapKey(entry.path);
-        const existing = _touched.get(mapKey);
-        if (existing) {
-            existing.reasons.add(entry.reason);
-            // "local" is sticky (see AccumulatedFileOrigin) — never downgrade an
-            // already-local entry back to cross-process.
-            // #1464: a foreign process touching this file invalidates whatever
-            // content this session's write path already delivered for it.
-            existing.contentDelivered = false;
-        }
-        else {
-            _touched.set(mapKey, {
-                displayPath: entry.path,
-                reasons: new Set([entry.reason]),
-                origin: "cross-process",
-                contentDelivered: false,
-            });
-        }
-    }
-}
-/**
- * Record the write path's authoritative-content attachment outcome for one
- * path (#1464).
- *
- * `attached` is the SAME boolean that drove the attachment in
- * `handleToolResult` (clients/runtime-tool-result.ts) — this module never
- * re-derives it from config, byte counts, or the aggregate budget. `true`
- * means the post-fix bytes went out in the write's own tool result and the
- * agent already holds them, so "re-read before editing" is noise. `false` is
- * the size cap and the per-command aggregate budget degrading an attachment
- * to a re-read warning: there the nudge is the whole signal, and calling this
- * with `false` re-arms a path an earlier per-file decision had suppressed
- * (the bash multi-file case, where the outer budget loop overrides the inner
- * per-file "attached").
- *
- * Marks an EXISTING accumulator entry only. `publishFilesTouched` fires
- * synchronously inside the `runPipeline` call this decision belongs to (pi's
- * event bus is a plain `EventEmitter`), so the entry is already there for any
- * path the relevance filter admitted; a path with no entry has nothing to
- * suppress. Deferred-edit autofix at `agent_end` never reaches here — it
- * attaches nothing, so it keeps nudging.
- */
-export function noteAuthoritativeContentAttachment(filePath, attached) {
-    const entry = _touched.get(normalizeMapKey(filePath));
-    if (entry)
-        entry.contentDelivered = attached;
-}
-/**
- * Subscribe to `pilens:files:touched` on pi's shared event bus. Called once
- * at extension factory time from index.ts, mirroring `wireBusEmitter`'s
- * placement (clients/bus-publish.ts). No-ops silently when `pi.events` or
- * `.on` is unavailable (older pi host) — never throws.
- */
-export function wireAgentNudgeSubscriber(args) {
-    const { events, getReadGuard, dbg } = args;
-    if (!events?.on)
-        return;
-    try {
-        events.on(BUS_FILES_TOUCHED_EVENT, (data) => {
-            if (!isAgentNudgeEnabled())
-                return;
-            if (!isValidPayload(data))
-                return;
-            try {
-                recordTouchedEvent(data, getReadGuard);
-            }
-            catch (err) {
-                dbg?.(`agent-nudge: failed to record touched event: ${err}`);
-            }
-        });
-    }
-    catch (err) {
-        dbg?.(`agent-nudge: subscribe failed (older pi host?): ${err}`);
-    }
-}
-/**
- * Consume the accumulated touched-file set and produce (at most) one context
- * message, e.g.:
- *   "pi-lens: 2 file(s) were autoformatted after your last turn: a.ts, b.ts —
- *    working-tree changes to these are expected; re-read before editing."
- * The provenance framing ("pi-lens ... expected") matters: the primary pain
- * case is an agent running `git status` (often at the START of a brand-new
- * run/session, not just mid-run) and burning turns investigating diffs it
- * did not knowingly make. Naming pi-lens as the source lets the agent act
- * (re-read, proceed) instead of investigating.
- *
- * #492: attribution is three-way by the batch's origin mix (see
- * AccumulatedFileOrigin) — still ONE message total (never split local vs.
- * cross-process into two separate injections; the agent gets one coherent
- * picture of everything unexplained in the working tree), but the wording
- * must never assign a LOCAL file to another instance:
- *   - all local         → "after your last turn" (the original #485 wording,
- *                         unchanged — verified by the pre-existing #485
- *                         tests);
- *   - all cross-process → "by an automatic run outside your turn";
- *   - mixed             → "after your last turn (N of them by an automatic
- *                         run outside it)" — the base framing stays local
- *                         and the cross-process portion is counted out
- *                         precisely, so no local file is ever misattributed.
- *
- * The cross-process wording names the ACTION, not the process identity. It
- * used to read "by another pi-lens instance (e.g. a subagent's)", which sent
- * agents investigating what other instance was running — the exact behavior
- * this nudge exists to prevent. Which process formatted the file is an
- * implementation detail the reading agent cannot act on; that it was an
- * automatic run outside their turn is the whole actionable content. The
- * origin split stays exact in the telemetry for human debugging.
- *
- * Clears the accumulator ONLY here, on actual injection — never on
- * agent_end/agent_settled/turn_start. Files formatted at the last turn_end of
- * a PREVIOUS run must still nudge at the first turn of the NEXT run in the
- * same session: this function is invoked from the `context` extension event
- * (index.ts), which fires before every provider/LLM call — including the
- * very first call of a fresh `agent_start` — so the accumulator surviving
- * across run boundaries is exactly what makes that cross-run delivery work.
- * Empty accumulator ⇒ returns undefined ⇒ zero bytes injected.
- *
- * #1464: paths whose post-fix content the write path already attached to its
- * OWN tool result are dropped from the batch here (see
- * `noteAuthoritativeContentAttachment`) — the agent holds those bytes, so
- * "re-read before editing" would spend context to re-fetch what it has. A
- * batch that is ENTIRELY such paths injects nothing.
- */
-export function consumeAgentNudge(dbg) {
-    const drained = Array.from(_touched.values());
-    _touched.clear();
-    const filesFiltered = _relevanceFilteredCount;
-    _relevanceFilteredCount = 0;
-    if (!isAgentNudgeEnabled())
-        return undefined;
-    if (drained.length === 0)
-        return undefined;
-    try {
-        // #1464: a write whose post-fix bytes were attached to its own tool
-        // result already told the agent everything this nudge would. Drop those
-        // paths from the message but keep counting them, so over-suppression is
-        // visible in telemetry instead of only in the absence of complaints.
-        const entries = drained.filter((e) => !e.contentDelivered);
-        const filesContentDelivered = drained.length - entries.length;
-        const filesTotal = entries.length;
-        const shown = entries.slice(0, MAX_NAMES_SHOWN);
-        const remaining = filesTotal - shown.length;
-        // Determine a single verb covering every reason seen across all
-        // accumulated files (not just the shown subset) — most turns will have
-        // a single uniform reason, so keep that common case terse; a mix of
-        // autofix + format across the batch falls back to a combined verb.
-        const allReasons = new Set();
-        for (const e of entries) {
-            for (const r of e.reasons)
-                allReasons.add(r);
-        }
-        const verbLabel = allReasons.size > 1
-            ? "autofixed/reformatted"
-            : allReasons.has("format")
-                ? "reformatted"
-                : "autofixed";
-        const names = shown.map((e) => e.displayPath);
-        const nameList = remaining > 0
-            ? `${names.join(", ")}, and ${remaining} more`
-            : names.join(", ");
-        const crossProcessCount = entries.filter((e) => e.origin === "cross-process").length;
-        const localCount = filesTotal - crossProcessCount;
-        logLatency({
-            type: "phase",
-            filePath: "<pi-lens>",
-            phase: "agent_nudge",
-            durationMs: 0,
-            metadata: {
-                filesTotal,
-                filesShown: shown.length,
-                // Relevance-filter drops since the last consume (files the session
-                // never read/edited) — NOT the display overflow, which is
-                // filesTotal - filesShown.
-                filesFiltered,
-                // #1464: drops because the write's own tool result already carried
-                // the post-fix bytes. A third, distinct count: these paths passed
-                // the relevance filter and were accumulated, then suppressed here.
-                filesContentDelivered,
-                reasonMix: Array.from(allReasons),
-                // #492: origin mix so cross-process pickup rate is observable
-                // alongside the existing relevance-filter metric.
-                originLocal: localCount,
-                originCrossProcess: crossProcessCount,
-            },
-        });
-        // Everything drained was delivered in a write's own tool result — the
-        // row above records that it happened, and zero bytes get injected.
-        if (filesTotal === 0)
-            return undefined;
-        // Three-way attribution (see the function doc): never assign a local
-        // file to another instance — a mixed batch keeps the local base framing
-        // and calls out the cross-process portion by exact count.
-        const attribution = localCount === 0
-            ? "by an automatic run outside your turn"
-            : crossProcessCount === 0
-                ? "after your last turn"
-                : `after your last turn (${crossProcessCount} of them by an automatic run outside it)`;
-        const message = `pi-lens: ${filesTotal} file(s) were ${verbLabel} ${attribution}: ${nameList} — working-tree changes to these are expected; re-read before editing.`;
-        return {
-            messages: [
-                {
-                    role: "user",
-                    content: `[pi-lens automated context — not a user request] ${message}`,
-                },
-            ],
-        };
-    }
-    catch (err) {
-        dbg?.(`agent-nudge: consume failed: ${err}`);
-        return undefined;
-    }
-}

package/dist/clients/analysed-root.js

@@ -1 +0,0 @@
-export {};