@nklisch/pi-enhanced 0.1.0

package/node_modules/@nklisch/pi-clearance/src/runtime/human-review-card.ts

@@ -0,0 +1,278 @@
+/**
+ * Human review card — plain-language rendering of a tool call under review.
+ *
+ * The approval surface answers three questions in prose: what the command
+ * does, where it acts, and (via the policy reason) why the operator is being
+ * asked. Raw tool input and the parsed shape JSON are debug material and
+ * live behind `/clearance why`, never in an approval dialog.
+ *
+ * Copy philosophy: lead with the safety-relevant verb and effect class
+ * ("Searches file contents — read-only"), not with parser vocabulary. A
+ * program-specific verb map covers the common cases; everything else falls
+ * back to the effect class so unrecognized programs are described by what
+ * they can do, not by an empty label.
+ */
+
+import type { PathScope } from "../contracts/PathScope.ts";
+import { classifyStageEffect } from "../parse/native-effects.ts";
+import type { BashStage, ToolShape } from "../parse/shape.ts";
+import { markdownCodeSpan } from "./markdown.ts";
+
+export interface HumanReviewCard {
+  /** Prose bullets describing behavior; always at least one entry. */
+  readonly whatItDoes: readonly string[];
+  /** Prose bullets for touched paths; empty when no path facts exist. */
+  readonly whereItActs: readonly string[];
+}
+
+const MAX_BEHAVIOR_BULLETS = 3;
+const MAX_PATH_BULLETS = 4;
+
+export function buildHumanReviewCard(shape: ToolShape): HumanReviewCard {
+  switch (shape.kind) {
+    case "bash":
+      return {
+        whatItDoes: bashBehavior(shape.stages),
+        whereItActs: pathBullets(shape.pathFacts?.facts ?? []),
+      };
+    case "pi-tool":
+      return {
+        whatItDoes: [describePiTool(shape)],
+        whereItActs: pathBulletsFromToolFacts(shape),
+      };
+    case "unknown":
+      return {
+        whatItDoes: [
+          `Runs the ${shape.toolName} tool, which Clearance could not analyze`,
+        ],
+        whereItActs: [],
+      };
+  }
+}
+
+/**
+ * Operation-specific Pi tool descriptions. Non-mutation is NOT synonymous
+ * with read-only: agent-dispatch and embedded-shell can do anything, and
+ * interactive tools wait on the user. Unknown operations stay conservative.
+ */
+function describePiTool(
+  shape: Extract<ToolShape, { readonly kind: "pi-tool" }>,
+): string {
+  switch (shape.operation) {
+    case "read-file":
+    case "list-directory":
+    case "find-files":
+    case "search-file-contents":
+    case "status-read":
+    case "state-read":
+    case "workspace-search":
+      return `Uses the Pi ${shape.toolName} tool (read-only)`;
+    case "mutation":
+      return `Uses the Pi ${shape.toolName} tool (modifies files)`;
+    case "embedded-shell":
+      return `Uses the Pi ${shape.toolName} tool, which runs shell commands (effects classified by the inner command)`;
+    case "agent-dispatch":
+      return `Uses the Pi ${shape.toolName} tool, which dispatches an agent that can run its own tool calls`;
+    case "interactive":
+      return `Uses the Pi ${shape.toolName} tool (asks you interactively)`;
+    case "network-read":
+      return `Uses the Pi ${shape.toolName} tool (network read)`;
+    default:
+      return `Uses the Pi ${shape.toolName} tool (effects could not be classified)`;
+  }
+}
+
+/** Human scope labels; the vocabulary is location + trust, not config keys. */
+const SCOPE_LABELS: Readonly<Record<PathScope, string>> = {
+  "writable-project": "project (writable)",
+  project: "project",
+  temp: "temporary directory",
+  home: "home, outside project",
+  "safe-home": "home (approved directory)",
+  "sensitive-home": "home (sensitive)",
+  "agent-support": "agent support directory",
+  system: "system path",
+  outside: "outside the project",
+  denied: "denied by your configuration",
+  unknown: "location could not be determined",
+};
+
+function bashBehavior(stages: readonly BashStage[]): readonly string[] {
+  if (stages.length === 0) return ["Runs a shell command"];
+  const bullets: string[] = [];
+  let remaining = 0;
+
+  for (const [index, stage] of stages.entries()) {
+    if (bullets.length >= MAX_BEHAVIOR_BULLETS) {
+      remaining = stages.length - index;
+      break;
+    }
+    bullets.push(describeStage(stage));
+  }
+
+  if (remaining > 0) bullets.push(`…and ${remaining} more`);
+  return bullets;
+}
+
+function describeStage(stage: BashStage): string {
+  switch (stage.kind) {
+    case "command":
+      return describeCommandStage(stage);
+    case "subshell":
+      return "Runs a subshell";
+    case "control-flow":
+      return `Uses ${CONTROL_FLOW_NOUNS[stage.construct] ?? `the ${stage.construct} shell construct`}, which Clearance does not model`;
+    case "for-loop":
+      return `Runs a for loop (${describeBodyPrograms(stage.body.pipeline.stages)})`;
+    case "brace-group":
+      return `Runs a command group (${describeBodyPrograms(stage.body.pipeline.stages)})`;
+    case "conditional": {
+      const bodyPrograms = stage.arms
+        .flatMap((arm) =>
+          arm.body.pipeline.stages.map((body) =>
+            body.kind === "command" ? body.program.program : null,
+          ),
+        )
+        .filter((program): program is string => program !== null);
+      const suffix =
+        bodyPrograms.length === 0
+          ? ""
+          : ` (${bodyPrograms.slice(0, 3).join(", ")}${bodyPrograms.length > 3 ? `, +${bodyPrograms.length - 3} more` : ""})`;
+      return `Runs a conditional (if/then)${suffix}`;
+    }
+    case "unsupported":
+      return `Could not be fully parsed (${stage.reason})`;
+  }
+}
+
+function describeBodyPrograms(stages: readonly BashStage[]): string {
+  const programs = stages
+    .map((stage) => (stage.kind === "command" ? stage.program.program : null))
+    .filter((program): program is string => program !== null);
+  if (programs.length === 0) return "no direct commands";
+  const shown = programs.slice(0, 3).join(", ");
+  return programs.length > 3
+    ? `body: ${shown}, +${programs.length - 3} more`
+    : `body: ${shown}`;
+}
+
+/** Program-specific verbs for the commands that dominate review traffic. */
+const PROGRAM_VERBS: Readonly<Record<string, string>> = {
+  grep: "Searches file contents",
+  rg: "Searches file contents",
+  find: "Finds files",
+  ls: "Lists directory contents",
+  cat: "Prints file contents",
+  head: "Prints the start of files",
+  tail: "Prints the end of files",
+  sed: "Transforms text",
+  awk: "Processes text",
+  jq: "Queries JSON",
+  sort: "Sorts lines",
+  wc: "Counts lines/words",
+  diff: "Compares files",
+  rm: "Deletes files",
+  rmdir: "Deletes directories",
+  mv: "Moves or renames files",
+  cp: "Copies files",
+  mkdir: "Creates directories",
+  touch: "Creates or updates file timestamps",
+  curl: "Makes a network request",
+  wget: "Downloads from the network",
+  ssh: "Opens a remote shell",
+  git: "Runs git",
+  node: "Runs Node.js",
+  python: "Runs Python",
+  python3: "Runs Python",
+  sqlite3: "Runs SQLite",
+};
+
+const CONTROL_FLOW_NOUNS: Readonly<Record<string, string>> = {
+  while: "a while loop",
+  until: "an until loop",
+  case: "a case statement",
+  select: "a select menu",
+  function: "a function definition",
+  if: "an if conditional",
+  for: "a for loop",
+  "brace-group": "a brace group",
+};
+
+const EFFECT_FALLBACKS = {
+  "read-only": "read-only",
+  write: "modifies files",
+  destructive: "destructive",
+  network: "network access",
+  "shell-wrap": "wraps another command",
+  // "unknown" means the program is parsed but absent from the effect
+  // registry — say that, not "unrecognized", which implies we don't know
+  // what the program is (git push, pnpm install land here).
+  unknown: "no effect classification",
+} as const;
+
+function describeCommandStage(
+  stage: Extract<BashStage, { readonly kind: "command" }>,
+): string {
+  const program = stage.program.program;
+  const effect = classifyStageEffect(stage);
+  const effectLabel = EFFECT_FALLBACKS[effect.class];
+  const verb = PROGRAM_VERBS[program];
+
+  const traits: string[] = [];
+  if (stage.substitutions.length > 0) traits.push("uses command substitution");
+  const traitSuffix = traits.length === 0 ? "" : `; ${traits.join("; ")}`;
+
+  if (verb === undefined) {
+    return `Runs ${markdownCodeSpan(program)} (${effectLabel})${traitSuffix}`;
+  }
+  const object = program === "git" ? (firstGitSubcommand(stage) ?? "") : "";
+  return `${verb} ${object}(${effectLabel})${traitSuffix}`;
+}
+
+/** Leading git options that consume a value; skip them to find the subcommand. */
+const GIT_VALUE_OPTIONS = new Set([
+  "-C",
+  "-c",
+  "--git-dir",
+  "--work-tree",
+  "--namespace",
+  "--exec-path",
+]);
+
+function firstGitSubcommand(
+  stage: Extract<BashStage, { readonly kind: "command" }>,
+): string | undefined {
+  const args = stage.program.arguments;
+  for (let index = 0; index < args.length; index += 1) {
+    const argument = args[index];
+    if (argument === undefined) return undefined;
+    if (GIT_VALUE_OPTIONS.has(argument)) {
+      index += 1; // skip the option's value
+      continue;
+    }
+    if (argument.startsWith("-")) continue;
+    return `${argument} `;
+  }
+  return undefined;
+}
+
+function pathBullets(
+  facts: readonly { readonly raw: string; readonly scope: PathScope }[],
+): readonly string[] {
+  if (facts.length === 0) return [];
+  const bullets = facts
+    .slice(0, MAX_PATH_BULLETS)
+    .map(
+      (fact) => `${markdownCodeSpan(fact.raw)} — ${SCOPE_LABELS[fact.scope]}`,
+    );
+  if (facts.length > MAX_PATH_BULLETS) {
+    bullets.push(`…and ${facts.length - MAX_PATH_BULLETS} more paths`);
+  }
+  return bullets;
+}
+
+function pathBulletsFromToolFacts(
+  shape: Extract<ToolShape, { readonly kind: "pi-tool" }>,
+): readonly string[] {
+  return pathBullets(shape.pathFacts?.facts ?? []);
+}

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

