@nklisch/pi-enhanced 0.2.0 → 0.2.2

package/node_modules/@nklisch/pi-clearance/src/packs/package-registration.ts

@@ -152,51 +152,72 @@ export function createPackageRegistrationStore(
   }
 
   function notify(): void {
-    onChange?.();
+    try {
+      onChange?.();
+    } catch (error) {
+      // The change hook invalidates another in-memory subsystem. It is part of
+      // this callback's recovery path, so a broken hook must remain observable
+      // without escaping into the host event bus.
+      recordListenerIssue("change-notification-error", error);
+    }
+  }
+
+  function recordListenerIssue(code: string, error: unknown): void {
+    const message = `package registration event handler failed: ${errorMessage(error)}`;
+    issues.push({ severity: "error", code, path: "event", message });
+    console.error(`Pi Clearance ${message}`);
   }
 
   // Register-event listener. Classifies each incoming payload by request id:
   // accept unsolicited (no requestId) and current-request responses; warn and
-  // ignore stale responses for older request ids. The normalizer is total, so
-  // this handler never throws on payload shape. The unsubscribe handle is kept
-  // so `session_shutdown` can detach this store from Pi's persistent event bus.
+  // ignore stale responses for older request ids. The event bus is an
+  // out-of-band callback boundary: payload property getters and normalizers
+  // operate inside the containment block so hostile contributor input cannot
+  // escape through Pi's shared event bus.
   const unsubscribeRegister = bus.on(
     AUTO_REVIEWER_PACKS_REGISTER_EVENT,
     (data: unknown) => {
-      if (disposed) {
-        return;
-      }
+      try {
+        if (disposed) {
+          return;
+        }
+
+        const rawRequestId = readRequestId(data);
 
-      const rawRequestId = readRequestId(data);
+        if (rawRequestId !== undefined && rawRequestId !== currentRequestId) {
+          // Stale: a response for a request we are no longer servicing (e.g. an
+          // older request id after reload). Record a warning and contribute
+          // nothing, so stale data can never widen available packs.
+          issues.push({
+            severity: "warning",
+            code: "stale-registration",
+            path: "event",
+            message: buildStaleMessage(rawRequestId, currentRequestId),
+          });
+          if (!isCollecting) {
+            notify();
+          }
+          return;
+        }
 
-      if (rawRequestId !== undefined && rawRequestId !== currentRequestId) {
-        // Stale: a response for a request we are no longer servicing (e.g. an
-        // older request id after reload). Record a warning and contribute
-        // nothing, so stale data can never widen available packs.
-        issues.push({
-          severity: "warning",
-          code: "stale-registration",
-          path: "event",
-          message: buildStaleMessage(rawRequestId, currentRequestId),
-        });
+        // Accept: matches the current request id, or unsolicited (no request
+        // id). Unsolicited registrations support manual tests and contributors
+        // that emit during their own session_start.
+        const result = normalizePackagePackRegistration(data);
+        for (const pack of result.packs) {
+          packs.push(pack);
+        }
+        for (const issue of result.issues) {
+          issues.push(issue);
+        }
+        if (!isCollecting) {
+          notify();
+        }
+      } catch (error) {
+        recordListenerIssue("listener-error", error);
         if (!isCollecting) {
           notify();
         }
-        return;
-      }
-
-      // Accept: matches the current request id, or unsolicited (no request id).
-      // Unsolicited registrations support manual tests and contributors that
-      // emit during their own session_start.
-      const result = normalizePackagePackRegistration(data);
-      for (const pack of result.packs) {
-        packs.push(pack);
-      }
-      for (const issue of result.issues) {
-        issues.push(issue);
-      }
-      if (!isCollecting) {
-        notify();
       }
     },
   );
@@ -233,9 +254,7 @@ export function createPackageRegistrationStore(
         severity: "error",
         code: "collection-error",
         path: "event",
-        message: `package registration request failed: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
+        message: `package registration request failed: ${errorMessage(error)}`,
       });
     } finally {
       isCollecting = false;
@@ -297,3 +316,11 @@ function buildStaleMessage(
     ? `Ignoring package registration for request id "${rawRequestId}" (no active collection).`
     : `Ignoring package registration for stale request id "${rawRequestId}" (current "${currentRequestId}").`;
 }
+
+function errorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "unknown error";
+  }
+}

package/node_modules/@nklisch/pi-clearance/src/runtime/allow-request-message.ts

@@ -16,6 +16,45 @@ export interface ClearanceAllowRequestDetails {
 export const renderClearanceAllowRequest: MessageRenderer<
   ClearanceAllowRequestDetails
 > = (message) => {
-  const form = message.details?.form ?? "request";
+  const form = readAllowRequestForm(message);
   return new Text(`[Pi Clearance] Allow request handed to agent (${form})`);
 };
+
+function readAllowRequestForm(message: unknown):
+  | ClearanceAllowRequestDetails["form"]
+  | "request" {
+  try {
+    if (!isRecord(message)) return "request";
+    const details = message.details;
+    if (!isRecord(details)) return "request";
+    const form = details.form;
+    return isAllowRequestForm(form) ? form : "request";
+  } catch (error) {
+    // Message details come from the persisted/custom-message boundary. A
+    // hostile getter must degrade the transcript row, not escape the renderer.
+    console.error(
+      `Pi Clearance allow-request details validation failed: ${errorMessage(error)}`,
+    );
+    return "request";
+  }
+}
+
+function isAllowRequestForm(value: unknown): value is ClearanceAllowRequestDetails["form"] {
+  return (
+    value === "free-text" ||
+    value === "recent-command" ||
+    value === "no-recent-command"
+  );
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function errorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "unknown error";
+  }
+}

package/node_modules/@nklisch/pi-clearance/src/runtime/command-registry.ts

@@ -87,8 +87,20 @@ export function buildClearanceCommandOptions(
       return getClearanceArgumentCompletions(argumentPrefix, deps);
     },
     async handler(args, ctx) {
-      const report = await handleClearanceCommand(args, ctx, pi, deps);
-      notify(ctx, report.markdown, report.level ?? "info");
+      try {
+        const report = await handleClearanceCommand(args, ctx, pi, deps);
+        notify(ctx, report.markdown, report.level ?? "info");
+      } catch (error) {
+        // Pi catches registered command promises, but that host-level catch does
+        // not provide a useful slash-command recovery message. Do not convert
+        // this into a write result or attempt rollback: any completed durable
+        // write remains completed, and the user gets an observable diagnostic.
+        notify(
+          ctx,
+          `Pi Clearance command failed: ${errorMessage(error)}`,
+          "error",
+        );
+      }
     },
   };
 }
@@ -364,3 +376,11 @@ function splitCompletionPrefix(argumentPrefix: string): {
     current: tokens.at(-1) ?? "",
   };
 }
+
+function errorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "unknown error";
+  }
+}

package/node_modules/@nklisch/pi-clearance/src/runtime/command-transforms.ts

@@ -170,36 +170,51 @@ export function createCommandTransformStore(
     currentRequestId = null;
   }
 
+  function recordListenerIssue(code: string, error: unknown): void {
+    const message = `command transform registration event handler failed: ${errorMessage(error)}`;
+    issues.push({ severity: "error", code, path: "event", message });
+    console.error(`Pi Clearance ${message}`);
+  }
+
   const unsubscribeRegister = on(
     AUTO_REVIEWER_TRANSFORMS_REGISTER_EVENT,
     (data: unknown) => {
-      if (disposed) {
-        return;
-      }
+      try {
+        if (disposed) {
+          return;
+        }
 
-      const rawRequestId = readRequestId(data);
-      if (rawRequestId !== undefined && rawRequestId !== currentRequestId) {
-        // Stale response for a request we are no longer servicing. Ignore it so
-        // stale data can never widen the transform set.
-        issues.push({
-          severity: "warning",
-          code: "stale-registration",
-          path: "event",
-          message: buildStaleMessage(rawRequestId, currentRequestId),
-        });
-        return;
-      }
+        // This is a raw event-bus callback. Keep request-id getters,
+        // normalization, and array updates in one containment block: a
+        // contributor can supply a Proxy/getter rather than a plain object.
+        const rawRequestId = readRequestId(data);
+        if (rawRequestId !== undefined && rawRequestId !== currentRequestId) {
+          // Stale response for a request we are no longer servicing. Ignore it
+          // so stale data can never widen the transform set.
+          issues.push({
+            severity: "warning",
+            code: "stale-registration",
+            path: "event",
+            message: buildStaleMessage(rawRequestId, currentRequestId),
+          });
+          return;
+        }
 
-      const result = normalizeCommandTransformRegistration(data);
-      if (result.transform !== null) {
-        transforms.push({
-          id: result.transform.id,
-          description: result.transform.description,
-          run: result.transform.transform,
-        });
-      }
-      for (const issue of result.issues) {
-        issues.push(issue);
+        const result = normalizeCommandTransformRegistration(data);
+        if (result.transform !== null) {
+          transforms.push({
+            id: result.transform.id,
+            description: result.transform.description,
+            run: result.transform.transform,
+          });
+        }
+        for (const issue of result.issues) {
+          issues.push(issue);
+        }
+      } catch (error) {
+        // Do not rely on Pi's event bus swallowing errors. This listener is an
+        // extension-owned out-of-band boundary and must be total on its own.
+        recordListenerIssue("listener-error", error);
       }
     },
   );
@@ -227,9 +242,7 @@ export function createCommandTransformStore(
         severity: "error",
         code: "collection-error",
         path: "event",
-        message: `transform registration request failed: ${
-          error instanceof Error ? error.message : String(error)
-        }`,
+        message: `transform registration request failed: ${errorMessage(error)}`,
       });
     }
 
@@ -310,7 +323,7 @@ export function createCommandTransformStore(
         lastNote = {
           id: transform.id,
           kind: "error",
-          message: error instanceof Error ? error.message : String(error),
+          message: errorMessage(error),
         };
         // fail open: keep current command
       }
@@ -371,3 +384,11 @@ function buildStaleMessage(
     ? `Ignoring transform registration for request id "${rawRequestId}" (no active collection).`
     : `Ignoring transform registration for stale request id "${rawRequestId}" (current "${currentRequestId}").`;
 }
+
+function errorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "unknown error";
+  }
+}

package/node_modules/@nklisch/pi-clearance/src/runtime/config-commands/settings/native-ui.ts

@@ -146,10 +146,14 @@ interface MinimalTui {
 const DOSSIER_VISIBLE_LINES = 12;
 
 export function canOpenSettingsNativeUi(ctx: ExtensionCommandContext): boolean {
-  const custom = (
-    ctx as unknown as { readonly ui?: { readonly custom?: unknown } }
-  ).ui?.custom;
-  return ctx.hasUI === true && typeof custom === "function";
+  try {
+    const custom = (
+      ctx as unknown as { readonly ui?: { readonly custom?: unknown } }
+    ).ui?.custom;
+    return ctx.hasUI === true && typeof custom === "function";
+  } catch {
+    return false;
+  }
 }
 
 export async function openSettingsNativeUi(
@@ -179,15 +183,27 @@ export async function openSettingsNativeUi(
   const handled: SettingsNativeUiHandledAction[] = [];
 
   while (true) {
-    const interaction = await presentSettingsNativeUi({
-      ctx: options.ctx,
-      model,
-      screen,
-      selected,
-      dossierScroll,
-      dossierOrigin,
-      ...(message === undefined ? {} : { message }),
-    });
+    let interaction: NativeSettingsUiInteraction;
+    try {
+      interaction = await presentSettingsNativeUi({
+        ctx: options.ctx,
+        model,
+        screen,
+        selected,
+        dossierScroll,
+        dossierOrigin,
+        ...(message === undefined ? {} : { message }),
+      });
+    } catch (error) {
+      return {
+        ok: false,
+        report: nativeSettingsFailureReport(
+          "presentation",
+          error,
+          handled.length,
+        ),
+      };
+    }
     const selection = interaction.selection;
     if (selection.kind === "close") {
       return {
@@ -201,11 +217,16 @@ export async function openSettingsNativeUi(
       };
     }
 
-    const report = await dispatchNativeSettingsSelection(
-      selection,
-      options.ctx,
-      options.deps,
-    );
+    let report: CommandReport;
+    try {
+      report = await dispatchNativeSettingsSelection(
+        selection,
+        options.ctx,
+        options.deps,
+      );
+    } catch (error) {
+      report = nativeSettingsFailureReport("action", error, handled.length);
+    }
     const handledAction: SettingsNativeUiHandledAction = {
       label: selection.label,
       reportTitle: report.title,
@@ -232,7 +253,15 @@ export async function openSettingsNativeUi(
     selected = dossier === undefined ? interaction.selected : 0;
     dossierScroll = dossier === undefined ? interaction.dossierScroll : 0;
 
-    const reloaded = await options.reload();
+    let reloaded: Awaited<ReturnType<SettingsNativeUiReload>>;
+    try {
+      reloaded = await options.reload();
+    } catch (error) {
+      return {
+        ok: false,
+        report: nativeSettingsFailureReport("reload", error, handled.length),
+      };
+    }
     if (!reloaded.ok) {
       return { ok: false, report: reloaded.report };
     }
@@ -252,25 +281,86 @@ async function presentSettingsNativeUi(input: {
   const custom = input.ctx.ui.custom.bind(input.ctx.ui);
   return await custom<NativeSettingsUiInteraction>(
     (tui, theme, _keybindings, done) => {
-      let component!: SettingsNativeUiComponent;
-      component = new SettingsNativeUiComponent({
-        model: input.model,
-        theme: theme as MinimalTheme,
-        done: (selection) =>
-          done({ selection, ...component.getNavigationState() }),
-        initialScreen: input.screen,
-        initialSelected: input.selected,
-        initialDossierScroll: input.dossierScroll,
-        dossierOrigin: input.dossierOrigin,
-        ...(input.message === undefined ? {} : { message: input.message }),
-      });
+      let component: SettingsNativeUiComponent | undefined;
+      let lastFailure: string | undefined;
+      const fallbackNavigation = {
+        screen: input.screen,
+        selected: input.selected,
+        dossierScroll: input.dossierScroll,
+      } satisfies Omit<NativeSettingsUiInteraction, "selection">;
+
+      const reportFailure = (phase: string, error: unknown): void => {
+        const diagnostic = `Pi Clearance native settings ${phase} failed: ${errorMessage(error)}`;
+        if (diagnostic === lastFailure) return;
+        lastFailure = diagnostic;
+        console.error(diagnostic);
+      };
+
+      const safeDone = (selection: SettingsNativeUiSelection): void => {
+        try {
+          done({
+            selection,
+            ...(component?.getNavigationState() ?? fallbackNavigation),
+          });
+        } catch (error) {
+          reportFailure("completion", error);
+        }
+      };
+
+      try {
+        component = new SettingsNativeUiComponent({
+          model: input.model,
+          theme: theme as MinimalTheme,
+          done: safeDone,
+          initialScreen: input.screen,
+          initialSelected: input.selected,
+          initialDossierScroll: input.dossierScroll,
+          dossierOrigin: input.dossierOrigin,
+          ...(input.message === undefined ? {} : { message: input.message }),
+        });
+      } catch (error) {
+        reportFailure("component construction", error);
+      }
+
       const minimalTui = tui as MinimalTui;
       return {
-        render: (width: number) => component.render(width),
-        invalidate: () => component.invalidate(),
+        render: (width: number) => {
+          try {
+            if (component === undefined) {
+              return renderNativeSettingsFallback(width, lastFailure);
+            }
+            return component.render(width);
+          } catch (error) {
+            reportFailure("render", error);
+            return renderNativeSettingsFallback(width, lastFailure);
+          }
+        },
+        invalidate: () => {
+          try {
+            component?.invalidate();
+          } catch (error) {
+            reportFailure("invalidation", error);
+          }
+        },
         handleInput: (data: string) => {
-          component.handleInput(data);
-          minimalTui.requestRender?.();
+          try {
+            if (component === undefined) {
+              if (isClose(data)) safeDone({ kind: "close" });
+            } else {
+              component.handleInput(data);
+            }
+          } catch (error) {
+            reportFailure("input", error);
+          }
+
+          // requestRender is a host callback too; a broken TUI refresh must
+          // not prevent the component from accepting a later close/recovery
+          // input or turn a completed settings write into a failed command.
+          try {
+            minimalTui.requestRender?.call(tui);
+          } catch (error) {
+            reportFailure("input refresh", error);
+          }
         },
       };
     },
@@ -320,16 +410,29 @@ async function readNativeSettingsInput(
   | { readonly ok: true; readonly value: string | null }
   | { readonly ok: false; readonly report: CommandReport }
 > {
-  const input = (
-    ctx as unknown as {
-      readonly ui?: {
-        readonly input?: (
-          title: string,
-          placeholder?: string,
-        ) => Promise<string | undefined> | string | undefined;
-      };
-    }
-  ).ui?.input;
+  let input:
+    | ((
+        title: string,
+        placeholder?: string,
+      ) => Promise<string | undefined> | string | undefined)
+    | undefined;
+  try {
+    input = (
+      ctx as unknown as {
+        readonly ui?: {
+          readonly input?: (
+            title: string,
+            placeholder?: string,
+          ) => Promise<string | undefined> | string | undefined;
+        };
+      }
+    ).ui?.input;
+  } catch (error) {
+    return {
+      ok: false,
+      report: nativeInputRefusedReport(selection, "failed", error),
+    };
+  }
 
   if (typeof input !== "function") {
     return {
@@ -338,7 +441,29 @@ async function readNativeSettingsInput(
     };
   }
 
-  const value = await input(selection.prompt, selection.placeholder ?? "");
+  let value: string | undefined;
+  try {
+    const rawValue = await input(
+      selection.prompt,
+      selection.placeholder ?? "",
+    );
+    if (rawValue !== undefined && typeof rawValue !== "string") {
+      return {
+        ok: false,
+        report: nativeInputRefusedReport(
+          selection,
+          "failed",
+          new Error("Pi UI input returned a non-string value"),
+        ),
+      };
+    }
+    value = rawValue;
+  } catch (error) {
+    return {
+      ok: false,
+      report: nativeInputRefusedReport(selection, "failed", error),
+    };
+  }
   if (value === undefined) {
     return {
       ok: false,
@@ -346,7 +471,15 @@ async function readNativeSettingsInput(
     };
   }
 
-  const trimmed = value.trim();
+  let trimmed: string;
+  try {
+    trimmed = value.trim();
+  } catch (error) {
+    return {
+      ok: false,
+      report: nativeInputRefusedReport(selection, "failed", error),
+    };
+  }
   if (trimmed.length === 0) {
     if (selection.empty === "null") {
       return { ok: true, value: null };
@@ -365,7 +498,8 @@ function nativeInputRefusedReport(
     SettingsNativeUiSelection,
     { readonly kind: "input-action" }
   >,
-  reason: "unavailable" | "cancelled" | "empty",
+  reason: "unavailable" | "cancelled" | "empty" | "failed",
+  error?: unknown,
 ): CommandReport {
   const summary = (() => {
     switch (reason) {
@@ -375,6 +509,8 @@ function nativeInputRefusedReport(
         return "Text input was cancelled; no config changes were written.";
       case "empty":
         return "Text input was empty; no config changes were written.";
+      case "failed":
+        return `Text input failed: ${errorMessage(error)}; no config changes were written.`;
     }
   })();
 
@@ -390,10 +526,50 @@ function nativeInputRefusedReport(
       "- No config changes were written.",
     ].join("\n"),
     details: { reason: `native-input-${reason}`, selection },
-    level: reason === "unavailable" ? "error" : "warning",
+    level: reason === "unavailable" || reason === "failed" ? "error" : "warning",
+  };
+}
+
+function nativeSettingsFailureReport(
+  phase: string,
+  error: unknown,
+  actionsHandled: number,
+): CommandReport {
+  const message = errorMessage(error);
+  const summary = `Pi Clearance settings ${phase} failed: ${message}. Previously confirmed actions, if any, remain applied; no rollback was attempted.`;
+  return {
+    title: "Pi Clearance settings failed",
+    summary,
+    markdown: [
+      "# Pi Clearance settings failed",
+      "",
+      `- Phase: ${phase}`,
+      `- Error: ${message}`,
+      `- Actions already handled: ${actionsHandled}`,
+      "- Reopen status to verify any previously confirmed writes.",
+    ].join("\n"),
+    details: { reason: `native-ui-${phase}-failed`, actionsHandled, error: message },
+    level: "error",
   };
 }
 
+function renderNativeSettingsFallback(
+  width: number,
+  diagnostic: string | undefined,
+): string[] {
+  const lines = [
+    "Pi Clearance settings UI encountered an error.",
+    diagnostic ?? "The settings component could not be rendered.",
+    "Previously confirmed actions, if any, remain applied.",
+    "Press q or Esc to close.",
+  ];
+  try {
+    return lines.map((line) => truncateAnsi(line, Math.max(1, width)));
+  } catch {
+    return ["Pi Clearance settings UI unavailable.", "Press q or Esc to close."];
+  }
+}
+
 interface NativeSettingsMessage {
   readonly level: "info" | "warning" | "error";
   readonly text: string;
@@ -1045,3 +1221,11 @@ function isClose(data: string): boolean {
 export function truncateAnsi(input: string, width: number): string {
   return truncateToWidth(input, width, width >= 2 ? "…" : "");
 }
+
+function errorMessage(error: unknown): string {
+  try {
+    return error instanceof Error ? error.message : String(error);
+  } catch {
+    return "unknown error";
+  }
+}