@herbertgao/pi-extensions 2026.8.4 → 2026.8.5

package/node_modules/pi-lens/dist/clients/project-trust.js

@@ -0,0 +1,181 @@
+/**
+ * Host project-trust gate (#1334 S5).
+ *
+ * pi decides project trust itself: an extension may *answer* the question by
+ * registering `pi.on("project_trust", handler)` (returning
+ * `{ trusted: "yes" | "no" | "undecided" }`), but every other extension simply
+ * *consumes* the outcome through `ExtensionContext.isProjectTrusted()`. pi-lens
+ * is a consumer — it must never register the handler and answer the trust
+ * question on the user's behalf.
+ *
+ * Verified against the pinned host types
+ * (`@earendil-works/pi-coding-agent/dist/core/extensions/types.d.ts`):
+ *   - `ExtensionContext.isProjectTrusted(): boolean`  (line 234)
+ *   - `ProjectTrustEventDecision = "yes" | "no" | "undecided"`  (line 390)
+ *
+ * Note the asymmetry: the *event* has a three-valued decision, but the *ctx*
+ * accessor collapses it to a boolean. So the only distinctions pi-lens can make
+ * are "host says trusted", "host says NOT trusted", and "host gave no signal at
+ * all" (older hosts with no `isProjectTrusted` on the ctx).
+ *
+ * Policy:
+ *   - `untrusted` — the host said no or its accessor failed. Block every
+ *     install/materialization path (including npx and grammar WASM downloads)
+ *     and LSP child process spawn. Discovery and cached/in-process analysis
+ *     continue; a missing grammar follows its unavailable path.
+ *   - `trusted` / `unknown` — current behavior, unchanged. Fail-open is
+ *     deliberate ONLY for `unknown`: a host that never exposed the accessor
+ *     never had a trust decision to honor, and degrading it would break every
+ *     older pi.
+ *
+ * Process-wide singleton on purpose: `ensureTool()` and the LSP service sit
+ * many layers below any `ctx`, and threading trust through every call site
+ * would be a far larger and more fragile change than a single latched state
+ * refreshed on each `session_start` and `turn_start`.
+ */
+import { logExtension } from "./extension-log.js";
+import { recordDegradation } from "./degradation-ledger.js";
+let trustState = "unknown";
+const installRefusalWarnings = new Set();
+// Bounded (#1363 review): dynamic contexts (per-formatter/per-server strings)
+// must not grow without limit across a long untrusted session. Clearing on
+// overflow trades an occasional repeat warning for bounded memory.
+const INSTALL_REFUSAL_WARNING_CAP = 200;
+// Monotonic transition counter (#1363 review): consumers needing
+// clear-on-transition semantics compare this lazily at use time instead of
+// registering callbacks -- a per-instance listener with no teardown path
+// strongly retains every instance ever constructed.
+let trustGeneration = 0;
+export function getProjectTrustGeneration() {
+    return trustGeneration;
+}
+function latchProjectTrustState(next) {
+    if (next === trustState)
+        return;
+    trustState = next;
+    installRefusalWarnings.clear();
+    trustGeneration += 1;
+}
+/**
+ * Feature-detected read of the host trust decision off an event ctx.
+ *
+ * Returns `"unknown"` when the host predates the accessor, when the accessor
+ * throws, or when it returns a non-boolean — never guesses "untrusted" from a
+ * missing surface, because that would silently disable pi-lens on every older
+ * host.
+ */
+export function readProjectTrustFromContext(ctx) {
+    try {
+        const accessor = ctx
+            ?.isProjectTrusted;
+        if (typeof accessor !== "function")
+            return "unknown";
+        const trusted = accessor.call(ctx);
+        if (typeof trusted !== "boolean")
+            return "unknown";
+        return trusted ? "trusted" : "untrusted";
+    }
+    catch (accessorErr) {
+        // The accessor exists, so this is not the absent older-host signal. If it
+        // fails, executable content must remain gated until a later adoption works.
+        // Log it (#1350 delta review): a host whose accessor throws on every call
+        // permanently gates installs/LSP, and without this line the only trace is
+        // indirect refusal logs.
+        logExtension({
+            subsystem: "project-trust",
+            level: "warn",
+            message: "isProjectTrusted() threw -- latching untrusted (fail-closed)",
+            metadata: { error: String(accessorErr) },
+        });
+        return "untrusted";
+    }
+}
+/** Latch a trust state directly (tests, and the ctx adoption path below). */
+export function setProjectTrustState(next) {
+    const previous = trustState;
+    latchProjectTrustState(next);
+    if (previous !== next) {
+        logExtension({
+            subsystem: "project-trust",
+            level: "debug",
+            message: `project trust state transitioned: ${previous} -> ${next}`,
+            metadata: { previous, next },
+        });
+    }
+}
+/**
+ * Read the host decision off `ctx` and latch it. Called from `session_start`,
+ * which fires again on fork/reload/resume — a re-read per session start is
+ * exactly right, since the cwd (and therefore the trust decision) can change.
+ */
+export function adoptProjectTrustFromContext(ctx) {
+    const next = readProjectTrustFromContext(ctx);
+    const previous = trustState;
+    latchProjectTrustState(next);
+    if (previous !== next) {
+        logExtension({
+            subsystem: "project-trust",
+            level: "debug",
+            message: `project trust state transitioned: ${previous} -> ${next}`,
+            metadata: { previous, next },
+        });
+    }
+    return next;
+}
+/** Adopt through the canonical host capability boundary. */
+export function adoptProjectTrustFromPorts(ports) {
+    const next = ports.trust.isProjectTrusted();
+    setProjectTrustState(next);
+    return next;
+}
+export function getProjectTrustState() {
+    return trustState;
+}
+/** Test/teardown-only: back to the fail-open default. */
+export function resetProjectTrust() {
+    latchProjectTrustState("unknown");
+    installRefusalWarnings.clear();
+}
+/**
+ * False only when the host actively denied trust. Gates tool auto-install
+ * (download + execute), never plain discovery of an already-present binary.
+ */
+export function isToolInstallAllowedByTrust() {
+    return trustState !== "untrusted";
+}
+/** Central gate for operations that may download or install executable content. */
+export function assertInstallAllowed(context) {
+    if (isToolInstallAllowedByTrust())
+        return true;
+    recordDegradation({
+        kind: "trust-refusal",
+        subject: context,
+        reason: projectTrustDenialReason() ?? "project trust denied",
+    });
+    if (!installRefusalWarnings.has(context)) {
+        if (installRefusalWarnings.size >= INSTALL_REFUSAL_WARNING_CAP) {
+            installRefusalWarnings.clear();
+        }
+        installRefusalWarnings.add(context);
+        logExtension({
+            subsystem: "project-trust",
+            level: "warn",
+            message: `install/materialization blocked: ${context}`,
+            metadata: { context, trustState },
+        });
+    }
+    return false;
+}
+/**
+ * False only when the host actively denied trust. Gates LSP server child
+ * process spawns.
+ */
+export function isLspSpawnAllowedByTrust() {
+    return trustState !== "untrusted";
+}
+/** Human/log-readable reason, or undefined when nothing is being blocked. */
+export function projectTrustDenialReason() {
+    return trustState === "untrusted"
+        ? "project is not trusted (host isProjectTrusted() === false)"
+        : undefined;
+}

