pi-jev-effort 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hyunwoo Nam
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,180 @@
+# pi-jev-effort
+
+Sets the thinking level of a [pi](https://pi.dev) session for every prompt, from a
+[TypeSafe Jev](https://typesafe.ai) judgement of how hard the prompt actually is — and caps it
+by how much of your quota is left.
+
+```
+[jev-effort] score=0.00 conf=1.00 budget=openrouter:58% burn=$0.00064/min ceiling=none high -> minimal
+[jev-effort] score=2.38 conf=0.54 budget=openrouter:58% burn=$0.00046/min ceiling=none high -> high
+[jev-effort] score=2.36 conf=0.55 budget=local:0%      burn=$0.00114/min ceiling=low  high -> low
+```
+
+Jev is a System One model: it answers a typed question with a distribution instead of prose, so
+one call returns a score on your rubric plus the confidence behind it. A judgement takes about
+250ms and costs about $0.000015, and Jev bills input only.
+
+## Why an extension and not a hook
+
+Pi's command hooks can read the thinking level but not write it. `setThinkingLevel` exists only on
+the extension API, so the decision has to live inside pi's process. The same is true elsewhere:
+Claude Code hooks read `$CLAUDE_EFFORT` but cannot set it (that needs a Mod), and Codex hook output
+has no field that changes session settings at all.
+
+## Install
+
+```sh
+pi install npm:pi-jev-effort
+```
+
+Or work on it in place, which keeps `/reload` working:
+
+```sh
+git clone https://github.com/namenu/pi-jev-effort ~/src/pi-jev-effort
+ln -s ~/src/pi-jev-effort ~/.pi/agent/extensions/jev-effort
+```
+
+Then give it a key. Either works, and `auto` prefers the first it finds:
+
+| Transport | Key | Endpoint |
+|---|---|---|
+| TypeSafe direct | `TYPESAFE_API_KEY`, or `apiKey` in `~/.jev/config.json` | `POST https://api.typesafe.ai/v1/systemone` |
+| OpenRouter | the OpenRouter login pi already holds — nothing to set | `POST https://openrouter.ai/api/alpha/decisions` |
+
+The OpenRouter path needs no configuration: the extension asks pi for the key with
+`modelRegistry.getApiKeyForProvider("openrouter")` and re-resolves it every turn, so a refreshed
+OAuth token keeps working. If your OpenRouter workspace filters providers, allow **TypeSafe** under
+Guardrails first, or every call comes back `404 provider-not-allowed-by-guardrail`.
+
+There are no npm dependencies. Both transports take the same body and return the same answer shape.
+
+## How a level gets chosen
+
+**1. Jev scores the prompt** against a four-level rubric — trivial, routine, substantial, hard —
+and returns an expected score with its confidence. Measured against `~typesafe/jev-latest`
+(resolved as `typesafe/jev-1.13-20260917`):
+
+| Prompt | Score | Confidence | Latency | Cost |
+|---|---|---|---|---|
+| `list the files in this directory, nothing else` | 0.00 | 1.00 | — | — |
+| `rename the variable foo to bar in utils.ts` | 0.43 | 0.57 | 281ms | $0.0000149 |
+| `why does the run index drift from the runner status file after a crash` | 2.38 | 0.54 | — | — |
+| `find why the scheduler deadlocks under concurrent compaction and fix it` | 2.87 | 0.87 | 235ms | $0.0000151 |
+
+**2. Hysteresis decides whether to move.** An upgrade needs confidence ≥ 0.3, a downgrade ≥ 0.6.
+Thinking more than necessary costs tokens; thinking less costs the answer, so the bars are not
+symmetric. The third row above is why: at 0.54 the score leans substantial but not firmly enough to
+give up a level you already have.
+
+**3. The budget caps the result.** A ceiling from quota pressure is a hard cap, not an opinion — it
+applies whether or not Jev was confident. Everything else about the turn is unchanged.
+
+Short prompts never reach step 1. "continue" or "yes" carries no signal of its own, and classifying
+it would drag the level down in the middle of hard work, so anything under 12 characters keeps the
+current level and makes no call.
+
+## Budget, burn rate and reset
+
+The same places `ccusage` and CodexBar look: the transcripts the agent already writes, plus whatever
+the provider volunteers about its own limits.
+
+| Source | Where it comes from | Gives |
+|---|---|---|
+| `headers` | rate-limit headers captured in `after_provider_response` | remaining fraction, reset time |
+| `openrouter` | `GET /api/v1/credits` | remaining fraction of purchased credits (no reset) |
+| `local` | `~/.pi/agent/sessions/**/*.jsonl`, which record `usage.cost` per message | spend in the window against `limitUsd`, reset at the window edge |
+
+`auto` tries them in that order. The **burn rate is always local**: the extension sums the cost of
+assistant messages inside a rolling window and divides by the span, re-reading a transcript only
+when its size changed. Windows sit on a UTC grid, the way ccusage treats Claude's 5-hour blocks, so
+the reset time is the edge of the current block.
+
+Pressure lowers the ceiling as the quota drains, and a burn rate that would empty the window before
+it resets counts as one threshold worse:
+
+```json
+"pressure": [
+  { "remainingBelow": 0.3, "ceiling": "medium" },
+  { "remainingBelow": 0.1, "ceiling": "low" }
+]
+```
+
+The footer carries it: `jev: high (0.87) · 58% · resets 2h11m`.
+
+## Command
+
+```
+/jev-effort           # status, including budget source, burn and reset
+/jev-effort on        # enable, and clear a manual pause
+/jev-effort off       # disable for this session
+```
+
+Change the level yourself with `/effort` or `Ctrl+Shift+E` and automatic routing pauses for the
+session — your hands beat the model's judgement. A level change caused by switching models does not
+count as manual, so clamping to a model's capabilities will not pause anything.
+
+## Configuration
+
+Optional, at `~/.pi/agent/jev-effort.json`. Defaults:
+
+```json
+{
+  "enabled": true,
+  "provider": "auto",
+  "apiKey": null,
+  "baseUrl": null,
+  "model": null,
+  "timeoutMs": 4000,
+  "levels": ["minimal", "low", "medium", "high"],
+  "minUpgradeConfidence": 0.3,
+  "minDowngradeConfidence": 0.6,
+  "floor": null,
+  "ceiling": null,
+  "minPromptChars": 12,
+  "budget": {
+    "source": "auto",
+    "windowHours": 5,
+    "limitUsd": null,
+    "pressure": [
+      { "remainingBelow": 0.3, "ceiling": "medium" },
+      { "remainingBelow": 0.1, "ceiling": "low" }
+    ],
+    "refreshMs": 60000
+  },
+  "notify": false,
+  "debug": false
+}
+```
+
+`levels` maps rubric scores 0–3 onto pi thinking levels, so a model with `xhigh` and `max` can use
+them: `["low", "medium", "high", "max"]`. `floor` and `ceiling` clamp every result. `JEV_EFFORT_DEBUG=1`
+prints one line per judgement to stderr, as at the top of this README.
+
+Pi clamps whatever it is given to what the model supports, so `minimal` can land as `low`. That is
+pi, not this extension, and the status line shows what actually took effect.
+
+## Failure is always open
+
+No key, a timeout, an HTTP error, a guardrail rejection or a malformed answer leaves the level
+untouched and the turn running. A judgement layer that can cost you a turn is worse than no
+judgement layer.
+
+## Development
+
+```sh
+node --test
+```
+
+The tests cover the hysteresis rule, the hard cap, the wire contract of both transports with `fetch`
+mocked, transcript parsing and burn rate, rate-limit header shapes, and the UTC window grid. For an
+end-to-end check, point `baseUrl` at a local server that answers
+
+```json
+{ "answers": { "effort": { "type": "score", "score": 0, "confidence": 0.85 } } }
+```
+
+and run `JEV_EFFORT_DEBUG=1 pi -p "<a prompt of at least 12 characters>"`.
+
+## License
+
+MIT

package/index.ts

@@ -0,0 +1,504 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { homedir } from "node:os";
+import { basename, join } from "node:path";
+import { readFileSync } from "node:fs";
+import {
+  humanizeReset,
+  openRouterCredits,
+  parseRateLimitHeaders,
+  pressureCeiling,
+  readSpend,
+  windowBounds,
+  type Budget,
+  type Pressure,
+  type RateLimit,
+} from "./usage.ts";
+
+export type ThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+/** Ordered so a level can be compared against another by index. */
+const LEVELS: ThinkingLevel[] = ["off", "minimal", "low", "medium", "high", "xhigh", "max"];
+
+/** Jev speaks the same wire format on both; only the URL and the model id differ. */
+export type Provider = "typesafe" | "openrouter";
+
+const ENDPOINTS: Record<Provider, { baseUrl: string; path: string; model: string }> = {
+  typesafe: { baseUrl: "https://api.typesafe.ai", path: "/v1/systemone", model: "jev-latest" },
+  openrouter: {
+    baseUrl: "https://openrouter.ai",
+    path: "/api/alpha/decisions",
+    model: "~typesafe/jev-latest",
+  },
+};
+
+const CONFIG_PATH = join(homedir(), ".pi", "agent", "jev-effort.json");
+const STATUS_KEY = "jev-effort";
+
+export interface Config {
+  enabled: boolean;
+  /** "auto" prefers a TypeSafe key and falls back to the OpenRouter key pi already holds. */
+  provider: "auto" | Provider;
+  apiKey: string | null;
+  baseUrl: string | null;
+  model: string | null;
+  timeoutMs: number;
+  /** Rubric index -> thinking level. */
+  levels: ThinkingLevel[];
+  minUpgradeConfidence: number;
+  minDowngradeConfidence: number;
+  floor: ThinkingLevel | null;
+  ceiling: ThinkingLevel | null;
+  /** Prompts shorter than this keep the current level without a Jev call. */
+  minPromptChars: number;
+  budget: BudgetConfig;
+  notify: boolean;
+  debug: boolean;
+}
+
+export interface BudgetConfig {
+  /** "auto" takes provider headers, then the OpenRouter balance, then a local budget. */
+  source: "auto" | "headers" | "openrouter" | "local" | "none";
+  /** Rolling block used for the burn rate, and for the local budget window. */
+  windowHours: number;
+  /** Dollars allowed per window; only the "local" source needs it. */
+  limitUsd: number | null;
+  /** Ceilings applied once the remaining fraction drops below each threshold. */
+  pressure: Pressure[];
+  /** How long a balance lookup is reused before it is refetched. */
+  refreshMs: number;
+}
+
+export const DEFAULTS: Config = {
+  enabled: true,
+  provider: "auto",
+  apiKey: null,
+  baseUrl: null,
+  model: null,
+  timeoutMs: 4000,
+  levels: ["minimal", "low", "medium", "high"],
+  // Asymmetric on purpose: spending more thinking than needed costs tokens,
+  // spending less costs a wrong answer, so upgrades clear a lower bar.
+  minUpgradeConfidence: 0.3,
+  minDowngradeConfidence: 0.6,
+  floor: null,
+  ceiling: null,
+  minPromptChars: 12,
+  budget: {
+    source: "auto",
+    windowHours: 5,
+    limitUsd: null,
+    pressure: [
+      { remainingBelow: 0.3, ceiling: "medium" },
+      { remainingBelow: 0.1, ceiling: "low" },
+    ],
+    refreshMs: 60_000,
+  },
+  notify: false,
+  debug: false,
+};
+
+/** Indexed from zero; the index is the effort score Jev returns. */
+const RUBRIC = [
+  "Trivial or mechanical. A greeting, a short factual question, reading or listing files, " +
+    "a rename, a one-line edit whose answer is already in view.",
+  "Routine. A small well-specified change in one or two files, a bug with a clear repro, " +
+    "writing a short test, following a pattern that already exists in the codebase.",
+  "Substantial. Changes spanning several files, unfamiliar code that has to be traced first, " +
+    "an ambiguous failure, designing a small API, tradeoffs that are not obvious.",
+  "Hard. Architecture, migration or concurrency work, a subtle performance or correctness bug, " +
+    "conflicting constraints, work that needs a plan and verification before it can be trusted.",
+] as const;
+
+const INSTRUCTIONS =
+  "A developer sent this prompt to a coding agent. How much step-by-step reasoning does " +
+  "answering it well require? Judge the work the prompt asks for, not how politely it is " +
+  "written and not how long it is.";
+
+export const rankOf = (level: string): number => {
+  const i = LEVELS.indexOf(level as ThinkingLevel);
+  return i === -1 ? 0 : i;
+};
+
+const clampLevel = (level: ThinkingLevel, cfg: Config): ThinkingLevel => {
+  let rank = rankOf(level);
+  if (cfg.floor) rank = Math.max(rank, rankOf(cfg.floor));
+  if (cfg.ceiling) rank = Math.min(rank, rankOf(cfg.ceiling));
+  return LEVELS[rank];
+};
+
+/**
+ * Map an expected score onto a level, then apply hysteresis against the level
+ * already in effect. Returns null when the current level should stand.
+ */
+export const decide = (
+  current: ThinkingLevel,
+  score: number,
+  confidence: number,
+  cfg: Config,
+): ThinkingLevel | null => {
+  const index = Math.min(cfg.levels.length - 1, Math.max(0, Math.round(score)));
+  const target = clampLevel(cfg.levels[index], cfg);
+  const delta = rankOf(target) - rankOf(current);
+  if (delta === 0) return null;
+  const needed = delta > 0 ? cfg.minUpgradeConfidence : cfg.minDowngradeConfidence;
+  return confidence >= needed ? target : null;
+};
+
+/**
+ * The level to switch to, or null to stay put. The judgement decides direction
+ * and has to clear its confidence bar; the ceiling is a hard cap that does not,
+ * because a budget that has run out is not an opinion.
+ */
+export const plan = (
+  current: ThinkingLevel,
+  score: number,
+  confidence: number,
+  cfg: Config,
+  ceiling: ThinkingLevel | null,
+): ThinkingLevel | null => {
+  const proposed = decide(current, score, confidence, { ...cfg, ceiling: null }) ?? current;
+  const capped = clampLevel(proposed, { ...cfg, ceiling });
+  return capped === current ? null : capped;
+};
+
+export const loadConfig = (env: NodeJS.ProcessEnv = process.env): Config => {
+  let fromFile: Partial<Config> = {};
+  try {
+    fromFile = JSON.parse(readFileSync(CONFIG_PATH, "utf8")) as Partial<Config>;
+  } catch {
+    // No config file is the normal case; a malformed one falls back to defaults.
+  }
+  const cfg = { ...DEFAULTS, ...fromFile, budget: { ...DEFAULTS.budget, ...fromFile.budget } };
+  if (env.JEV_EFFORT_DEBUG) cfg.debug = true;
+  return cfg;
+};
+
+/** jev-cli and the other Jev tools keep the key here; reuse it rather than ask twice. */
+const jevConfigKey = (): string | null => {
+  try {
+    const raw = JSON.parse(readFileSync(join(homedir(), ".jev", "config.json"), "utf8"));
+    return typeof raw?.apiKey === "string" ? raw.apiKey : null;
+  } catch {
+    return null;
+  }
+};
+
+export interface Route {
+  provider: Provider;
+  url: string;
+  apiKey: string;
+  model: string;
+}
+
+export const buildRoute = (provider: Provider, apiKey: string, cfg: Config): Route => {
+  const e = ENDPOINTS[provider];
+  return {
+    provider,
+    apiKey,
+    model: cfg.model ?? e.model,
+    url: `${cfg.baseUrl ?? e.baseUrl}${e.path}`,
+  };
+};
+
+export interface Judgement {
+  score: number;
+  confidence: number;
+}
+
+export const classify = async (
+  state: Record<string, unknown>,
+  route: Route,
+  cfg: Config,
+): Promise<Judgement | null> => {
+  const res = await fetch(route.url, {
+    method: "POST",
+    headers: {
+      Authorization: `Bearer ${route.apiKey}`,
+      "Content-Type": "application/json",
+    },
+    body: JSON.stringify({
+      model: route.model,
+      state,
+      questions: {
+        effort: { type: "score", instructions: INSTRUCTIONS, criteria: RUBRIC },
+      },
+    }),
+    signal: AbortSignal.timeout(cfg.timeoutMs),
+  });
+  if (!res.ok) {
+    throw new Error(`${route.provider} ${res.status}: ${(await res.text()).slice(0, 300)}`);
+  }
+  const body = (await res.json()) as {
+    answers?: { effort?: { score?: unknown; confidence?: unknown } };
+  };
+  const { score, confidence } = body.answers?.effort ?? {};
+  if (typeof score !== "number" || typeof confidence !== "number") return null;
+  return { score, confidence };
+};
+
+export default function (pi: ExtensionAPI) {
+  const cfg = loadConfig();
+  let paused = false;
+  let lastApplied: ThinkingLevel | null = null;
+  let lastJudgement: Judgement | null = null;
+  let lastRoute: Route | null = null;
+  let lastBudget: Budget | null = null;
+  let observedLimit: RateLimit | null = null;
+  let balance: { at: number; remainingFraction: number } | null = null;
+  // Set while we call setThinkingLevel so the resulting event is not read as a
+  // manual override. Model changes clamp the level too, hence the timestamp.
+  let applying = false;
+  let levelChurnUntil = 0;
+
+  const log = (msg: string) => {
+    if (cfg.debug) process.stderr.write(`[jev-effort] ${msg}\n`);
+  };
+
+  /**
+   * Resolved per turn rather than cached: pi refreshes the OpenRouter OAuth
+   * token in the background, and a stale copy would fail the rest of the session.
+   */
+  const resolveRoute = async (ctx: ExtensionContext): Promise<Route | null> => {
+    if (cfg.provider !== "openrouter") {
+      const key = cfg.apiKey ?? process.env.TYPESAFE_API_KEY ?? jevConfigKey();
+      if (key) return buildRoute("typesafe", key, cfg);
+      if (cfg.provider === "typesafe") return null;
+    }
+    const key =
+      (cfg.provider === "openrouter" ? cfg.apiKey : null) ??
+      process.env.OPENROUTER_API_KEY ??
+      (await ctx.modelRegistry.getApiKeyForProvider("openrouter")) ??
+      null;
+    return key ? buildRoute("openrouter", key, cfg) : null;
+  };
+
+  /**
+   * Remaining quota, how fast it is going, and when it returns. The spend half
+   * is always local; only the ceiling half needs the provider to say anything.
+   */
+  const resolveBudget = async (route: Route | null): Promise<Budget> => {
+    const b = cfg.budget;
+    const { start, end } = windowBounds(b.windowHours);
+    const spend = readSpend(start);
+    const none: Budget = {
+      source: "none",
+      remainingFraction: null,
+      resetAt: null,
+      spend,
+      exhaustsBeforeReset: false,
+    };
+    if (b.source === "none") return none;
+
+    if (b.source === "auto" || b.source === "headers") {
+      const l = observedLimit;
+      if (l?.limit && l.remaining !== undefined) {
+        const fraction = Math.max(0, Math.min(1, l.remaining / l.limit));
+        return {
+          source: "headers",
+          remainingFraction: fraction,
+          resetAt: l.resetAt ?? null,
+          spend,
+          exhaustsBeforeReset: false,
+        };
+      }
+      if (b.source === "headers") return none;
+    }
+
+    if ((b.source === "auto" || b.source === "openrouter") && route?.provider === "openrouter") {
+      const fresh = balance && Date.now() - balance.at < b.refreshMs;
+      if (!fresh) {
+        try {
+          const credits = await openRouterCredits(route.apiKey, cfg.timeoutMs);
+          balance = credits ? { at: Date.now(), remainingFraction: credits.remainingFraction } : null;
+        } catch {
+          // A balance lookup is advisory; losing it must not change the turn.
+        }
+      }
+      if (balance) {
+        return {
+          source: "openrouter",
+          remainingFraction: balance.remainingFraction,
+          // Purchased credits do not come back on a schedule.
+          resetAt: null,
+          spend,
+          exhaustsBeforeReset: false,
+        };
+      }
+      if (b.source === "openrouter") return none;
+    }
+
+    if ((b.source === "auto" || b.source === "local") && b.limitUsd) {
+      const remainingUsd = Math.max(0, b.limitUsd - spend.usd);
+      const minutesLeft = (end - Date.now()) / 60000;
+      return {
+        source: "local",
+        remainingFraction: Math.min(1, remainingUsd / b.limitUsd),
+        resetAt: end,
+        spend,
+        exhaustsBeforeReset:
+          spend.burnUsdPerMin > 0 && remainingUsd / spend.burnUsdPerMin < minutesLeft,
+      };
+    }
+    return none;
+  };
+
+  /** The tighter of the configured ceiling and the one budget pressure forces. */
+  const effectiveCeiling = (budget: Budget): ThinkingLevel | null => {
+    const forced = pressureCeiling(budget, cfg.budget.pressure) as ThinkingLevel | null;
+    if (!forced) return cfg.ceiling;
+    if (!cfg.ceiling) return forced;
+    return rankOf(forced) < rankOf(cfg.ceiling) ? forced : cfg.ceiling;
+  };
+
+  const status = (ctx: ExtensionContext) => {
+    if (!ctx.hasUI) return;
+    if (!cfg.enabled || paused) {
+      ctx.ui.setStatus(STATUS_KEY, paused ? "jev: paused" : undefined);
+      return;
+    }
+    const j = lastJudgement;
+    const b = lastBudget;
+    const parts = [j ? `jev: ${pi.getThinkingLevel()} (${j.confidence.toFixed(2)})` : "jev: auto"];
+    if (b?.remainingFraction !== null && b !== null) {
+      parts.push(`${Math.round(b.remainingFraction! * 100)}%`);
+    }
+    const reset = humanizeReset(b?.resetAt ?? null);
+    if (reset) parts.push(`resets ${reset}`);
+    ctx.ui.setStatus(STATUS_KEY, parts.join(" · "));
+  };
+
+  pi.on("session_start", async (_event, ctx) => {
+    levelChurnUntil = Date.now() + 2000;
+    if (cfg.enabled) {
+      const route = await resolveRoute(ctx);
+      if (!route) {
+        if (ctx.hasUI) {
+          ctx.ui.notify(
+            "jev-effort: no key. Set TYPESAFE_API_KEY, or sign in to OpenRouter in pi.",
+            "warning",
+          );
+          ctx.ui.setStatus(STATUS_KEY, "jev: no key");
+        }
+        return;
+      }
+      log(`route ${route.provider} ${route.url} model=${route.model}`);
+    }
+    status(ctx);
+  });
+
+  pi.on("after_provider_response", async (event, _ctx) => {
+    // Free of charge: whatever the provider already said about its own limits.
+    const seen = parseRateLimitHeaders(event.headers ?? {});
+    if (seen) observedLimit = { ...observedLimit, ...seen };
+  });
+
+  pi.on("model_select", async (_event, ctx) => {
+    // A model change can clamp the thinking level; that is not the user typing /effort.
+    levelChurnUntil = Date.now() + 1000;
+    status(ctx);
+  });
+
+  pi.on("thinking_level_select", async (event, ctx) => {
+    log(`level -> ${event.level} (applying=${applying})`);
+    if (applying || Date.now() < levelChurnUntil) return;
+    if (event.level === lastApplied) return;
+    if (cfg.enabled && !paused) {
+      paused = true;
+      if (ctx.hasUI) {
+        ctx.ui.notify(`jev-effort: manual ${event.level}, auto paused. /jev-effort on`, "info");
+      }
+    }
+    status(ctx);
+  });
+
+  pi.on("before_agent_start", async (event, ctx) => {
+    if (!cfg.enabled || paused) return;
+    const prompt = (event.prompt ?? "").trim();
+    // Short follow-ups ("continue", "yes") carry no signal of their own; classifying
+    // them would drag the level back down in the middle of hard work.
+    if (prompt.length < cfg.minPromptChars) return;
+
+    const current = pi.getThinkingLevel() as ThinkingLevel;
+    let judgement: Judgement | null = null;
+    try {
+      const route = await resolveRoute(ctx);
+      if (!route) return;
+      lastRoute = route;
+      judgement = await classify(
+        {
+          prompt,
+          project: basename(ctx.cwd),
+          model: ctx.model ? `${ctx.model.provider}/${ctx.model.id}` : null,
+          current_thinking_level: current,
+        },
+        route,
+        cfg,
+      );
+    } catch (err) {
+      // Fail open: a judgement layer must never cost the user their turn.
+      log(`classify failed: ${String(err)}`);
+      return;
+    }
+    if (!judgement) return;
+    lastJudgement = judgement;
+
+    const budget = await resolveBudget(lastRoute);
+    lastBudget = budget;
+    const ceiling = effectiveCeiling(budget);
+    const next = plan(current, judgement.score, judgement.confidence, cfg, ceiling);
+    const left =
+      budget.remainingFraction === null
+        ? "n/a"
+        : `${Math.round(budget.remainingFraction * 100)}%`;
+    log(
+      `score=${judgement.score.toFixed(2)} conf=${judgement.confidence.toFixed(2)} ` +
+        `budget=${budget.source}:${left} burn=$${budget.spend.burnUsdPerMin.toFixed(5)}/min ` +
+        `ceiling=${ceiling ?? "none"} ${current} -> ${next ?? current}`,
+    );
+    if (next) {
+      applying = true;
+      try {
+        pi.setThinkingLevel(next);
+      } finally {
+        applying = false;
+      }
+      // Pi clamps to what the model supports, so record what actually took effect.
+      lastApplied = pi.getThinkingLevel() as ThinkingLevel;
+      if (cfg.notify && ctx.hasUI) ctx.ui.notify(`jev-effort: ${current} -> ${next}`, "info");
+    }
+    status(ctx);
+  });
+
+  pi.registerCommand("jev-effort", {
+    description: "Jev-driven automatic thinking level: on | off | status",
+    handler: async (args, ctx) => {
+      const arg = args.trim().toLowerCase();
+      if (arg === "on") {
+        cfg.enabled = true;
+        paused = false;
+      } else if (arg === "off") {
+        cfg.enabled = false;
+      } else if (arg && arg !== "status") {
+        ctx.ui.notify("jev-effort: usage /jev-effort [on|off|status]", "warning");
+        return;
+      }
+      const state = !cfg.enabled ? "off" : paused ? "paused" : "on";
+      const j = lastJudgement;
+      const b = lastBudget ?? (await resolveBudget(lastRoute));
+      lastBudget = b;
+      const left = b.remainingFraction === null ? "?" : `${Math.round(b.remainingFraction * 100)}%`;
+      const reset = humanizeReset(b.resetAt);
+      ctx.ui.notify(
+        `jev-effort ${state} · via ${lastRoute?.provider ?? "unresolved"} · ` +
+          `level ${pi.getThinkingLevel()}` +
+          (j ? ` · last score ${j.score.toFixed(2)} @ ${j.confidence.toFixed(2)}` : "") +
+          ` · budget ${b.source} ${left}` +
+          (reset ? ` (resets ${reset})` : "") +
+          ` · ${b.spend.tokens.toLocaleString()} tok / $${b.spend.usd.toFixed(3)} ` +
+          `in ${cfg.budget.windowHours}h`,
+        "info",
+      );
+      status(ctx);
+    },
+  });
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "pi-jev-effort",
+  "version": "0.1.0",
+  "description": "Pi extension that sets the session's thinking level per prompt from a TypeSafe Jev judgement, clamped by the quota you have left",
+  "keywords": [
+    "pi-package",
+    "pi",
+    "coding-agent",
+    "extension",
+    "jev",
+    "typesafe",
+    "openrouter",
+    "thinking-level",
+    "reasoning-effort",
+    "usage"
+  ],
+  "author": "namenu <namenu@gmail.com>",
+  "license": "MIT",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/namenu/pi-jev-effort.git"
+  },
+  "homepage": "https://github.com/namenu/pi-jev-effort#readme",
+  "bugs": {
+    "url": "https://github.com/namenu/pi-jev-effort/issues"
+  },
+  "engines": {
+    "node": ">=22.6"
+  },
+  "files": [
+    "index.ts",
+    "usage.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "pi": {
+    "extensions": ["./index.ts"]
+  }
+}

package/usage.ts

@@ -0,0 +1,237 @@
+/**
+ * Budget signal: how much of the current quota is left, how fast it is going,
+ * and when it comes back. Read the way ccusage and CodexBar read theirs — from
+ * the local transcripts the agent already writes, plus whatever the provider
+ * says about its own limits.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { readFileSync, readdirSync, statSync } from "node:fs";
+
+const SESSIONS_DIR = join(homedir(), ".pi", "agent", "sessions");
+
+export interface Spend {
+  /** Dollars spent inside the window. */
+  usd: number;
+  tokens: number;
+  /** Start of the window actually observed, as epoch ms. */
+  since: number;
+  /** Dollars per minute over the observed span; 0 when there is nothing to divide by. */
+  burnUsdPerMin: number;
+}
+
+interface FileCache {
+  size: number;
+  /** [timestampMs, usd, tokens] per assistant message, ascending. */
+  rows: [number, number, number][];
+}
+
+const cache = new Map<string, FileCache>();
+
+/** Assistant messages carry `usage.cost.total`; everything else is skipped. */
+const parseRows = (path: string): [number, number, number][] => {
+  const rows: [number, number, number][] = [];
+  for (const line of readFileSync(path, "utf8").split("\n")) {
+    if (!line || !line.includes('"usage"')) continue;
+    try {
+      const entry = JSON.parse(line) as {
+        type?: string;
+        timestamp?: string;
+        message?: {
+          usage?: { totalTokens?: number; cost?: { total?: number } };
+        };
+      };
+      const usage = entry.message?.usage;
+      const at = Date.parse(entry.timestamp ?? "");
+      if (!usage || Number.isNaN(at)) continue;
+      rows.push([at, usage.cost?.total ?? 0, usage.totalTokens ?? 0]);
+    } catch {
+      // A half-written last line is normal while a session is live.
+    }
+  }
+  return rows;
+};
+
+/**
+ * Sum what the agent spent since `since`. Files are re-read only when their
+ * size changed, so a long session costs one parse per turn at most.
+ */
+export const readSpend = (since: number, dir = SESSIONS_DIR): Spend => {
+  let usd = 0;
+  let tokens = 0;
+  let earliest = Number.POSITIVE_INFINITY;
+  let latest = 0;
+  let projects: string[];
+  try {
+    projects = readdirSync(dir);
+  } catch {
+    return { usd: 0, tokens: 0, since, burnUsdPerMin: 0 };
+  }
+  for (const project of projects) {
+    let files: string[];
+    try {
+      files = readdirSync(join(dir, project));
+    } catch {
+      continue;
+    }
+    for (const name of files) {
+      if (!name.endsWith(".jsonl")) continue;
+      const path = join(dir, project, name);
+      let size: number;
+      let mtimeMs: number;
+      try {
+        const st = statSync(path);
+        size = st.size;
+        mtimeMs = st.mtimeMs;
+      } catch {
+        continue;
+      }
+      // A file untouched since the window opened cannot hold rows inside it.
+      if (mtimeMs < since) {
+        cache.delete(path);
+        continue;
+      }
+      let entry = cache.get(path);
+      if (!entry || entry.size !== size) {
+        entry = { size, rows: parseRows(path) };
+        cache.set(path, entry);
+      }
+      for (const [at, cost, tok] of entry.rows) {
+        if (at < since) continue;
+        usd += cost;
+        tokens += tok;
+        if (at < earliest) earliest = at;
+        if (at > latest) latest = at;
+      }
+    }
+  }
+  const spanMin = latest > earliest ? (latest - earliest) / 60000 : 0;
+  return {
+    usd,
+    tokens,
+    since,
+    burnUsdPerMin: spanMin > 0 ? usd / spanMin : 0,
+  };
+};
+
+export interface RateLimit {
+  limit?: number;
+  remaining?: number;
+  /** Epoch ms. */
+  resetAt?: number;
+}
+
+/**
+ * Pull whatever a provider volunteered about its own limits. Header names
+ * differ per provider and many send nothing, so every field is optional.
+ */
+export const parseRateLimitHeaders = (headers: Record<string, string>): RateLimit | null => {
+  const h: Record<string, string> = {};
+  for (const [k, v] of Object.entries(headers)) h[k.toLowerCase()] = v;
+  const num = (...keys: string[]): number | undefined => {
+    for (const k of keys) {
+      const v = Number(h[k]);
+      if (h[k] !== undefined && !Number.isNaN(v)) return v;
+    }
+    return undefined;
+  };
+  const limit = num("x-ratelimit-limit", "anthropic-ratelimit-unified-limit");
+  const remaining = num(
+    "x-ratelimit-remaining",
+    "anthropic-ratelimit-unified-remaining",
+    "x-ratelimit-remaining-tokens",
+  );
+  const rawReset = num(
+    "x-ratelimit-reset",
+    "anthropic-ratelimit-unified-reset",
+    "x-ratelimit-reset-tokens",
+  );
+  const retryAfter = num("retry-after");
+  let resetAt: number | undefined;
+  if (rawReset !== undefined) {
+    // Seconds-since-epoch, milliseconds-since-epoch and seconds-from-now all appear.
+    resetAt =
+      rawReset > 1e12 ? rawReset : rawReset > 1e9 ? rawReset * 1000 : Date.now() + rawReset * 1000;
+  } else if (retryAfter !== undefined) {
+    resetAt = Date.now() + retryAfter * 1000;
+  }
+  if (limit === undefined && remaining === undefined && resetAt === undefined) return null;
+  return { limit, remaining, resetAt };
+};
+
+export interface Budget {
+  source: "headers" | "openrouter" | "local" | "none";
+  /** 0..1, or null when nothing credible says what the ceiling is. */
+  remainingFraction: number | null;
+  /** Epoch ms when the quota comes back, or null for a balance that does not reset. */
+  resetAt: number | null;
+  spend: Spend;
+  /** True when the current burn rate empties the quota before it resets. */
+  exhaustsBeforeReset: boolean;
+}
+
+export interface Pressure {
+  remainingBelow: number;
+  ceiling: string;
+}
+
+/**
+ * Pick the lowest ceiling whose threshold the remaining fraction has crossed.
+ * A projected exhaustion before reset counts as one threshold worse.
+ */
+export const pressureCeiling = (budget: Budget, rules: Pressure[]): string | null => {
+  if (budget.remainingFraction === null) return null;
+  const sorted = [...rules].sort((a, b) => b.remainingBelow - a.remainingBelow);
+  let hit: string | null = null;
+  let index = -1;
+  sorted.forEach((rule, i) => {
+    if (budget.remainingFraction! < rule.remainingBelow) {
+      hit = rule.ceiling;
+      index = i;
+    }
+  });
+  if (budget.exhaustsBeforeReset) {
+    const next = sorted[index + 1];
+    if (next) return next.ceiling;
+    if (!hit && sorted.length) return sorted[0].ceiling;
+  }
+  return hit;
+};
+
+/** OpenRouter reports purchased credits rather than a window, so this never resets. */
+export const openRouterCredits = async (
+  apiKey: string,
+  timeoutMs: number,
+): Promise<{ remainingFraction: number; remainingUsd: number } | null> => {
+  const res = await fetch("https://openrouter.ai/api/v1/credits", {
+    headers: { Authorization: `Bearer ${apiKey}` },
+    signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (!res.ok) return null;
+  const body = (await res.json()) as { data?: { total_credits?: number; total_usage?: number } };
+  const total = body.data?.total_credits;
+  const used = body.data?.total_usage;
+  if (typeof total !== "number" || typeof used !== "number" || total <= 0) return null;
+  const remainingUsd = Math.max(0, total - used);
+  return { remainingFraction: Math.min(1, remainingUsd / total), remainingUsd };
+};
+
+export const humanizeReset = (resetAt: number | null, now = Date.now()): string => {
+  if (resetAt === null) return "";
+  const mins = Math.max(0, Math.round((resetAt - now) / 60000));
+  if (mins < 60) return `${mins}m`;
+  return `${Math.floor(mins / 60)}h${String(mins % 60).padStart(2, "0")}m`;
+};
+
+/**
+ * Fixed rolling blocks on a UTC grid, the way ccusage treats Claude's 5-hour
+ * windows: everyone with the same window length agrees on where it starts.
+ */
+export const windowBounds = (
+  windowHours: number,
+  now = Date.now(),
+): { start: number; end: number } => {
+  const ms = Math.max(1, windowHours) * 3600_000;
+  const start = Math.floor(now / ms) * ms;
+  return { start, end: start + ms };
+};