@wyattjoh/demur 0.3.0 → 0.3.2

package/README.md

@@ -90,9 +90,11 @@ pi install npm:@wyattjoh/demur
 
 Pin a specific release when reproducibility matters:
 
+<!-- x-release-please-start-version -->
 ```sh
-pi install npm:@wyattjoh/demur@0.1.1
+pi install npm:@wyattjoh/demur@0.3.2
 ```
+<!-- x-release-please-end -->
 
 Launch Pi normally after configuring the credential:
 
@@ -100,8 +102,27 @@ Launch Pi normally after configuring the credential:
 pi
 ```
 
-The extension intercepts `bash` tool calls. `ask` opens an interactive
-confirmation dialog; without an interactive UI, demur blocks the command.
+The extension intercepts `bash` tool calls. Because Pi runs extensions under
+Node.js while demur uses `Bun.secrets`, the extension launches a package-local
+Bun worker for each judgment. The API key remains inside that worker; only the
+command request and resulting verdict cross its local stdio pipes. `ask` opens
+an interactive confirmation dialog; without an interactive UI, demur blocks the
+command.
+
+After each run, Pi's interactive UI prints the decision, submitted input-token
+count, the run's estimated input cost, the accumulated global estimate, and the
+wall-clock evaluation time in human-readable units. The
+estimate uses TypeSafe's published Jev price of
+[$0.042 per million input tokens](https://typesafe.ai/blog/introducing-system-one-models-and-jev);
+it is informational rather than an authoritative billing amount. Failure and
+bypass paths that do not call Jev report that cost is unavailable.
+
+The accumulated estimate is stored at `$XDG_STATE_HOME/demur/usage.json`, or
+`~/.local/state/demur/usage.json` when `XDG_STATE_HOME` is unset. A lock
+serializes concurrent Pi instances, and each update is written to a temporary
+file before an atomic rename so the total cannot be partially written or lose a
+concurrent increment. Cost-accounting failures do not change demur's guard
+decision; the status reports `accumulated unavailable` instead.
 
 Pi packages execute with the user's full system permissions. Review this
 repository before installing it.

package/extensions/demur/cost-tracker.ts

@@ -0,0 +1,185 @@
+import { randomUUID } from "node:crypto";
+import {
+  mkdir,
+  readFile,
+  rename,
+  rmdir,
+  unlink,
+  writeFile,
+} from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+
+const LOCK_RETRY_MS = 10;
+const LOCK_TIMEOUT_MS = 5_000;
+
+/**
+ * TypeSafe's published Jev input price in US dollars per million tokens.
+ *
+ * Source: https://typesafe.ai/blog/introducing-system-one-models-and-jev
+ */
+export const JEV_INPUT_COST_USD_PER_MILLION = 0.042;
+
+/**
+ * Persisted global usage and estimated-cost totals.
+ */
+export type CostTotals = {
+  version: 1;
+  totalInputTokens: number;
+  estimatedCostUsd: number;
+  updatedAt: string;
+};
+
+/**
+ * Resolve the global demur usage file according to the XDG state convention.
+ *
+ * @param environment - Process environment used to resolve `XDG_STATE_HOME`
+ * @param homeDirectory - Home directory used when the XDG override is absent
+ * @returns Absolute path to demur's usage state file
+ */
+export function getCostStatePath(
+  environment: NodeJS.ProcessEnv = process.env,
+  homeDirectory: string = homedir(),
+): string {
+  const stateDirectory = environment.XDG_STATE_HOME || join(homeDirectory, ".local", "state");
+  return join(stateDirectory, "demur", "usage.json");
+}
+
+/**
+ * Estimate the Jev input cost from TypeSafe's published per-token price.
+ *
+ * This is a display estimate rather than an authoritative billing amount.
+ *
+ * @param inputTokens - Number of input tokens submitted to Jev
+ * @returns Estimated cost in US dollars
+ */
+export function estimateInputCostUsd(inputTokens: number): number {
+  return (inputTokens * JEV_INPUT_COST_USD_PER_MILLION) / 1_000_000;
+}
+
+/**
+ * Atomically add one judgment's usage to the global accumulated estimate.
+ *
+ * A lock directory serializes read-modify-write operations across Pi processes.
+ * The updated JSON is written to a same-directory temporary file and atomically
+ * renamed over the previous state so readers never observe partial content.
+ *
+ * @param inputTokens - Number of input tokens submitted for this judgment
+ * @param statePath - Usage file to update
+ * @returns Updated accumulated totals
+ */
+export async function recordInputCost(
+  inputTokens: number,
+  statePath: string = getCostStatePath(),
+): Promise<CostTotals> {
+  if (!Number.isSafeInteger(inputTokens) || inputTokens < 0) {
+    throw new Error("input token count must be a non-negative safe integer");
+  }
+
+  await mkdir(dirname(statePath), { recursive: true, mode: 0o700 });
+  const release = await acquireLock(`${statePath}.lock`);
+
+  try {
+    const current = await readTotals(statePath);
+    const next: CostTotals = {
+      version: 1,
+      totalInputTokens: current.totalInputTokens + inputTokens,
+      estimatedCostUsd:
+        current.estimatedCostUsd + estimateInputCostUsd(inputTokens),
+      updatedAt: new Date().toISOString(),
+    };
+    await replaceJsonAtomically(statePath, next);
+    return next;
+  } finally {
+    await release();
+  }
+}
+
+async function acquireLock(lockPath: string): Promise<() => Promise<void>> {
+  const startedAt = Date.now();
+
+  while (true) {
+    try {
+      await mkdir(lockPath, { mode: 0o700 });
+      return async () => {
+        await rmdir(lockPath);
+      };
+    } catch (error: unknown) {
+      if (!isErrorCode(error, "EEXIST")) throw error;
+      if (Date.now() - startedAt >= LOCK_TIMEOUT_MS) {
+        throw new Error(`timed out waiting for cost state lock: ${lockPath}`);
+      }
+      await delay(LOCK_RETRY_MS);
+    }
+  }
+}
+
+async function readTotals(statePath: string): Promise<CostTotals> {
+  let content: string;
+  try {
+    content = await readFile(statePath, "utf8");
+  } catch (error: unknown) {
+    if (isErrorCode(error, "ENOENT")) {
+      return {
+        version: 1,
+        totalInputTokens: 0,
+        estimatedCostUsd: 0,
+        updatedAt: new Date(0).toISOString(),
+      };
+    }
+    throw error;
+  }
+
+  const value: unknown = JSON.parse(content);
+  if (value === null || typeof value !== "object") {
+    throw new Error(`invalid cost state in ${statePath}: expected an object`);
+  }
+
+  const { version, totalInputTokens, estimatedCostUsd, updatedAt } =
+    value as Record<string, unknown>;
+  if (
+    version !== 1 ||
+    !Number.isSafeInteger(totalInputTokens) ||
+    (totalInputTokens as number) < 0 ||
+    typeof estimatedCostUsd !== "number" ||
+    !Number.isFinite(estimatedCostUsd) ||
+    estimatedCostUsd < 0 ||
+    typeof updatedAt !== "string"
+  ) {
+    throw new Error(`invalid cost state in ${statePath}: unsupported values`);
+  }
+
+  return value as CostTotals;
+}
+
+async function replaceJsonAtomically(
+  statePath: string,
+  totals: CostTotals,
+): Promise<void> {
+  const temporaryPath = `${statePath}.${process.pid}.${randomUUID()}.tmp`;
+
+  try {
+    await writeFile(temporaryPath, `${JSON.stringify(totals, null, 2)}\n`, {
+      encoding: "utf8",
+      flag: "wx",
+      mode: 0o600,
+    });
+    await rename(temporaryPath, statePath);
+  } finally {
+    try {
+      await unlink(temporaryPath);
+    } catch (error: unknown) {
+      if (!isErrorCode(error, "ENOENT")) throw error;
+    }
+  }
+}
+
+function isErrorCode(error: unknown, code: string): boolean {
+  return error instanceof Error &&
+    "code" in error &&
+    (error as NodeJS.ErrnoException).code === code;
+}
+
+function delay(milliseconds: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, milliseconds));
+}

package/extensions/demur/index.ts

@@ -1,3 +1,5 @@
+import { spawn } from "node:child_process";
+import { fileURLToPath } from "node:url";
 import {
   isToolCallEventType,
   type ExtensionAPI,
@@ -5,7 +7,16 @@ import {
   type ToolCallEvent,
   type ToolCallEventResult,
 } from "@earendil-works/pi-coding-agent";
-import { guard } from "../../src/guard.ts";
+import type { Verdict } from "../../src/types.ts";
+import {
+  estimateInputCostUsd,
+  recordInputCost,
+} from "./cost-tracker.ts";
+
+const WORKER_PATH = fileURLToPath(
+  new URL("../../src/adapters/pi-worker.ts", import.meta.url),
+);
+const MAX_WORKER_OUTPUT_BYTES = 64 * 1024;
 
 /**
  * Handle one `tool_call` event, guarding shell commands only.
@@ -26,11 +37,44 @@ export async function handleToolCall(
   const command = event.input.command ?? "";
   if (command.trim() === "") return undefined;
 
-  const verdict = await guard(command, ctx.cwd, "pi", ctx.signal);
+  const evaluationStartedAt = performance.now();
+  let verdict: Verdict;
+  try {
+    verdict = await runGuardWorker(command, ctx.cwd, ctx.signal);
+  } catch (error: unknown) {
+    const evaluationMs = performance.now() - evaluationStartedAt;
+    notifyRun(ctx, "ERROR", undefined, undefined, evaluationMs, "warning");
+    return {
+      block: true,
+      reason: `demur: guard worker crashed — ${errorDetail(error)} Blocking because demur fails closed. Set DEMUR_DISABLE=1 to bypass.`,
+    };
+  }
+
+  const evaluationMs = performance.now() - evaluationStartedAt;
+  const inputTokens = verdict.usage?.inputTokens;
+  const accumulatedCostUsd = await recordAccumulatedCost(inputTokens);
 
-  if (verdict.decision === "allow") return undefined;
+  if (verdict.decision === "allow") {
+    notifyRun(
+      ctx,
+      "ALLOW",
+      inputTokens,
+      accumulatedCostUsd,
+      evaluationMs,
+      "info",
+    );
+    return undefined;
+  }
 
   if (verdict.decision === "deny") {
+    notifyRun(
+      ctx,
+      "DENY",
+      inputTokens,
+      accumulatedCostUsd,
+      evaluationMs,
+      "warning",
+    );
     return { block: true, reason: verdict.reason };
   }
 
@@ -38,6 +82,14 @@ export async function handleToolCall(
   // better than the agent guessing. Without a UI there is nobody to ask, so the
   // fail-closed posture applies and the command is blocked.
   if (!ctx.hasUI) {
+    notifyRun(
+      ctx,
+      "ASK → BLOCK",
+      inputTokens,
+      accumulatedCostUsd,
+      evaluationMs,
+      "warning",
+    );
     return {
       block: true,
       reason: `${verdict.reason} No interactive UI available to confirm, so blocking.`,
@@ -45,11 +97,140 @@ export async function handleToolCall(
   }
 
   const approved = await ctx.ui.confirm("demur", `${verdict.reason}\n\n${command}\n\nRun it anyway?`);
+  notifyRun(
+    ctx,
+    approved ? "ASK → ALLOW" : "ASK → BLOCK",
+    inputTokens,
+    accumulatedCostUsd,
+    evaluationMs,
+    approved ? "info" : "warning",
+  );
   if (approved) return undefined;
 
   return { block: true, reason: `${verdict.reason} Declined by the user.` };
 }
 
+/**
+ * Format the compact status Pi prints after each demur run.
+ *
+ * @param result - Guard decision and any final user-confirmation outcome
+ * @param inputTokens - Submitted Jev input tokens, when a judgment completed
+ * @param accumulatedCostUsd - Persisted global estimate after this run
+ * @param evaluationMs - Wall-clock time spent obtaining the guard verdict
+ * @returns One-line status with costs and evaluation duration
+ */
+export function formatRunNotification(
+  result: string,
+  inputTokens: number | undefined,
+  accumulatedCostUsd: number | undefined,
+  evaluationMs: number,
+): string {
+  const duration = `evaluated in ${formatEvaluationDuration(evaluationMs)}`;
+  if (inputTokens === undefined) {
+    return `demur: ${result} · cost unavailable · ${duration}`;
+  }
+
+  const accumulated =
+    accumulatedCostUsd === undefined
+      ? "accumulated unavailable"
+      : `accumulated ${formatUsd(accumulatedCostUsd)}`;
+  return `demur: ${result} · ${inputTokens.toLocaleString("en-US")} input tokens · estimated cost ${formatUsd(estimateInputCostUsd(inputTokens))} · ${accumulated} · ${duration}`;
+}
+
+/**
+ * Format an evaluation duration using compact human-readable units.
+ *
+ * @param milliseconds - Non-negative wall-clock duration in milliseconds
+ * @returns Duration rendered in milliseconds, seconds, or minutes
+ */
+export function formatEvaluationDuration(milliseconds: number): string {
+  const bounded = Math.max(0, milliseconds);
+  if (bounded < 1) return "<1 ms";
+  if (bounded < 1_000) return `${Math.round(bounded)} ms`;
+  if (bounded < 60_000) return `${formatDecimal(bounded / 1_000, bounded < 10_000 ? 2 : 1)} s`;
+
+  const minutes = Math.floor(bounded / 60_000);
+  const seconds = (bounded % 60_000) / 1_000;
+  return `${minutes}m ${formatDecimal(seconds, seconds < 10 ? 1 : 0)}s`;
+}
+
+/**
+ * Run the Bun-native guard behind Pi's Node-compatible extension boundary.
+ *
+ * The API key remains inside the worker process: only the command request and
+ * resulting verdict cross the local stdio pipes.
+ *
+ * @param command - The shell command Pi is about to execute
+ * @param cwd - Absolute working directory for the command
+ * @param signal - Optional cancellation signal from Pi
+ * @param environment - Environment inherited by the Bun worker
+ * @returns The guard verdict produced by the worker
+ */
+export function runGuardWorker(
+  command: string,
+  cwd: string,
+  signal: AbortSignal | undefined,
+  environment: NodeJS.ProcessEnv = process.env,
+): Promise<Verdict> {
+  return new Promise((resolve, reject) => {
+    if (signal?.aborted) {
+      reject(new Error("guard request cancelled"));
+      return;
+    }
+
+    const child = spawn("bun", [WORKER_PATH], {
+      cwd,
+      env: environment,
+      stdio: ["pipe", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    let settled = false;
+
+    const finish = (outcome: () => void) => {
+      if (settled) return;
+      settled = true;
+      signal?.removeEventListener("abort", abort);
+      outcome();
+    };
+    const abort = () => {
+      child.kill();
+      finish(() => reject(new Error("guard request cancelled")));
+    };
+    const appendBounded = (current: string, chunk: Buffer): string =>
+      `${current}${chunk.toString("utf8")}`.slice(0, MAX_WORKER_OUTPUT_BYTES);
+
+    signal?.addEventListener("abort", abort, { once: true });
+    child.stdout.on("data", (chunk: Buffer) => {
+      stdout = appendBounded(stdout, chunk);
+      if (stdout.length >= MAX_WORKER_OUTPUT_BYTES) child.kill();
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      stderr = appendBounded(stderr, chunk);
+      if (stderr.length >= MAX_WORKER_OUTPUT_BYTES) child.kill();
+    });
+    child.on("error", (error) => finish(() => reject(error)));
+    child.on("close", (code, exitSignal) => {
+      finish(() => {
+        if (code !== 0) {
+          const detail = stderr.trim() || `exit ${code ?? exitSignal ?? "unknown"}`;
+          reject(new Error(detail));
+          return;
+        }
+
+        try {
+          resolve(parseVerdict(stdout));
+        } catch (error: unknown) {
+          reject(new Error(`invalid guard worker response: ${errorDetail(error)}`));
+        }
+      });
+    });
+
+    child.stdin.on("error", (error) => finish(() => reject(error)));
+    child.stdin.end(JSON.stringify({ command, cwd }));
+  });
+}
+
 /**
  * Pi extension entry point.
  *
@@ -61,3 +242,67 @@ export async function handleToolCall(
 export default function demur(pi: ExtensionAPI): void {
   pi.on("tool_call", handleToolCall);
 }
+
+function notifyRun(
+  ctx: ExtensionContext,
+  result: string,
+  inputTokens: number | undefined,
+  accumulatedCostUsd: number | undefined,
+  evaluationMs: number,
+  level: "info" | "warning",
+): void {
+  ctx.ui.notify(
+    formatRunNotification(
+      result,
+      inputTokens,
+      accumulatedCostUsd,
+      evaluationMs,
+    ),
+    level,
+  );
+}
+
+async function recordAccumulatedCost(
+  inputTokens: number | undefined,
+): Promise<number | undefined> {
+  if (inputTokens === undefined) return undefined;
+
+  try {
+    return (await recordInputCost(inputTokens)).estimatedCostUsd;
+  } catch {
+    return undefined;
+  }
+}
+
+function formatDecimal(value: number, fractionDigits: number): string {
+  return value
+    .toFixed(fractionDigits)
+    .replace(/(\.\d*?[1-9])0+$/, "$1")
+    .replace(/\.0+$/, "");
+}
+
+function formatUsd(value: number): string {
+  const decimal = value.toFixed(9).replace(/0+$/, "").replace(/\.$/, "");
+  return `$${decimal}`;
+}
+
+function parseVerdict(output: string): Verdict {
+  const value: unknown = JSON.parse(output);
+  if (value === null || typeof value !== "object") {
+    throw new Error("verdict must be an object");
+  }
+
+  const { decision, reason } = value as Record<string, unknown>;
+  if (
+    (decision !== "allow" && decision !== "ask" && decision !== "deny") ||
+    typeof reason !== "string"
+  ) {
+    throw new Error("verdict must contain a valid decision and reason");
+  }
+
+  return value as Verdict;
+}
+
+function errorDetail(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wyattjoh/demur",
-  "version": "0.3.0",
+  "version": "0.3.2",
   "type": "module",
   "description": "A proof-of-concept destructive-command guard for coding agents.",
   "license": "MIT",
@@ -22,8 +22,10 @@
     "security"
   ],
   "files": [
+    "extensions/demur/cost-tracker.ts",
     "extensions/demur/index.ts",
     "src/adapters/claude-code.ts",
+    "src/adapters/pi-worker.ts",
     "src/analyze.ts",
     "src/cli.ts",
     "src/guard.internal.ts",
@@ -45,7 +47,7 @@
   "scripts": {
     "check": "tsc --noEmit",
     "test": "vitest run",
-    "build:pi": "bun build extensions/demur/index.ts --target=bun --outfile=dist/demur-guard.ts --format=esm --external @earendil-works/pi-coding-agent",
+    "build:pi": "bun build extensions/demur/index.ts --target=node --outfile=dist/demur-guard.js --format=esm --external @earendil-works/pi-coding-agent && bun build src/adapters/pi-worker.ts --target=bun --outfile=dist/demur-pi-worker.js --format=esm",
     "build:claude": "bun build src/adapters/claude-code.ts --target=bun --outfile=dist/demur-hook.js --format=esm",
     "build": "bun run build:pi && bun run build:claude",
     "ci": "bun run check && bun run test && bun run build",

package/src/adapters/pi-worker.ts

@@ -0,0 +1,25 @@
+#!/usr/bin/env bun
+import { guard } from "../guard.ts";
+
+type GuardRequest = {
+  command: string;
+  cwd: string;
+};
+
+const request = parseRequest(await Bun.stdin.text());
+const verdict = await guard(request.command, request.cwd, "pi");
+process.stdout.write(JSON.stringify(verdict));
+
+function parseRequest(input: string): GuardRequest {
+  const value: unknown = JSON.parse(input);
+  if (value === null || typeof value !== "object") {
+    throw new Error("guard request must be an object");
+  }
+
+  const { command, cwd } = value as Record<string, unknown>;
+  if (typeof command !== "string" || typeof cwd !== "string") {
+    throw new Error("guard request must contain string command and cwd fields");
+  }
+
+  return { command, cwd };
+}