@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-clearance/src/runtime/config-commands/tune-cue.ts

@@ -0,0 +1,50 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import type { AutoReviewerCommandDependencies } from "./types.ts";
+
+const TUNE_STATUS_KEY = "clearance-tune";
+
+export type TuneCueUpdateResult =
+  | {
+      readonly kind: "status";
+      readonly active: boolean;
+      readonly key: typeof TUNE_STATUS_KEY;
+      readonly label: string | undefined;
+    }
+  | {
+      readonly kind: "none";
+      readonly active: boolean;
+      readonly reason: "ui-unavailable" | "chrome-unavailable";
+    };
+
+interface TuneStatusCapableUi {
+  readonly setStatus?: (key: string, value: string | undefined) => void;
+}
+
+export function formatTuneCueStatus(active: boolean): string {
+  return active ? "Tune active" : "Tune inactive";
+}
+
+export function updateTuneActiveCue(
+  ctx: ExtensionCommandContext,
+  deps: Pick<AutoReviewerCommandDependencies, "manager">,
+): TuneCueUpdateResult {
+  const active = deps.manager.isRatchetActive();
+  if (ctx.hasUI !== true) {
+    return { kind: "none", active, reason: "ui-unavailable" };
+  }
+
+  const ui = ctx.ui as TuneStatusCapableUi | undefined;
+  if (typeof ui?.setStatus === "function") {
+    const label = active ? formatTuneCueStatus(active) : undefined;
+    try {
+      ui.setStatus(TUNE_STATUS_KEY, label);
+      return { kind: "status", active, key: TUNE_STATUS_KEY, label };
+    } catch {
+      // The command report carries the state. A failed chrome update must not
+      // affect Tune activation or claim a visual cue that was not rendered.
+    }
+  }
+
+  return { kind: "none", active, reason: "chrome-unavailable" };
+}

package/node_modules/@nklisch/pi-clearance/src/runtime/config-commands/tune.ts

@@ -0,0 +1,135 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+
+import type { RatchetModeResult } from "../ratchet-mode.ts";
+import { type TuneCueUpdateResult, updateTuneActiveCue } from "./tune-cue.ts";
+import {
+  type AutoReviewerCommandDependencies,
+  type CommandPi,
+  type CommandReport,
+  usageReport,
+} from "./types.ts";
+
+export interface TuneCommandDetails {
+  readonly command: "tune";
+  readonly action: "toggle" | "on" | "off";
+  readonly result: RatchetModeResult;
+  readonly status: RatchetModeResult["status"];
+  readonly toolNames: readonly string[];
+  readonly cue: TuneCueUpdateResult;
+}
+
+export function handleTuneCommand(
+  rest: readonly string[],
+  ctx: ExtensionCommandContext,
+  pi: CommandPi,
+  deps: AutoReviewerCommandDependencies,
+): CommandReport<
+  TuneCommandDetails | { readonly usage: true; readonly reason?: string }
+> {
+  const parsed = parseTuneArgs(rest);
+  if (!parsed.ok) {
+    return usageReport(parsed.reason);
+  }
+
+  const wasActive = deps.manager.isRatchetActive();
+  const desiredActive =
+    parsed.action === "toggle" ? !wasActive : parsed.action === "on";
+  const result = desiredActive
+    ? deps.manager.enterRatchetMode(pi)
+    : deps.manager.exitRatchetMode(pi);
+  const cue = updateTuneActiveCue(ctx, deps);
+  const toolNames = result.status.ratchetToolNames;
+
+  return {
+    title: tuneTitle({ action: parsed.action, wasActive, desiredActive }),
+    summary: tuneSummary({ wasActive, desiredActive, toolNames }),
+    markdown: formatTuneMarkdown({ result, desiredActive, toolNames }),
+    details: {
+      command: "tune",
+      action: parsed.action,
+      result,
+      status: result.status,
+      toolNames,
+      cue,
+    },
+    level: result.fallback === undefined ? "info" : "warning",
+  };
+}
+
+function parseTuneArgs(
+  tokens: readonly string[],
+):
+  | { readonly ok: true; readonly action: "toggle" | "on" | "off" }
+  | { readonly ok: false; readonly reason: string } {
+  if (tokens.length === 0) {
+    return { ok: true, action: "toggle" };
+  }
+
+  if (tokens.length === 1 && (tokens[0] === "on" || tokens[0] === "off")) {
+    return { ok: true, action: tokens[0] };
+  }
+
+  return {
+    ok: false,
+    reason: "Expected `tune` (or hidden explicit form `tune on|off`).",
+  };
+}
+
+function tuneTitle(input: {
+  readonly action: "toggle" | "on" | "off";
+  readonly wasActive: boolean;
+  readonly desiredActive: boolean;
+}): string {
+  if (input.action !== "toggle" && input.wasActive === input.desiredActive) {
+    return `Tune mode already ${input.desiredActive ? "on" : "off"}`;
+  }
+
+  return `Tune mode ${input.desiredActive ? "enabled" : "disabled"}`;
+}
+
+function tuneSummary(input: {
+  readonly wasActive: boolean;
+  readonly desiredActive: boolean;
+  readonly toolNames: readonly string[];
+}): string {
+  const tools = formatToolList(input.toolNames);
+  if (input.desiredActive) {
+    return input.wasActive
+      ? `Tune mode is already on; active Tune tools: ${tools}.`
+      : `Tune mode is on; active Tune tools: ${tools}.`;
+  }
+
+  return input.wasActive
+    ? `Tune mode is off; removed Tune tools: ${tools}.`
+    : `Tune mode is already off; Tune tools remain inactive: ${tools}.`;
+}
+
+function formatTuneMarkdown(input: {
+  readonly result: RatchetModeResult;
+  readonly desiredActive: boolean;
+  readonly toolNames: readonly string[];
+}): string {
+  const lines = [
+    `# ${input.desiredActive ? "Tune mode on" : "Tune mode off"}`,
+    "",
+    `- State: ${input.desiredActive ? "on" : "off"}`,
+    `- Tune tools: ${formatToolList(input.toolNames)}`,
+    `- Manager: ${input.result.message}`,
+  ];
+
+  if (input.result.fallback !== undefined) {
+    const { fallback } = input.result;
+    lines.push(
+      `- Warning: ${fallback.message}`,
+      `- Expected active tools: ${formatToolList(fallback.expected)}`,
+      `- Actual active tools: ${formatToolList(fallback.actual)}`,
+      `- Restored tools: ${formatToolList(fallback.restored)}`,
+    );
+  }
+
+  return lines.join("\n");
+}
+
+function formatToolList(toolNames: readonly string[]): string {
+  return toolNames.length === 0 ? "(none)" : toolNames.join(", ");
+}

