@nklisch/pi-enhanced 0.1.0

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

@@ -0,0 +1,38 @@
+import { mkdirSync } from "node:fs";
+import path from "node:path";
+
+import {
+  type AuditLogSink,
+  createRotatingFileSink,
+  noopAuditSink,
+} from "../audit/sink.ts";
+import { resolveUserConfigRoot } from "../config/paths.ts";
+
+export interface DefaultAuditSinkOptions {
+  /** Defaults to `resolveUserConfigRoot()`. */
+  readonly userConfigRoot?: string;
+}
+
+export function defaultAuditLogPath(
+  userConfigRoot: string = resolveUserConfigRoot(),
+): string {
+  return path.join(userConfigRoot, "audit.log");
+}
+
+export function createDefaultAuditSink(
+  options: DefaultAuditSinkOptions = {},
+): AuditLogSink {
+  const userConfigRoot = options.userConfigRoot ?? resolveUserConfigRoot();
+  const logPath = defaultAuditLogPath(userConfigRoot);
+
+  try {
+    mkdirSync(userConfigRoot, { recursive: true });
+  } catch {
+    // Audit logging must not affect runtime command decisions. If the user
+    // config directory is unavailable, fall back to a no-op sink instead of
+    // letting filesystem state change approval behavior.
+    return noopAuditSink;
+  }
+
+  return createRotatingFileSink({ path: logPath });
+}

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

@@ -0,0 +1,95 @@
+import type { TokenUsage } from "./reviewer.ts";
+
+export interface TokenBudgetConfig {
+  readonly window: string;
+  readonly limit: number | null;
+}
+
+export interface BudgetCheckResult {
+  readonly exhausted: boolean;
+  readonly cumulative: number;
+  readonly remaining: number | null;
+}
+
+/** Port: the runtime decision path depends on this interface, not the implementation. */
+export interface ReviewerTokenBudgetGate {
+  /** True iff budget is active and cumulative in-window usage >= limit. */
+  isExhausted(config: TokenBudgetConfig): boolean;
+  /** Account a completed call's usage. No-op when limit === null. */
+  record(usage: TokenUsage, config: TokenBudgetConfig): void;
+}
+
+/**
+ * Default window used when config.window is unparseable.
+ *
+ * A typo should keep the configured budget functional rather than silently making model
+ * review unlimited.
+ */
+export const DEFAULT_TOKEN_BUDGET_WINDOW_MS = 24 * 60 * 60 * 1000;
+
+export interface ReviewerTokenBudgetGateOptions {
+  /**
+   * Injected so this module stays pure and independent of the shared duration-parser
+   * module. Production wires parseDurationToMs at the composition root.
+   */
+  readonly parseDuration: (window: string) => number | undefined;
+  readonly clock?: () => number;
+}
+
+interface TokenBudgetEntry {
+  readonly ts: number;
+  readonly tokens: number;
+}
+
+export function createReviewerTokenBudgetGate(
+  options: ReviewerTokenBudgetGateOptions,
+): ReviewerTokenBudgetGate {
+  const entries: TokenBudgetEntry[] = [];
+  const windowCache = new Map<string, number>();
+  const clock = options.clock ?? (() => Date.now());
+
+  const windowMsFor = (config: TokenBudgetConfig): number => {
+    const cached = windowCache.get(config.window);
+    if (cached !== undefined) return cached;
+
+    const parsed =
+      options.parseDuration(config.window) ?? DEFAULT_TOKEN_BUDGET_WINDOW_MS;
+    windowCache.set(config.window, parsed);
+    return parsed;
+  };
+
+  const prune = (now: number, windowMs: number): void => {
+    const cutoff = now - windowMs;
+    let writeIndex = 0;
+
+    for (const entry of entries) {
+      if (entry.ts >= cutoff) {
+        entries[writeIndex] = entry;
+        writeIndex += 1;
+      }
+    }
+
+    entries.length = writeIndex;
+  };
+
+  const cumulative = (): number =>
+    entries.reduce((sum, entry) => sum + entry.tokens, 0);
+
+  return {
+    isExhausted(config) {
+      if (config.limit === null) return false;
+
+      const now = clock();
+      prune(now, windowMsFor(config));
+      return cumulative() >= config.limit;
+    },
+
+    record(usage, config) {
+      if (config.limit === null) return;
+
+      const now = clock();
+      entries.push({ ts: now, tokens: Math.max(0, usage.totalTokens) });
+      prune(now, windowMsFor(config));
+    },
+  };
+}

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