package/node_modules/pi-lens/dist/clients/quiet-window.js

@@ -185,10 +185,24 @@ const HEARTBEAT_SAMPLE_TIMEOUT_MS = 2000;
  *  a timeout resolves to `{}` (same "leave everything untouched" semantics as
  *  any other sampling failure — see the module docstring below). */
 async function buildHeartbeatResourcePatchBounded() {
-    return Promise.race([
-        buildHeartbeatResourcePatch(),
-        new Promise((resolve) => setTimeout(() => resolve({}), HEARTBEAT_SAMPLE_TIMEOUT_MS)),
-    ]);
+    // #1097: clear the timeout once the race settles. An uncleared, REF'D
+    // setTimeout would keep the event loop alive for the full
+    // HEARTBEAT_SAMPLE_TIMEOUT_MS after `agent_settled` fires the quiet window —
+    // a same-class sibling of the LSP client-wait leak: harmless in a long-lived
+    // session, but a keep-alive tail in a one-shot `pi --print` process.
+    let timer;
+    try {
+        return await Promise.race([
+            buildHeartbeatResourcePatch(),
+            new Promise((resolve) => {
+                timer = setTimeout(() => resolve({}), HEARTBEAT_SAMPLE_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
 }
 /**
  * #620: sample this process's host CPU% plus every currently-recorded LSP

package/node_modules/pi-lens/dist/clients/read-bridge.js

@@ -0,0 +1,147 @@
+/**
+ * Generic read-recording bridge for pi-lens.
+ *
+ * ## Trust model — explicitly advisory
+ *
+ * This bridge is an **advisory, trust-based protocol** for same-process Pi
+ * extensions. Any code sharing the same Node.js process already has full
+ * access to pi-lens's internal state, so the bridge cannot and does not
+ * provide a meaningful security boundary. What it *does* provide is:
+ *
+ * - A stable API surface so extensions do not need to import pi-lens
+ *   internals directly.
+ * - A single place for flag/scope checks (no-read-guard, ignored paths).
+ * - Basic defensive validation to catch integration bugs early (malformed
+ *   payloads).
+ *
+ * Mounts a `ReadBridge` object at `globalThis[READ_BRIDGE_KEY]` that any
+ * co-process extension can call to register a file read against pi-lens's
+ * read-guard — without either party needing to know about the other.
+ *
+ * Protocol (producer side)
+ * ────────────────────────
+ * A co-process Pi extension that performs file reads outside pi-lens's
+ * awareness (e.g. via a custom registered tool) can forward those reads so
+ * that a subsequent `edit` call on the same file is not blocked by the
+ * read-before-edit guard:
+ *
+ *   const bridge = (globalThis as any)[Symbol.for("pi-lens:read-bridge")];
+ *   bridge?.recordRead({
+ *     filePath,          // absolute path
+ *     requestedOffset,   // 1-indexed first line (default 1)
+ *     requestedLimit,    // line count, or undefined for the whole file
+ *     consumer,          // optional identifier, e.g. "my-extension" (appears in read-guard.log)
+ *   });
+ *
+ * Check `bridge.version` before calling to guard against future incompatible
+ * changes — a bridge whose version you don't recognise should be treated as
+ * unsupported.
+ *
+ * The timestamp is stamped by the bridge itself (Date.now()) to match
+ * exactly how the internal read path works.
+ *
+ * Calling before pi-lens is loaded, or when the guard is disabled via
+ * `PI_LENS_NO_READ_GUARD`, is safe — the bridge is absent or the call is
+ * silently dropped.
+ *
+ * Protocol (registration side, internal to pi-lens)
+ * ──────────────────────────────────────────────────
+ * `registerReadBridge` is called once from inside the extension factory
+ * (after `getLensFlag` is available) via the `_readBridgeRegistered`
+ * singleton guard so that factory re-activations in the same process do not
+ * mount a second bridge.
+ *
+ * The `isRecordable` predicate is re-evaluated on every `recordRead` call
+ * using the *current* activation's flag getter (stored in a module-level
+ * holder refreshed on every factory activation — same pattern as
+ * `_turnSummaryEmitCtx`), so flag changes take effect immediately.
+ */
+/** Stable Symbol key — identical across module reloads in the same process. */
+import { captureReadContentBinding, } from "./read-guard.js";
+export const READ_BRIDGE_KEY = Symbol.for("pi-lens:read-bridge");
+/**
+ * Validate a raw entry from an untrusted caller.
+ * Returns `true` when the entry is structurally sound and safe to forward.
+ *
+ * Validation is deliberately lightweight — this is an advisory protocol
+ * between same-process extensions (see the module-level trust-model note).
+ * The goal is to catch integration bugs (typo'd fields, bad numbers) early
+ * rather than to enforce a security boundary.
+ */
+function isValidEntry(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return false;
+    const e = entry;
+    // filePath must be a non-empty string (absolute paths are expected but
+    // we don't re-resolve here — `isRecordable` handles scope checks).
+    if (typeof e["filePath"] !== "string" || e["filePath"] === "")
+        return false;
+    // requestedOffset must be a finite integer ≥ 1.
+    const offset = e["requestedOffset"];
+    if (typeof offset !== "number" ||
+        !Number.isFinite(offset) ||
+        offset < 1 ||
+        !Number.isInteger(offset))
+        return false;
+    // requestedLimit must be undefined or a finite positive integer.
+    const limit = e["requestedLimit"];
+    if (limit !== undefined) {
+        if (typeof limit !== "number" ||
+            !Number.isFinite(limit) ||
+            limit < 1 ||
+            !Number.isInteger(limit))
+            return false;
+    }
+    return true;
+}
+/**
+ * Mount the bridge singleton. Call once from inside the extension factory
+ * (protected by the `_readBridgeRegistered` module-level flag).
+ * Subsequent calls are no-ops.
+ */
+export function registerReadBridge(deps) {
+    // Use `in` check so the frozen non-configurable property doesn't throw
+    // on a redundant defineProperty attempt.
+    if (READ_BRIDGE_KEY in globalThis)
+        return;
+    const bridge = Object.freeze({
+        version: 1,
+        recordRead(entry) {
+            // Validate the payload before doing anything else — this catches
+            // integration bugs in callers (malformed fields, bad numbers).
+            if (!isValidEntry(entry))
+                return;
+            if (!deps.isRecordable(entry.filePath))
+                return;
+            const offset = entry.requestedOffset;
+            // When no limit is given treat the whole file as covered — the guard
+            // clips to the actual line count via its own file-length probe.
+            const limit = entry.requestedLimit ?? Number.MAX_SAFE_INTEGER;
+            const contentBinding = captureReadContentBinding(entry.filePath, offset, limit);
+            deps.getReadGuard().recordRead({
+                filePath: entry.filePath,
+                requestedOffset: offset,
+                requestedLimit: limit,
+                effectiveOffset: offset,
+                effectiveLimit: limit,
+                expandedByLsp: false,
+                turnIndex: deps.getTurnIndex(),
+                writeIndex: deps.peekWriteIndex(),
+                // Stamp the timestamp here, matching exactly how the internal read
+                // path works (runtime-tool-call.ts always uses Date.now()).
+                timestamp: Date.now(),
+                // Provenance: identifies this record as bridge-sourced in read-guard.log.
+                source: `bridge:${entry.consumer ?? "unknown"}`,
+                ...(contentBinding !== undefined && { contentBinding }),
+            });
+        },
+    });
+    // Register as non-writable, non-configurable so no subsequent code can
+    // silently overwrite the bridge (first-wins is the contract).
+    Object.defineProperty(globalThis, READ_BRIDGE_KEY, {
+        value: bridge,
+        writable: false,
+        configurable: false,
+        enumerable: false,
+    });
+}

package/node_modules/pi-lens/dist/clients/read-guard-logger.js

@@ -17,6 +17,101 @@ const VERBOSE_READ_GUARD_LOG = process.env.PI_LENS_READ_GUARD_VERBOSE === "1" ||
 const LOG_ALLOWED_EDITS = process.env.PI_LENS_READ_GUARD_LOG_ALLOWS === "1";
 const SNAPSHOT_LOG_SETTING = (process.env.PI_LENS_READ_GUARD_LOG_SNAPSHOTS ?? "1").toLowerCase();
 const LOG_SNAPSHOT_VALIDATION = !["0", "false", "off"].includes(SNAPSHOT_LOG_SETTING);
+export const MAX_EDIT_BATCH_ITEMS = 100;
+let generatedCorrelationCounter = 0;
+function sanitizeCorrelationId(value) {
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    const sanitized = String(value)
+        .trim()
+        .replace(/[^a-zA-Z0-9._:-]/g, "_")
+        .slice(0, 64);
+    return sanitized.length > 0 ? sanitized : undefined;
+}
+/** Prefer the host call token; otherwise create a bounded per-process token. */
+export function getReadGuardCorrelationId(event) {
+    const value = (event ?? {});
+    const details = (value.details ?? {});
+    for (const candidate of [
+        details.readGuardCorrelationId,
+        details.toolCallId,
+        value.toolCallId,
+        value.callId,
+        value.requestId,
+        value.id,
+    ]) {
+        const sanitized = sanitizeCorrelationId(candidate);
+        if (sanitized)
+            return sanitized;
+    }
+    generatedCorrelationCounter =
+        (generatedCorrelationCounter + 1) % 1_000_000;
+    return `rg-${Date.now().toString(36)}-${generatedCorrelationCounter}`;
+}
+function validIndexes(indexes) {
+    return indexes.filter((index) => Number.isInteger(index) && index >= 0);
+}
+export function boundedEditIndexes(indexes) {
+    return [...new Set(validIndexes(indexes))].slice(0, MAX_EDIT_BATCH_ITEMS);
+}
+export function boundedIndexesForCount(count) {
+    const boundedCount = Math.max(0, Math.floor(count));
+    return Array.from({ length: Math.min(boundedCount, MAX_EDIT_BATCH_ITEMS) }, (_, index) => index);
+}
+export function formatBoundedEditIndexes(indexes) {
+    return boundedEditIndexes(indexes)
+        .map((index) => `edits[${index}]`)
+        .join(", ");
+}
+export function createReadGuardEditBatchSummary(args) {
+    const requestedSource = validIndexes(args.requestedIndexes);
+    const resolvedSource = validIndexes(args.resolvedIndexes ?? []);
+    const rejectedSource = (args.rejectedReasons ?? []).filter((entry) => Number.isInteger(entry.index) && entry.index >= 0);
+    const appliedSource = validIndexes(args.appliedIndexes ?? []);
+    const requestedIndexes = boundedEditIndexes(requestedSource);
+    const resolvedIndexes = boundedEditIndexes(resolvedSource);
+    const rejectedReasons = rejectedSource.slice(0, MAX_EDIT_BATCH_ITEMS);
+    const rejectedIndexes = boundedEditIndexes(rejectedSource.map((entry) => entry.index));
+    const appliedIndexes = boundedEditIndexes(appliedSource);
+    const participantSource = (args.participantIds ?? []).filter((id) => typeof id === "string" && id.length > 0);
+    const participantIds = [...new Set(participantSource)].slice(0, MAX_EDIT_BATCH_ITEMS);
+    const commitStatus = args.commitStatus ?? "not_attempted";
+    const postEditStatus = args.postEditStatus ?? "not_run";
+    const terminalStatus = args.terminalStatus ??
+        (postEditStatus === "failed" || commitStatus === "failed"
+            ? "failed"
+            : commitStatus === "not_attempted" && rejectedSource.length > 0
+                ? "blocked"
+                : commitStatus === "no_changes"
+                    ? "skipped"
+                    : "success");
+    return {
+        requestedCount: requestedSource.length,
+        requestedTotal: args.requestedTotal ?? requestedSource.length,
+        requestedIndexes,
+        resolvedCount: resolvedSource.length,
+        resolvedTotal: args.resolvedTotal ?? resolvedSource.length,
+        resolvedIndexes,
+        rejectedCount: rejectedSource.length,
+        rejectedTotal: args.rejectedTotal ?? rejectedSource.length,
+        rejectedIndexes,
+        rejectedReasons,
+        appliedCount: appliedSource.length,
+        appliedTotal: args.appliedTotal ?? appliedSource.length,
+        appliedIndexes,
+        participantIds,
+        participantTotal: args.participantTotal ?? participantSource.length,
+        participantIdsTruncated: (args.participantTotal ?? participantSource.length) > participantIds.length,
+        indexesTruncated: (args.requestedTotal ?? requestedSource.length) > requestedIndexes.length ||
+            (args.resolvedTotal ?? resolvedSource.length) > resolvedIndexes.length ||
+            (args.rejectedTotal ?? rejectedSource.length) > rejectedIndexes.length ||
+            (args.appliedTotal ?? appliedSource.length) > appliedIndexes.length,
+        commitStatus,
+        postEditStatus,
+        terminalStatus,
+        durationMs: Math.max(0, Math.min(args.durationMs ?? 0, 86_400_000)),
+    };
+}
 function shouldLogEvent(event) {
     if (VERBOSE_READ_GUARD_LOG)
         return true;
@@ -35,13 +130,76 @@ function shouldLogEvent(event) {
         event === "edit_range_relocated" ||
         event === "edit_preflight_blocked" ||
         event === "edit_partial_apply" ||
+        event === "edit_partial_apply_skipped" ||
+        event === "edit_post_edit_pipeline_failed" ||
+        event === "edit_batch_summary" ||
+        event === "edit_batch_summary_overflow" ||
         event === "touched_lines_missing");
 }
+const MAX_TELEMETRY_STRING = 512;
+const MAX_TELEMETRY_KEYS = 64;
+function boundTelemetryValue(value, pathName, depth) {
+    if (typeof value === "string") {
+        return value.length > MAX_TELEMETRY_STRING
+            ? {
+                value: `${value.slice(0, MAX_TELEMETRY_STRING)}…`,
+                truncated: true,
+                arrayTotals: {},
+            }
+            : { value, truncated: false, arrayTotals: {} };
+    }
+    if (Array.isArray(value)) {
+        const sampled = value.slice(0, MAX_EDIT_BATCH_ITEMS);
+        const bounded = sampled.map((item, index) => boundTelemetryValue(item, `${pathName}[${index}]`, depth + 1));
+        const arrayTotals = value.length > MAX_EDIT_BATCH_ITEMS
+            ? { [pathName || "array"]: value.length }
+            : {};
+        let truncated = value.length > MAX_EDIT_BATCH_ITEMS;
+        for (const item of bounded) {
+            truncated ||= item.truncated;
+            Object.assign(arrayTotals, item.arrayTotals);
+        }
+        return {
+            value: bounded.map((item) => item.value),
+            truncated,
+            arrayTotals,
+        };
+    }
+    if (!value || typeof value !== "object" || depth >= 4) {
+        return { value, truncated: false, arrayTotals: {} };
+    }
+    const output = {};
+    let truncated = false;
+    const arrayTotals = {};
+    for (const [key, child] of Object.entries(value).slice(0, MAX_TELEMETRY_KEYS)) {
+        const bounded = boundTelemetryValue(child, pathName ? `${pathName}.${key}` : key, depth + 1);
+        output[key] = bounded.value;
+        truncated ||= bounded.truncated;
+        Object.assign(arrayTotals, bounded.arrayTotals);
+    }
+    if (Object.keys(value).length > MAX_TELEMETRY_KEYS)
+        truncated = true;
+    return { value: output, truncated, arrayTotals };
+}
 export function logReadGuardEvent(entry) {
     if (isTestMode() || !shouldLogEvent(entry.event)) {
         return;
     }
-    writer.log({ ts: new Date().toISOString(), ...entry });
+    const rawMetadata = entry.correlationId
+        ? { ...(entry.metadata ?? {}), correlationId: entry.correlationId }
+        : entry.metadata;
+    const bounded = boundTelemetryValue(rawMetadata, "metadata", 0);
+    const metadata = bounded.truncated && bounded.value && typeof bounded.value === "object"
+        ? {
+            ...bounded.value,
+            telemetryTruncated: true,
+            telemetryArrayTotals: bounded.arrayTotals,
+        }
+        : bounded.value && typeof bounded.value === "object"
+            ? bounded.value
+            : undefined;
+    const { correlationId: _correlationId, ...logEntry } = entry;
+    writer.log({ ts: new Date().toISOString(), ...logEntry, metadata });
 }
 export function getReadGuardLogPath() {
     return READ_GUARD_LOG_FILE;