package/node_modules/@nklisch/pi-clearance/src/runtime/config-commands/types.ts

@@ -0,0 +1,163 @@
+import type {
+  ExtensionAPI,
+  ExtensionCommandContext,
+} from "@earendil-works/pi-coding-agent";
+
+import type { AuditLogger } from "../../audit/logger.ts";
+import type { PackageRegistrationSnapshot } from "../../packs/package-registration.ts";
+import type { ToolAnalyzerRegistry } from "../../parse/registry.ts";
+import type { PolicyResolver, ResolvedPolicy } from "../policy-cache.ts";
+import type { RatchetModeManager } from "../ratchet-mode.ts";
+import type { RecentDecisionSource } from "../reviewer-context.ts";
+
+export type {
+  RecentDecisionEntry,
+  RecentDecisionSource,
+} from "../reviewer-context.ts";
+
+export interface AutoReviewerCommandDependencies {
+  readonly manager: RatchetModeManager;
+  readonly policyResolver: PolicyResolver;
+  readonly packageRegistration: () => PackageRegistrationSnapshot;
+  readonly audit: AuditLogger;
+  /** Bounded recent audit decisions used by `/clearance allow` with no text. */
+  readonly recentDecisionSource: RecentDecisionSource;
+  /** Structural analyzer used only to summarize the recent command for the agent. */
+  readonly analyzerRegistry: ToolAnalyzerRegistry;
+}
+
+export interface CommandReport<TDetails = unknown> {
+  readonly title: string;
+  readonly summary: string;
+  readonly markdown: string;
+  readonly details: TDetails;
+  readonly level?: "info" | "warning" | "error";
+}
+
+export interface AutoReviewerAutocompleteItem {
+  readonly value: string;
+  readonly label: string;
+  readonly description?: string;
+}
+
+export type CommandPi = Pick<
+  ExtensionAPI,
+  | "getActiveTools"
+  | "getAllTools"
+  | "setActiveTools"
+  | "registerTool"
+  | "sendUserMessage"
+>;
+
+export const USAGE_MARKDOWN = [
+  "# Pi Clearance commands",
+  "",
+  "Primary surface:",
+  "- `/clearance setup` — open the guided setup entry point.",
+  "- `/clearance settings` — open the settings control center.",
+  "- `/clearance status [--warnings]` — show current status.",
+  "- `/clearance mode [off|ask|auto]` — show or set the global Clearance mode.",
+  "- `/clearance packs [--source <kind>] [--enabled|--disabled] [--baseline] [--tag <tag>]` — open Policy dossiers.",
+  "- `/clearance scope` — open Safe Zones settings.",
+  "- `/clearance tune` — toggle Tune mode.",
+  "- `/clearance why [count]` — open a Debrief for recent clearance decisions.",
+  "- `/clearance allow <plain language>` or `/clearance allow` — hand a focused allow request to the agent for the approval card.",
+  "",
+  "",
+  "Tune analysis tools are available only while `/clearance tune` is active; proposal tools remain available in every mode.",
+  "",
+  "Advanced settings such as reviewer prompt posture, context mode, token budget, and escalation are edited in user-owned global config; reviewer model selection remains available in settings.",
+].join("\n");
+
+export async function resolvePolicyForCommand(
+  ctx: ExtensionCommandContext,
+  deps: Pick<AutoReviewerCommandDependencies, "policyResolver">,
+): Promise<ResolvedPolicy> {
+  const result = await deps.policyResolver.resolve(ctx);
+  if (!result.ok) {
+    throw new Error(`auto-reviewer policy resolution failed: ${result.reason}`);
+  }
+
+  return result.policy;
+}
+
+export async function resolvePolicyReport(
+  ctx: ExtensionCommandContext,
+  deps: Pick<AutoReviewerCommandDependencies, "policyResolver">,
+): Promise<
+  | { readonly ok: true; readonly policy: ResolvedPolicy }
+  | {
+      readonly ok: false;
+      readonly report: CommandReport<{ readonly error: string }>;
+    }
+> {
+  try {
+    return { ok: true, policy: await resolvePolicyForCommand(ctx, deps) };
+  } catch (error: unknown) {
+    const message = errorMessage(error);
+    return {
+      ok: false,
+      report: {
+        title: "Auto-reviewer command failed",
+        summary: message,
+        markdown: [
+          "# Auto-reviewer command failed",
+          "",
+          `- Error: ${message}`,
+          "- No config changes were written.",
+        ].join("\n"),
+        details: { error: message },
+        level: "error",
+      },
+    };
+  }
+}
+
+export function usageReport(
+  reason?: string,
+): CommandReport<{ readonly usage: true; readonly reason?: string }> {
+  return {
+    title: "Pi Clearance usage",
+    summary: reason ?? "Show Pi Clearance command usage.",
+    markdown:
+      reason === undefined
+        ? USAGE_MARKDOWN
+        : [`# Pi Clearance usage`, "", `- ${reason}`, "", USAGE_MARKDOWN].join(
+            "\n",
+          ),
+    details: reason === undefined ? { usage: true } : { usage: true, reason },
+    level: reason === undefined ? "info" : "error",
+  };
+}
+
+export function completion(
+  value: string,
+  description: string,
+): AutoReviewerAutocompleteItem {
+  return { value, label: value, description };
+}
+
+export function filterCompletions(
+  items: readonly AutoReviewerAutocompleteItem[],
+  current: string,
+): AutoReviewerAutocompleteItem[] | null {
+  const filtered = items.filter((item) => item.value.startsWith(current));
+  return filtered.length === 0 ? null : filtered;
+}
+
+export function stableUnique<T>(values: readonly T[]): readonly T[] {
+  const seen = new Set<T>();
+  const result: T[] = [];
+  for (const value of values) {
+    if (seen.has(value)) {
+      continue;
+    }
+    seen.add(value);
+    result.push(value);
+  }
+  return result;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/node_modules/@nklisch/pi-clearance/src/runtime/config-commands/why.ts

@@ -0,0 +1,253 @@
+import type { ExtensionCommandContext } from "@earendil-works/pi-coding-agent";
+import type { RecentDecisionEntry } from "../reviewer-context.ts";
+import { createAuditLogRecentDecisionSource } from "../reviewer-context-adapter.ts";
+import {
+  type AutoReviewerCommandDependencies,
+  type CommandReport,
+  usageReport,
+} from "./types.ts";
+
+const MAX_DEBRIEF_DECISIONS = 5;
+const NOT_RECORDED = "not recorded";
+
+export interface WhyCommandDetails {
+  readonly count: number;
+  readonly requestedCount: number;
+  readonly cappedAt: number;
+  readonly decisions: readonly RecentDecisionEntry[];
+  readonly warnings: readonly string[];
+}
+
+export function handleWhyCommand(
+  rest: readonly string[],
+  _ctx: ExtensionCommandContext,
+  _deps: AutoReviewerCommandDependencies,
+): CommandReport<
+  WhyCommandDetails | { readonly usage: true; readonly reason?: string }
+> {
+  const parsed = parseWhyArgs(rest);
+  if (!parsed.ok) {
+    return usageReport(parsed.reason);
+  }
+
+  const source = createAuditLogRecentDecisionSource();
+  const result = source.readRecent();
+  const decisions = result.items.slice(0, parsed.count);
+
+  if (decisions.length === 0) {
+    return {
+      title: "Debrief",
+      summary: "No clearance decisions recorded yet.",
+      markdown: ["# Debrief", "", "No clearance decisions recorded yet."].join(
+        "\n",
+      ),
+      details: {
+        count: 0,
+        requestedCount: parsed.requestedCount,
+        cappedAt: MAX_DEBRIEF_DECISIONS,
+        decisions,
+        warnings: result.warnings,
+      },
+      level: result.warnings.length === 0 ? "info" : "warning",
+    };
+  }
+
+  return {
+    title: "Debrief",
+    summary:
+      decisions.length === 1
+        ? `Most recent clearance decision: ${decisions[0]?.effect ?? NOT_RECORDED} ${decisions[0]?.toolName ?? NOT_RECORDED}.`
+        : `Last ${decisions.length} clearance decisions.`,
+    markdown: renderDebriefMarkdown(decisions, result.warnings),
+    details: {
+      count: decisions.length,
+      requestedCount: parsed.requestedCount,
+      cappedAt: MAX_DEBRIEF_DECISIONS,
+      decisions,
+      warnings: result.warnings,
+    },
+    level: result.warnings.length === 0 ? "info" : "warning",
+  };
+}
+
+function parseWhyArgs(tokens: readonly string[]):
+  | {
+      readonly ok: true;
+      readonly count: number;
+      readonly requestedCount: number;
+    }
+  | { readonly ok: false; readonly reason: string } {
+  if (tokens.length === 0) {
+    return { ok: true, count: 1, requestedCount: 1 };
+  }
+
+  if (tokens.length !== 1) {
+    return { ok: false, reason: "Expected `why` or `why <count>`." };
+  }
+
+  const [countText] = tokens;
+  if (countText === undefined || !/^\d+$/.test(countText)) {
+    return { ok: false, reason: "Expected `why` or `why <count>`." };
+  }
+
+  const requestedCount = Number(countText);
+  if (!Number.isSafeInteger(requestedCount) || requestedCount < 1) {
+    return { ok: false, reason: "Expected `why` or `why <count>`." };
+  }
+
+  return {
+    ok: true,
+    requestedCount,
+    count: Math.min(requestedCount, MAX_DEBRIEF_DECISIONS),
+  };
+}
+
+function renderDebriefMarkdown(
+  decisions: readonly RecentDecisionEntry[],
+  warnings: readonly string[],
+): string {
+  const lines = ["# Debrief", ""];
+
+  decisions.forEach((decision, index) => {
+    if (index > 0) lines.push("");
+    lines.push(
+      `## ${decision.timestamp} — ${valueOrNotRecorded(decision.toolName)}`,
+    );
+    lines.push(...renderDecisionLines(decision));
+  });
+
+  if (warnings.length > 0) {
+    lines.push("", "## Audit source warnings");
+    for (const warning of warnings) {
+      lines.push(`- ${warning}`);
+    }
+  }
+
+  return lines.join("\n");
+}
+
+function renderDecisionLines(decision: RecentDecisionEntry): readonly string[] {
+  const lines = [
+    `- Tool: ${inlineCodeOrNotRecorded(decision.toolName)}`,
+    ...renderInputLines(decision),
+    `- Effect: ${inlineCodeOrNotRecorded(decision.effect)}`,
+    `- Reason: ${valueOrNotRecorded(decision.reason)}`,
+    `- Rule id: ${inlineCodeOrNotRecorded(decision.provenance?.ruleId)}`,
+    `- Pack: ${inlineCodeOrNotRecorded(decision.provenance?.packId)}`,
+    `- Provenance: ${inlineCodeOrNotRecorded(decision.provenance?.source)}`,
+    `- Reviewer original outcome: ${formatOutcome(
+      decision.originalEffect,
+      decision.originalReason,
+    )}`,
+    `- Reviewer final outcome: ${formatOutcome(
+      decision.finalEffect,
+      decision.finalReason,
+    )}`,
+    `- Reviewer source: ${inlineCodeOrNotRecorded(
+      decision.reviewerDecisionSource,
+    )}`,
+    `- Reviewer model: ${formatReviewerModel(decision)}`,
+  ];
+
+  if (decision.reviewerModelSource !== undefined) {
+    lines.push(
+      `- Reviewer model source: ${inlineCodeOrNotRecorded(
+        decision.reviewerModelSource,
+      )}`,
+    );
+  }
+  if (decision.reviewerModelNote !== undefined) {
+    lines.push(
+      `- Reviewer model note: ${valueOrNotRecorded(decision.reviewerModelNote)}`,
+    );
+  }
+  if (decision.reviewerMode !== undefined) {
+    lines.push(
+      `- Reviewer path: ${inlineCodeOrNotRecorded(decision.reviewerMode)}`,
+    );
+  }
+
+  // Debug surface: the parsed shape lives here, never in approval cards.
+  if (decision.shape !== undefined) {
+    lines.push(
+      "",
+      "### Parsed shape (debug)",
+      "",
+      markdownJsonBlock(formatJsonBlock(decision.shape)),
+    );
+  }
+
+  return lines;
+}
+
+function formatJsonBlock(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2) ?? String(value);
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+function markdownJsonBlock(value: string): string {
+  const longestFence = Math.max(
+    0,
+    ...Array.from(value.matchAll(/`+/gu), (match) => match[0]?.length ?? 0),
+  );
+  const fence = "`".repeat(Math.max(3, longestFence + 1));
+  return [`${fence}json`, value, fence].join("\n");
+}
+
+function renderInputLines(decision: RecentDecisionEntry): readonly string[] {
+  if (decision.command !== undefined) {
+    return [`- Command: ${inlineCode(decision.command)}`];
+  }
+
+  if (decision.toolInput !== undefined) {
+    return [`- Tool input: ${inlineCode(formatToolInput(decision.toolInput))}`];
+  }
+
+  return ["- Command/input: not recorded"];
+}
+
+function formatOutcome(
+  effect: string | undefined,
+  reason: string | undefined,
+): string {
+  if (effect === undefined) return NOT_RECORDED;
+  const effectText = inlineCode(effect);
+  return reason === undefined
+    ? effectText
+    : `${effectText} — ${valueOrNotRecorded(reason)}`;
+}
+
+function formatReviewerModel(decision: RecentDecisionEntry): string {
+  if (decision.reviewerModel === undefined) return NOT_RECORDED;
+  return inlineCode(
+    `${decision.reviewerModel.provider}/${decision.reviewerModel.id}`,
+  );
+}
+
+function valueOrNotRecorded(value: string | undefined): string {
+  return value === undefined || value.length === 0 ? NOT_RECORDED : value;
+}
+
+function inlineCodeOrNotRecorded(value: string | undefined): string {
+  return value === undefined || value.length === 0
+    ? NOT_RECORDED
+    : inlineCode(value);
+}
+
+function inlineCode(value: string): string {
+  return `\`${value.replaceAll("`", "\\`")}\``;
+}
+
+function formatToolInput(value: unknown): string {
+  if (typeof value === "string") return value;
+
+  try {
+    const text = JSON.stringify(value);
+    return text === undefined ? NOT_RECORDED : text;
+  } catch {
+    return NOT_RECORDED;
+  }
+}

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

@@ -0,0 +1,49 @@
+const DURATION_UNITS = {
+  h: 60 * 60 * 1000,
+  m: 60 * 1000,
+  s: 1000,
+} as const satisfies Record<string, number>;
+
+/**
+ * Parse a compact duration string ("10m", "2h", "45s", "1h30m") to ms.
+ *
+ * The runtime keeps duration strings schema-light so user config can stay readable across
+ * reviewer features. Invalid input returns undefined and lets each caller choose its own
+ * safe fallback.
+ */
+export function parseDurationToMs(input: string): number | undefined {
+  const text = input.trim().toLowerCase();
+  if (text.length === 0) return undefined;
+
+  let index = 0;
+  let matched = false;
+  let total = 0;
+
+  while (index < text.length) {
+    while (index < text.length && /\s/u.test(text[index] ?? "")) {
+      index += 1;
+    }
+    if (index >= text.length) break;
+
+    const match = /^(\d+)\s*([hms])/.exec(text.slice(index));
+    if (match === null) return undefined;
+
+    const amountText = match[1];
+    const unit = match[2] as keyof typeof DURATION_UNITS | undefined;
+    if (amountText === undefined || unit === undefined) return undefined;
+
+    const amount = Number(amountText);
+    if (!Number.isSafeInteger(amount)) return undefined;
+
+    const addition = amount * DURATION_UNITS[unit];
+    total += addition;
+    if (!Number.isSafeInteger(addition) || !Number.isSafeInteger(total)) {
+      return undefined;
+    }
+
+    matched = true;
+    index += match[0].length;
+  }
+
+  return matched ? total : undefined;
+}