@@ -0,0 +1,259 @@
+/**
+ * Command transform registration — v1 event contract.
+ *
+ * An installed Pi extension that wants to rewrite a `bash` command **after**
+ * pi-clearance has approved it (so the auto-reviewer still judges the
+ * command the agent typed) registers a transform here. This is the
+ * load-order-independent coordination channel between the auto-reviewer and a
+ * command rewriter such as RTK output compression.
+ *
+ * ## Why this exists
+ *
+ * Pi mutates `tool_call` event handlers in load order on a single shared
+ * `event.input.command` object, and the bash executor reads `command` from
+ * that same object at execution time. So both a reviewer and a rewriter must
+ * act in the `tool_call` window on the same field — whoever loads first wins.
+ * Without this contract, a rewriter loaded before the reviewer would mutate
+ * the command before the reviewer saw it, so the reviewer would judge the
+ * *rewritten* form rather than what the agent typed.
+ *
+ * This contract inverts that: **pi-clearance owns the only `tool_call`
+ * handler.** It captures the original command up front (the reviewer always
+ * sees the original), and on the `allow` branch it runs every registered
+ * transform against the original command, then writes the final result back
+ * to `event.input.command`. Rewriters register via `pi.events` instead of
+ * racing on `tool_call`, so package-vs-global load rank no longer matters.
+ *
+ * A rewriter registers by listening for
+ * {@link AUTO_REVIEWER_TRANSFORMS_REQUEST_EVENT} on the Pi event bus and
+ * emitting {@link AUTO_REVIEWER_TRANSFORMS_REGISTER_EVENT} with an
+ * {@link AutoReviewerTransformRegistration} payload whose `transform` is an
+ * async function. The request is emitted on `session_start` (after all
+ * extension factories have loaded, so a contributor that registers during its
+ * own factory is captured regardless of load order).
+ *
+ * ## Safety model
+ *
+ * - Transforms run **only after** an `allow` decision (deterministic or model
+ *   review). A blocked/denied command is never transformed.
+ * - A transform returns `{ command }` to replace the command, `{ skipped }`
+ *   to opt out for this call, or `{ error }` to fail open (the prior command
+ *   runs unchanged).
+ * - Transforms compose in registration order: each transform sees the evolving
+ *   command (the prior transform's output, or the original for the first).
+ *   The final command is what runs. (Composition semantics may evolve; v1
+ *   keeps it simple and deterministic.)
+ * - The contract is total: `normalizeCommandTransformRegistration` never
+ *   throws on adversarial input — a malformed payload contributes nothing and
+ *   records an issue.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+/**
+ * Stable API version for the v1 command-transform contract. Payloads with a
+ * different `apiVersion` are rejected by the normalizer rather than interpreted.
+ */
+export const AUTO_REVIEWER_TRANSFORMS_API_VERSION = 1 as const;
+
+/**
+ * Event the core extension emits on session_start to request transform
+ * registrations from contributor extensions.
+ */
+export const AUTO_REVIEWER_TRANSFORMS_REQUEST_EVENT =
+  "pi-clearance:transforms:request" as const;
+
+/**
+ * Event a contributor emits in response to a request (or unsolicited) carrying
+ * an {@link AutoReviewerTransformRegistration} payload.
+ */
+export const AUTO_REVIEWER_TRANSFORMS_REGISTER_EVENT =
+  "pi-clearance:transforms:register" as const;
+
+/** Request payload for {@link AUTO_REVIEWER_TRANSFORMS_REQUEST_EVENT}. */
+export interface AutoReviewerTransformsRequest {
+  readonly apiVersion: 1;
+  readonly requestId: string;
+  readonly reason: "startup" | "reload" | "manual";
+}
+
+/**
+ * The transform function a contributor registers. It receives the command
+ * (the original for the first transform, or the prior transform's output for
+ * later ones) and the extension context, and returns one of:
+ * - `{ command }` — replace the command that will run.
+ * - `{ skipped }` — opt out for this call; the prior command is preserved.
+ * - `{ error }` — fail open; the prior command is preserved and the error is
+ *   surfaced to the transform's last-status (the contributor is responsible
+ *   for surfacing it, e.g. via a `/rtk`-style status command).
+ *
+ * The function must be resilient to an abort signal (via `ctx.signal`) and
+ * must not throw synchronously; pi-clearance wraps calls in try/catch and
+ * treats a throw as `{ error }`.
+ */
+export type CommandTransformFn = (
+  command: string,
+  ctx: ExtensionContext,
+) => Promise<CommandTransformResult>;
+
+/** Result of a single transform invocation. */
+export interface CommandTransformResult {
+  /** Replacement command. Omit to preserve the prior command. */
+  readonly command?: string;
+  /** Human-readable reason this transform did not apply. Display only. */
+  readonly skipped?: string;
+  /** Failure reason. The prior command is preserved. Display only. */
+  readonly error?: string;
+}
+
+/** Full registration payload for {@link AUTO_REVIEWER_TRANSFORMS_REGISTER_EVENT}. */
+export interface AutoReviewerTransformRegistration {
+  readonly apiVersion: 1;
+  /** Echo the request id when responding to a collect; omit for unsolicited. */
+  readonly requestId?: string;
+  /** Stable id for the contributor (e.g. "pi-config:rtk-rewrite"). */
+  readonly id: string;
+  /** Human-readable description shown in status/diagnostics. */
+  readonly description?: string;
+  /** The transform function. Required. */
+  readonly transform: CommandTransformFn;
+}
+
+/**
+ * A validated transform ready to run. The normalizer attaches a stable id and
+ * description; the transform function is the contributor's, unmodified.
+ */
+export interface NormalizedCommandTransform {
+  readonly id: string;
+  readonly description: string;
+  readonly transform: CommandTransformFn;
+}
+
+/** A structured registration issue. */
+export interface CommandTransformIssue {
+  readonly severity: "warning" | "error";
+  readonly code: string;
+  readonly path: string;
+  readonly message: string;
+}
+
+/** Result of normalizing a registration payload. */
+export interface CommandTransformRegistrationResult {
+  readonly transform: NormalizedCommandTransform | null;
+  readonly issues: readonly CommandTransformIssue[];
+}
+
+/**
+ * Normalize an untrusted transform-registration payload into a validated
+ * transform (or null) plus structured issues. Total: never throws.
+ *
+ * A valid payload has `apiVersion === 1`, a non-empty string `id`, and a
+ * function `transform`. A missing or non-function `transform` is an error
+ * (there is nothing to register without one).
+ */
+export function normalizeCommandTransformRegistration(
+  registration: unknown,
+): CommandTransformRegistrationResult {
+  try {
+    return normalizeRegistration(registration);
+  } catch (error) {
+    return {
+      transform: null,
+      issues: [
+        {
+          severity: "error",
+          code: "normalizer-error",
+          path: "$",
+          message: `normalizer error: ${
+            error instanceof Error ? error.message : "unknown error"
+          }`,
+        },
+      ],
+    };
+  }
+}
+
+function normalizeRegistration(
+  registration: unknown,
+): CommandTransformRegistrationResult {
+  const issues: CommandTransformIssue[] = [];
+
+  if (!isRecord(registration)) {
+    issues.push(
+      issue({
+        severity: "error",
+        code: "invalid-registration",
+        path: "$",
+        message: "expected registration object",
+      }),
+    );
+    return { transform: null, issues };
+  }
+
+  if (registration.apiVersion !== AUTO_REVIEWER_TRANSFORMS_API_VERSION) {
+    issues.push(
+      issue({
+        severity: "error",
+        code: "invalid-api-version",
+        path: "$.apiVersion",
+        message: `expected apiVersion ${AUTO_REVIEWER_TRANSFORMS_API_VERSION}`,
+      }),
+    );
+    // Unknown payload version has undefined semantics; do not interpret it.
+    return { transform: null, issues };
+  }
+
+  if (!isNonEmptyString(registration.id)) {
+    issues.push(
+      issue({
+        severity: "error",
+        code: "missing-id",
+        path: "$.id",
+        message: "expected non-empty transform id",
+      }),
+    );
+    return { transform: null, issues };
+  }
+
+  if (typeof registration.transform !== "function") {
+    issues.push(
+      issue({
+        severity: "error",
+        code: "missing-transform",
+        path: "$.transform",
+        message: "expected transform function",
+      }),
+    );
+    return { transform: null, issues };
+  }
+
+  const description =
+    typeof registration.description === "string"
+      ? registration.description
+      : registration.id;
+
+  const normalized: NormalizedCommandTransform = {
+    id: registration.id,
+    description,
+    transform: registration.transform as CommandTransformFn,
+  };
+
+  return { transform: normalized, issues };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptyString(value: unknown): value is string {
+  return typeof value === "string" && value.length > 0;
+}
+
+function issue(params: {
+  readonly severity: "warning" | "error";
+  readonly code: string;
+  readonly path: string;
+  readonly message: string;
+}): CommandTransformIssue {
+  return { ...params };
+}

package/node_modules/@nklisch/pi-clearance/src/skill/clearance-pack-authoring/SKILL.md

@@ -0,0 +1,51 @@
+---
+name: clearance-pack-authoring
+description: >
+  Agent-facing guide for authoring Pi Clearance data packs, core matcher design inputs,
+  and package-distributed pack collections. Use it when building or reviewing packs so
+  agents validate/replay changes and preserve install-versus-enable separation before any
+  user-owned enablement write.
+---
+
+# Clearance Pack Authoring
+
+Use this skill when the user wants to write, review, package, or explain
+Pi Clearance packs.
+
+This is a thin workflow guide. Do not copy matcher catalogs, config schemas, package
+registration payloads, or long validation rules into the conversation. Read the canonical
+docs first and point future agents back to them.
+
+## Read first
+
+1. [PACK_AUTHORING.md](../../../docs/PACK_AUTHORING.md) — canonical workflow for data packs,
+   core matcher design inputs, and package-distributed collections.
+2. [CONFIGURATION.md](../../../docs/CONFIGURATION.md) — user-owned `packs` and
+   `packEnablement` config shape.
+3. [RATCHET.md](../../../docs/RATCHET.md) — proposal cards, replay evidence, approval, and
+   writer boundaries.
+
+## Required boundaries
+
+- Prefer data packs. If the JSON matcher DSL can express the policy, use it instead of
+  executable code.
+- Installing a Pi package makes package packs available in the registry. It does not enable
+  them or relax policy.
+- Package pack enablement is a separate user-owned config action through
+  `packEnablement.enabledPackagePacks` or the Pi pack command workflow.
+- Trusted TypeScript rule modules are cut. They are never discovered, loaded, or enabled;
+  use inspectable data packs or record a core matcher design input instead.
+- sealed-floor validation, Replay/validation, and user approval precede any write that broadens
+  user-owned policy.
+
+## Workflow
+
+1. Start from repeated history or a clear package authoring request.
+2. Check whether a shipped or package-contributed pack already fits.
+3. If authoring is needed, draft the smallest data pack first.
+4. If the DSL cannot express a reusable need, propose a core matcher/design input rather than
+   jumping straight to TypeScript.
+5. Show validation results, replay impact, warnings, exact diffs or enablement patches, and
+   required acknowledgments before asking the user to approve a write.
+7. Keep package distribution docs and skills thin; link to `docs/PACK_AUTHORING.md` as the
+   source of truth.

package/node_modules/@nklisch/pi-clearance/src/skill/clearance-tune/SKILL.md

@@ -0,0 +1,112 @@
+---
+name: clearance-tune
+description: >
+  Agent-facing workflow for reducing Pi Clearance review friction through
+  Pi-native Tune mode. The always-on clearance_propose/clearance_present flow
+  accepts drafts and owns the approval card; Tune turns on temporary clearance_*
+  analysis tools to inspect captured history, size and validate batches, and
+  present them through the same card. The helper CLI is internal test/debug
+  plumbing, not the approval path.
+---
+
+# Clearance Tune
+
+Use this skill when the user wants to reduce repeated Pi Clearance review
+prompts, tune policy or reviewer config from captured command history, or
+inspect replay evidence for a proposed change.
+
+Tune mode is an approval workflow, not an auto-apply workflow. Runtime reviewer
+decisions and model-authored suggestions are evidence only. They become policy
+or reviewer configuration only after the user sees the exact proposal card,
+approves it through Pi UI, and the write-time validator accepts it.
+
+## Read first
+
+1. [TUNE.md](../../../docs/TUNE.md) — Tune workflow, proposal cards, replay
+   evidence, approval, and writer boundaries.
+2. [PACK_AUTHORING.md](../../../docs/PACK_AUTHORING.md) — inspectable data packs,
+   core matcher gaps, and package-distributed collections.
+3. [CONFIGURATION.md](../../../docs/CONFIGURATION.md) — user-owned `packs` and
+   reviewer config shape.
+
+## Turning Tune mode on and off
+
+Tune analysis tools are temporary. They are hidden outside Tune mode; the
+always-on `clearance_propose` and `clearance_present` tools remain active.
+
+- `/clearance tune` — toggle Tune mode on or off. When on, Pi snapshots the
+  current active tools and exposes the Tune analysis tools for this session.
+  Invoke it again when the pass is done so temporary analysis tools do not
+  linger.
+
+## Required workflow
+
+1. `/clearance tune` to activate Tune mode.
+2. Call `clearance_status` first to read Tune mode, baseline packs, reviewer
+   configuration, project trust, pack counts, and current warnings.
+3. Call `clearance_list_history_families` to inspect captured command history by
+   structured family, replay status, captured outcome, source, and evidence
+   fidelity. Use `clearance_list_packs` when pack enablement or pack source
+   context is relevant to the change.
+4. Call `clearance_generate_proposals` to draft a bounded structured proposal
+   batch from the captured history. Generation caches the in-memory batch and
+   never writes config or policy.
+5. For each proposal in the batch:
+   - `clearance_show_proposal` to read the exact structured proposal and its
+     proposal-card markdown.
+   - `clearance_replay_proposal` to dry-run the proposal across captured history
+     without executing commands and attach the structured replay delta.
+   - For candidate allow rules, `clearance_adversarial_cases` to stress-test the
+     proposal with adversarial near-miss cases.
+   - `clearance_validate_pack` to collect ordered validation slots, filling any
+     missing replay or adversarial evidence in the in-memory cache.
+6. Present the shared batch through `clearance_present`. It fills evidence,
+   renders the summary-first card, and collects approve-all or per-family
+   accept / reject / skip decisions. On explicit approval only, it validates
+   and writes approved user-owned config through the existing writer seams. Do
+   not write config or policy files directly as a substitute for presentation.
+7. `/clearance tune` again when the Tune pass is complete.
+
+## Approval and write boundary
+
+`clearance_present` is the only approval and write path. On explicit approval, it
+writes only user-owned config:
+
+- global config: `global.json` under Pi Clearance's user config root;
+- per-project overlay: `projects/<project-key>/overlay.json` under that same
+  root.
+
+It never writes shipped packs, repository policy, executable rule modules, or
+package source code. Shipped-pack and `core-matcher` proposals route to markdown
+design-input artifacts instead of writing code or config. Write-time validation
+rebuilds and schema-validates the
+target JSON and re-runs the effective-policy composer so sealed-floor overlap is
+caught at write time; a rejected write leaves no target file or backup behind.
+
+Project-targeted writes may still wait for Pi's project-trust signal before
+project-local policy or prompt appends take effect. Tune mode does not create a
+local trust record.
+
+## Safety reminders
+
+- Show before approve. Approval happens through `clearance_present` in Pi UI,
+  not by writing files directly. With no corpus, only the human may choose the
+  separately labeled approve-without-replay-evidence action.
+- Size the batch to the evidence and safety profile; mode suggestions are allowed, but initial runs can be larger
+  than later runs, but every change must still be shown and approved.
+- Treat allow expansions as asymmetric risk: a command observed as safe once is
+  not proof it is always safe. Replay and adversarial cases exist to surface
+  near-miss regressions before approval.
+- If validation reports a hard regression, stop and report it; do not keep tuning
+  wider policy on top of it.
+
+## Debugging fallback (not the approval path)
+
+The shipped product workflow is Tune mode plus the `clearance_*` tools.
+Maintainers may exercise the internal `runRatchetCli()` harness in
+`src/skill/clearance-tune/cli.ts` (or the optional
+`scripts/dev/pi-clearance-tune.cjs` wrapper) for focused replay, presentation,
+write-plan, and verification debugging. That harness is not installed as a
+package executable, structured proposal objects remain the source of truth, and
+its `apply` seam is internal-only — it is not the user approval path and must not
+be presented as such.