@@ -0,0 +1,13 @@
+/**
+ * Markdown-safe inline code span. Raw commands and paths are untrusted text:
+ * when they contain backticks, a single-backtick span breaks the card.
+ */
+export function markdownCodeSpan(value: string): string {
+  if (!value.includes("`")) return `\`${value}\``;
+  const longest = Math.max(
+    1,
+    ...Array.from(value.matchAll(/`+/gu), (match) => match[0].length),
+  );
+  const fence = "`".repeat(longest + 1);
+  return `${fence} ${value} ${fence}`;
+}

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

@@ -0,0 +1,47 @@
+import type {
+  BeforeAgentStartEvent,
+  BeforeAgentStartEventResult,
+  ExtensionHandler,
+} from "@earendil-works/pi-coding-agent";
+
+import type { RatchetModeManager } from "./ratchet-mode.ts";
+
+const PROPOSAL_FLOW_GUIDANCE = [
+  "## Clearance proposal flow guidance",
+  "- Agent-authored policy batches are always available: call clearance_propose, then call clearance_present to show the deterministic summary card.",
+  "- Only an explicit user approval from the presented card may write user-owned config; never apply proposals or write policy directly.",
+].join("\n");
+
+function formatRatchetToolGuidance(toolNames: readonly string[]): string {
+  if (toolNames.length === 0) {
+    return "- No ratchet tools are registered yet.";
+  }
+
+  return `- Registered ratchet tools: ${toolNames.join(", ")}.`;
+}
+
+function buildRatchetModeGuidance(manager: RatchetModeManager): string {
+  const { ratchetToolNames } = manager.getStatus();
+
+  return [
+    "## Ratchet mode guidance",
+    "- Ratchet mode is active; ratchet-only analysis tools are temporarily available.",
+    formatRatchetToolGuidance(ratchetToolNames),
+    "- Prefer structured corpus, replay, and proposal tools over reading raw logs directly.",
+    "- Replay candidate changes across the full corpus before recommending them.",
+    "- Read docs/PACK_AUTHORING.md before authoring custom packs.",
+    "- Proposal writes require explicit Pi UI approval; do not write config or policy files directly as a substitute for proposal approval.",
+  ].join("\n");
+}
+
+export function createRatchetModePromptInjector(
+  manager: RatchetModeManager,
+): ExtensionHandler<BeforeAgentStartEvent, BeforeAgentStartEventResult> {
+  return (event) => ({
+    systemPrompt: [
+      event.systemPrompt,
+      ...(manager.isRatchetActive() ? [buildRatchetModeGuidance(manager)] : []),
+      PROPOSAL_FLOW_GUIDANCE,
+    ].join("\n\n"),
+  });
+}

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

@@ -0,0 +1,248 @@
+import type {
+  Api,
+  AssistantMessage,
+  Context,
+  Model,
+  SimpleStreamOptions,
+} from "@earendil-works/pi-ai";
+import { completeSimple } from "@earendil-works/pi-ai/compat";
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type {
+  ReviewerModelAdapter,
+  ReviewerModelResponse,
+} from "./reviewer.ts";
+import {
+  type ReviewerModelSource,
+  resolveReviewerModel,
+} from "./reviewer-model.ts";
+import { buildReviewerShapeSummary } from "./reviewer-shape-summary.ts";
+
+export const DEFAULT_REVIEWER_MAX_TOKENS = 512;
+
+export type PiModelInvoker = (
+  model: Model<Api>,
+  context: Context,
+  options: SimpleStreamOptions,
+) => Promise<AssistantMessage>;
+
+export interface PiModelAdapterOptions {
+  readonly maxTokens?: number;
+  readonly invokeModel?: PiModelInvoker;
+  /** Reads the current resolved reviewer.model spec per dispatch. */
+  readonly modelSpec?: () => string | null;
+}
+
+type ResolvedRequestAuth =
+  | {
+      readonly ok: true;
+      readonly apiKey?: string;
+      readonly headers?: Record<string, string | null>;
+      readonly env?: Record<string, string>;
+    }
+  | { readonly ok: false; readonly error: string };
+
+type ResolvedModelLabels = Required<
+  Pick<ReviewerModelResponse, "resolvedModel" | "resolvedModelSource">
+> &
+  Pick<ReviewerModelResponse, "resolvedModelNote">;
+
+/**
+ * LLM-backed auto-review adapter for one runtime `review` decision.
+ * This returns evidence for the current tool call only; it never writes policy.
+ */
+export function createPiModelAdapter(
+  ctx: ExtensionContext,
+  options: PiModelAdapterOptions = {},
+): ReviewerModelAdapter {
+  return {
+    kind: "model",
+    isAvailable: () =>
+      resolveReviewerModel({
+        registry: ctx.modelRegistry,
+        spec: options.modelSpec?.() ?? null,
+        fallback: ctx.model,
+      }).model !== undefined,
+    async review({ prompt, shape, signal }) {
+      const resolved = resolveReviewerModel({
+        registry: ctx.modelRegistry,
+        spec: options.modelSpec?.() ?? null,
+        fallback: ctx.model,
+      });
+      const model = resolved.model;
+      if (model === undefined) {
+        return { effect: "review", reason: "no model configured" };
+      }
+      const modelLabels = labelsForResolvedModel(
+        model,
+        resolved.source === "none" ? "fallback" : resolved.source,
+        resolved.note,
+      );
+
+      let auth: ResolvedRequestAuth;
+      try {
+        auth = await ctx.modelRegistry.getApiKeyAndHeaders(model);
+      } catch (error) {
+        return {
+          effect: "review",
+          reason: `model auth resolution failed: ${errorMessage(error)}`,
+          ...modelLabels,
+        };
+      }
+
+      if (!auth.ok) {
+        return {
+          effect: "review",
+          reason: `model auth not configured: ${auth.error}`,
+          ...modelLabels,
+        };
+      }
+
+      const context: Context = {
+        systemPrompt: prompt,
+        messages: [
+          {
+            role: "user",
+            content: [
+              "Review this parsed Pi tool-call shape.",
+              "",
+              "Shape summary:",
+              safeJson(buildReviewerShapeSummary(shape)),
+              "",
+              "Raw shape JSON:",
+              safeJson(shape),
+            ].join("\n"),
+            timestamp: Date.now(),
+          },
+        ],
+      };
+      const streamOptions: SimpleStreamOptions = {
+        maxTokens: options.maxTokens ?? DEFAULT_REVIEWER_MAX_TOKENS,
+        ...(signal === undefined ? {} : { signal }),
+        ...(auth.apiKey === undefined ? {} : { apiKey: auth.apiKey }),
+        ...(auth.headers === undefined ? {} : { headers: auth.headers }),
+        ...(auth.env === undefined ? {} : { env: auth.env }),
+      };
+
+      let assistant: AssistantMessage;
+      try {
+        assistant = await (options.invokeModel ?? completeSimple)(
+          model,
+          context,
+          streamOptions,
+        );
+      } catch (error) {
+        return {
+          effect: "review",
+          reason: `model auto-reviewer failed: ${errorMessage(error)}`,
+          ...modelLabels,
+        };
+      }
+
+      if (
+        assistant.stopReason === "error" ||
+        assistant.stopReason === "aborted" ||
+        assistant.errorMessage !== undefined
+      ) {
+        return {
+          effect: "review",
+          reason: `model auto-reviewer error: ${assistant.errorMessage ?? assistant.stopReason}`,
+          ...modelLabels,
+        };
+      }
+
+      const parsed = parseReviewerResponse(extractText(assistant.content));
+      if (parsed === undefined) {
+        return {
+          effect: "review",
+          reason: "model auto-reviewer returned invalid JSON",
+          ...modelLabels,
+        };
+      }
+
+      return {
+        effect: parsed.decision,
+        reason: parsed.reason,
+        usage: { totalTokens: assistant.usage.totalTokens },
+        ...modelLabels,
+      };
+    },
+  };
+}
+
+function labelsForResolvedModel(
+  model: Model<Api>,
+  source: Exclude<ReviewerModelSource, "none">,
+  note: string | undefined,
+): ResolvedModelLabels {
+  return {
+    resolvedModel: { provider: model.provider, id: model.id },
+    resolvedModelSource: source,
+    ...(note === undefined ? {} : { resolvedModelNote: note }),
+  };
+}
+
+function parseReviewerResponse(
+  text: string,
+):
+  | { readonly decision: "allow" | "deny"; readonly reason: string }
+  | undefined {
+  const trimmed = text.trim();
+  if (trimmed.length === 0) return undefined;
+
+  const parsed = parseJsonObject(trimmed);
+  if (!isRecord(parsed)) return undefined;
+
+  if (parsed.decision !== "allow" && parsed.decision !== "deny") {
+    return undefined;
+  }
+
+  if (typeof parsed.reason !== "string" || parsed.reason.trim().length === 0) {
+    return undefined;
+  }
+
+  return { decision: parsed.decision, reason: parsed.reason };
+}
+
+function parseJsonObject(text: string): unknown {
+  const direct = tryParseJson(text);
+  if (direct !== undefined) return direct;
+
+  const fenced = /```(?:json)?\s*([\s\S]*?)\s*```/i.exec(text);
+  if (fenced?.[1] !== undefined) return tryParseJson(fenced[1]);
+
+  return undefined;
+}
+
+function tryParseJson(text: string): unknown | undefined {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return undefined;
+  }
+}
+
+function extractText(content: AssistantMessage["content"]): string {
+  return content
+    .filter(
+      (part): part is { readonly type: "text"; readonly text: string } =>
+        part.type === "text",
+    )
+    .map((part) => part.text)
+    .join("");
+}
+
+function safeJson(value: unknown): string {
+  try {
+    return JSON.stringify(value, null, 2);
+  } catch {
+    return "[unserializable]";
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === "object" && value !== null;
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}