@alexlikevibe/pi-jev 0.2.0

package/media/banner.svg

@@ -0,0 +1,198 @@
+<svg xmlns="http://www.w3.org/2000/svg" width="1200" height="440" viewBox="0 0 1200 440" role="img" aria-labelledby="banner-title banner-desc">
+  <title id="banner-title">pi-jev: typed judgments become actions</title>
+  <desc id="banner-desc">Two examples of the same pipeline, triggered independently by pi events. For compaction, Jev returns five keep scores; a 0.5 threshold selects the first and last tool calls, preserving their text verbatim. For routing, a difficulty level of 0.3 selects the cheap model from three branches. Each example illustrates a typed Jev request; large compactions may be batched. The animation plays once and ends in a complete, readable diagram.</desc>
+  <defs>
+    <pattern id="grid" width="32" height="32" patternUnits="userSpaceOnUse">
+      <path d="M32 0H0V32" fill="none" stroke="#293341" stroke-width="0.7"/>
+    </pattern>
+    <linearGradient id="engine" x1="0" y1="0" x2="1" y2="1">
+      <stop stop-color="#142033"/><stop offset="1" stop-color="#111820"/>
+    </linearGradient>
+    <linearGradient id="engine-edge" x1="0" x2="1">
+      <stop stop-color="#58a6ff" stop-opacity="0.05"/><stop offset="0.5" stop-color="#58a6ff" stop-opacity="0.8"/><stop offset="1" stop-color="#58a6ff" stop-opacity="0.05"/>
+    </linearGradient>
+    <filter id="glow" x="-100%" y="-100%" width="300%" height="300%">
+      <feGaussianBlur stdDeviation="2.5" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+    <clipPath id="gauge-clip"><rect x="416" y="319" width="304" height="14" rx="7"/></clipPath>
+    <style>
+      text { font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace; }
+      .heading { fill:#a5b3c4; font-size:14px; letter-spacing:1.6px; }
+      .step { fill:#64758b; font-size:12px; }
+      .label { fill:#a5b3c4; font-size:14px; }
+      .question { fill:#d5e4f5; font-size:14px; }
+      .number { fill:#79b8ff; font-size:13px; }
+      .reveal { animation:reveal .5s ease-out both; animation-delay:var(--at,0s); }
+      .bar { transform-box:fill-box; transform-origin:center bottom; animation:grow .55s cubic-bezier(.2,.7,.2,1) both; animation-delay:var(--at,1.4s); }
+      .keep { fill:#47c975; animation:keep-color .35s ease both; animation-delay:2.25s; }
+      .drop { fill:#506074; animation:drop-color .35s ease both; animation-delay:2.25s; }
+      .pointer { animation:pointer .55s cubic-bezier(.2,.7,.2,1) both; animation-delay:3.1s; }
+      .chosen { stroke-dasharray:170; animation:choose .65s ease-out both; animation-delay:3.8s; }
+      .packet { opacity:0; animation:packet .6s linear both; animation-delay:var(--at,1s); }
+      @keyframes reveal { from { opacity:0; } to { opacity:1; } }
+      @keyframes grow { from { transform:scaleY(0); } to { transform:scaleY(1); } }
+      @keyframes keep-color { from { fill:#79a6d5; } to { fill:#47c975; } }
+      @keyframes drop-color { from { fill:#79a6d5; } to { fill:#506074; } }
+      @keyframes pointer { from { transform:translateX(140px); opacity:0; } to { transform:translateX(0); opacity:1; } }
+      @keyframes choose { from { stroke-dashoffset:170; opacity:0; } to { stroke-dashoffset:0; opacity:1; } }
+      @keyframes packet { 0% { transform:translateX(0); opacity:0; } 20% { opacity:1; } 80% { opacity:1; } 100% { transform:translateX(48px); opacity:0; } }
+      @media (prefers-reduced-motion:reduce) {
+        .reveal,.bar,.keep,.drop,.pointer,.chosen { animation:none; }
+        .packet { display:none; }
+      }
+    </style>
+  </defs>
+
+  <rect width="1200" height="440" rx="16" fill="#0d1117"/>
+  <rect x=".5" y=".5" width="1199" height="439" rx="15.5" fill="url(#grid)" fill-opacity=".26" stroke="#28313c" stroke-opacity=".65"/>
+
+  <!-- A shared three-stage structure, with one illustrated event in each row. -->
+  <g class="reveal" style="--at:.08s">
+    <text class="step" x="44" y="46">01</text><text class="heading" x="74" y="46">PI EVENT</text>
+    <text class="step" x="382" y="46" fill="#79b8ff">02</text><text class="heading" x="412" y="46" style="fill:#bdd9fa">TYPED JEV REQUEST</text>
+    <text class="step" x="840" y="46">03</text><text class="heading" x="870" y="46">ACTION</text>
+  </g>
+  <rect x="44" y="72" width="288" height="324" rx="14" fill="#131920" stroke="#2c3540"/>
+  <rect x="382" y="72" width="408" height="324" rx="14" fill="url(#engine)" stroke="#395779"/>
+  <path d="M398 72H774" stroke="url(#engine-edge)" stroke-width="2"/>
+  <rect x="840" y="72" width="316" height="324" rx="14" fill="#131920" stroke="#2c3540"/>
+  <path d="M64 236H312M402 236H770M860 236H1136" stroke="#2c3540"/>
+  <g fill="none" stroke="#566578" stroke-width="1.5" stroke-linecap="round" stroke-linejoin="round">
+    <path d="M340 171H373M369 168L373 171L369 174M798 171H831M827 168L831 171L827 174M340 326H373M369 323L373 326L369 329M798 326H831M827 323L831 326L827 329"/>
+  </g>
+  <g fill="#79b8ff">
+    <circle class="packet" style="--at:1s" cx="338" cy="171" r="2.5"/>
+    <circle class="packet" style="--at:2.6s" cx="338" cy="326" r="2.5"/>
+    <circle class="packet" style="--at:2.65s" cx="794" cy="171" r="2.5"/>
+    <circle class="packet" style="--at:3.55s" cx="794" cy="326" r="2.5"/>
+  </g>
+
+  <!-- Compaction: the input and output share the same five row shapes. -->
+  <text class="label reveal" style="--at:.2s" x="66" y="105">compaction</text>
+
+  <g class="reveal" style="--at:0.35s">
+    <rect x="66" y="129" width="10" height="10" rx="2" fill="#1f2b39" stroke="#5c7189"/>
+    <path d="M69 134H73" stroke="#8395aa" stroke-width="1.3"/>
+    <rect x="88" y="131" width="146" height="6" rx="3" fill="#64758a"/>
+  </g>
+  <g class="reveal" style="--at:0.45s">
+    <rect x="66" y="147" width="10" height="10" rx="2" fill="#1f2b39" stroke="#5c7189"/>
+    <path d="M69 152H73" stroke="#8395aa" stroke-width="1.3"/>
+    <rect x="88" y="149" width="198" height="6" rx="3" fill="#64758a"/>
+  </g>
+  <g class="reveal" style="--at:0.55s">
+    <rect x="66" y="165" width="10" height="10" rx="2" fill="#1f2b39" stroke="#5c7189"/>
+    <path d="M69 170H73" stroke="#8395aa" stroke-width="1.3"/>
+    <rect x="88" y="167" width="126" height="6" rx="3" fill="#64758a"/>
+  </g>
+  <g class="reveal" style="--at:0.65s">
+    <rect x="66" y="183" width="10" height="10" rx="2" fill="#1f2b39" stroke="#5c7189"/>
+    <path d="M69 188H73" stroke="#8395aa" stroke-width="1.3"/>
+    <rect x="88" y="185" width="174" height="6" rx="3" fill="#64758a"/>
+  </g>
+  <g class="reveal" style="--at:0.75s">
+    <rect x="66" y="201" width="10" height="10" rx="2" fill="#1f2b39" stroke="#5c7189"/>
+    <path d="M69 206H73" stroke="#8395aa" stroke-width="1.3"/>
+    <rect x="88" y="203" width="158" height="6" rx="3" fill="#64758a"/>
+  </g>
+
+  <g class="reveal" style="--at:1.15s">
+    <rect x="412" y="91" width="84" height="26" rx="7" fill="#0e1621" stroke="#334963"/>
+    <text class="question" x="427" y="109">keep?</text>
+  </g>
+  <path class="reveal" style="--at:1.35s" d="M416 210H710" stroke="#3b4b60"/>
+
+  <g class="bar" style="--at:1.40s"><rect class="keep" x="432" y="152" width="32" height="58" rx="4"/></g>
+  <g class="bar" style="--at:1.49s"><rect class="drop" x="490" y="201" width="32" height="9" rx="4"/></g>
+  <g class="bar" style="--at:1.58s"><rect class="drop" x="548" y="200" width="32" height="10" rx="4"/></g>
+  <g class="bar" style="--at:1.67s"><rect class="drop" x="606" y="186" width="32" height="24" rx="4"/></g>
+  <g class="bar" style="--at:1.76s"><rect class="keep" x="664" y="150" width="32" height="60" rx="4"/></g>
+
+  <g class="reveal" style="--at:2.25s">
+    <path d="M416 172.5H710" fill="none" stroke="#79b8ff" stroke-width="1.5" stroke-dasharray="4 5"/>
+    <text class="number" x="723" y="177">0.5</text>
+  </g>
+  <text class="label reveal" style="--at:2.9s" x="862" y="105">verbatim</text>
+
+  <g class="reveal" style="--at:3.00s">
+    <g opacity="1">
+      <rect x="862" y="129" width="10" height="10" rx="2" fill="#47c975" stroke="#47c975"/>
+      <rect x="884" y="131" width="146" height="6" rx="3" fill="#85d9a3"/>
+
+      <path d="M864 134L866 136L870 132" fill="none" stroke="#0d3420" stroke-width="1.1"/>
+    </g>
+  </g>
+  <g class="reveal" style="--at:3.08s">
+    <g opacity="0.35">
+      <rect x="862" y="147" width="10" height="10" rx="2" fill="#19212b" stroke="#5b6777"/>
+      <rect x="884" y="149" width="198" height="6" rx="3" fill="#596677"/>
+
+      <path d="M864 155L870 149M881 152H1085" stroke="#7d8b9e" stroke-width="1.2"/>
+    </g>
+  </g>
+  <g class="reveal" style="--at:3.16s">
+    <g opacity="0.35">
+      <rect x="862" y="165" width="10" height="10" rx="2" fill="#19212b" stroke="#5b6777"/>
+      <rect x="884" y="167" width="126" height="6" rx="3" fill="#596677"/>
+
+      <path d="M864 173L870 167M881 170H1013" stroke="#7d8b9e" stroke-width="1.2"/>
+    </g>
+  </g>
+  <g class="reveal" style="--at:3.24s">
+    <g opacity="0.35">
+      <rect x="862" y="183" width="10" height="10" rx="2" fill="#19212b" stroke="#5b6777"/>
+      <rect x="884" y="185" width="174" height="6" rx="3" fill="#596677"/>
+
+      <path d="M864 191L870 185M881 188H1061" stroke="#7d8b9e" stroke-width="1.2"/>
+    </g>
+  </g>
+  <g class="reveal" style="--at:3.32s">
+    <g opacity="1">
+      <rect x="862" y="201" width="10" height="10" rx="2" fill="#47c975" stroke="#47c975"/>
+      <rect x="884" y="203" width="158" height="6" rx="3" fill="#85d9a3"/>
+
+      <path d="M864 206L866 208L870 204" fill="none" stroke="#0d3420" stroke-width="1.1"/>
+    </g>
+  </g>
+
+  <!-- Routing: a contiguous numeric scale drives a single lit branch. -->
+  <text class="label reveal" style="--at:.85s" x="66" y="269">routing</text>
+  <g class="reveal" style="--at:1s">
+    <path d="M78 298H286Q298 298 298 310V343Q298 355 286 355H91L78 367V355Q66 355 66 343V310Q66 298 78 298Z" fill="#0e141c" stroke="#3a4a5d"/>
+    <circle cx="86" cy="317" r="3" fill="#79b8ff"/>
+    <rect x="100" y="314" width="162" height="6" rx="3" fill="#64758a"/>
+    <rect x="84" y="334" width="114" height="5" rx="2.5" fill="#3e4e62"/>
+  </g>
+  <g class="reveal" style="--at:2.65s">
+    <rect x="412" y="255" width="132" height="26" rx="7" fill="#0e1621" stroke="#334963"/>
+    <text class="question" x="427" y="273">difficulty?</text>
+  </g>
+  <g class="reveal" style="--at:2.85s">
+    <g clip-path="url(#gauge-clip)">
+      <rect x="416" y="319" width="76" height="14" fill="#386ca6"/>
+      <rect x="492" y="319" width="152" height="14" fill="#354355"/>
+      <rect x="644" y="319" width="76" height="14" fill="#2b7550"/>
+    </g>
+    <path d="M492 311V342M644 311V342" fill="none" stroke="#8aa0ba" stroke-dasharray="3 4" stroke-opacity=".6"/>
+  </g>
+  <g class="pointer">
+    <path d="M462 313V339" stroke="#dcecff" stroke-width="3" stroke-linecap="round"/>
+    <circle cx="462" cy="326" r="3.5" fill="#dcecff" filter="url(#glow)"/>
+    <text class="number" x="462" y="364" text-anchor="middle">0.3</text>
+  </g>
+  <g class="reveal" style="--at:3.55s">
+    <path d="M862 326H908Q920 326 920 314V296Q920 284 932 284H984M908 326H984M908 326Q920 326 920 338V356Q920 368 932 368H984" fill="none" stroke="#465569" stroke-width="1.5"/>
+    <circle cx="992" cy="284" r="5" fill="#131920" stroke="#5c7189" stroke-width="1.5"/>
+    <circle cx="992" cy="326" r="5" fill="#131920" stroke="#5c7189" stroke-width="1.5"/>
+    <circle cx="992" cy="368" r="5" fill="#131920" stroke="#5c7189" stroke-width="1.5"/>
+    <text x="1009" y="289" font-size="15" fill="#78b7ff">cheap</text>
+    <text x="1009" y="331" font-size="15" fill="#7f90a5">current</text>
+    <text x="1009" y="373" font-size="15" fill="#7f90a5">strong</text>
+  </g>
+  <path class="chosen" d="M862 326H908Q920 326 920 314V296Q920 284 932 284H986" fill="none" stroke="#79b8ff" stroke-width="2.5" stroke-linecap="round"/>
+  <g class="reveal" style="--at:4.25s">
+    <circle cx="992" cy="284" r="5" fill="#79b8ff" filter="url(#glow)"/>
+    <text x="1009" y="289" font-size="15" fill="#bdd9fa">cheap</text>
+  </g>
+</svg>

package/package.json

@@ -0,0 +1,55 @@
+{
+  "name": "@alexlikevibe/pi-jev",
+  "version": "0.2.0",
+  "description": "Pi extension suite powered by Jev: selective context compaction and model routing, each an independently toggleable extension.",
+  "type": "module",
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "prepare": "npm run build",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run"
+  },
+  "bin": {
+    "pi-jev": "bin/pi-jev.js"
+  },
+  "files": [
+    "dist",
+    "bin",
+    "src",
+    "extensions",
+    "README.md",
+    "README.zh-CN.md",
+    "media",
+    "LICENSE"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/iefnaf/pi-jev.git"
+  },
+  "keywords": [
+    "pi",
+    "pi-extension",
+    "pi-package",
+    "jev",
+    "typesafe",
+    "compaction",
+    "model-routing",
+    "openrouter"
+  ],
+  "dependencies": {
+    "@narumitw/pi-tui-kit": "^0.65.0"
+  },
+  "devDependencies": {
+    "@earendil-works/pi-agent-core": "^0.85.1",
+    "@earendil-works/pi-ai": "^0.85.1",
+    "@earendil-works/pi-coding-agent": "^0.85.1",
+    "@types/node": "^22.10.2",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  }
+}

package/src/cli/main.ts

@@ -0,0 +1,241 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import {
+  CONFIG_KEYS,
+  configFromEnv,
+  loadConfig,
+  mergeConfigFiles,
+  readConfigFile,
+  type ConfigKeyMeta,
+  type JevFileConfig,
+} from '../shared/config.js';
+
+/** Injectable process surface, so tests can run the CLI against temp dirs. */
+export interface CliIo {
+  env: Record<string, string | undefined>;
+  globalPath: string;
+  projectPath: string;
+  out(text: string): void;
+  err(text: string): void;
+}
+
+const USAGE = `pi-jev — configuration CLI for the pi-jev extension suite
+
+Usage:
+  pi-jev config                          Show resolved config and each value's source
+  pi-jev config set <key> <value>        Write a key (global by default)
+  pi-jev config get <key>                Print the resolved value of a key
+  pi-jev config unset <key>              Remove a key
+  pi-jev config path                     Print the config file path
+  pi-jev config keys                     List all keys with types and env overrides
+
+Options:
+  -l, --project    Target the project file (.pi/jev.json) instead of the global one
+
+Sources resolve highest-first: environment variables > project file > global file > defaults.
+API keys are environment-only and never stored in files.
+Changes take effect after pi restarts or /reload.`;
+
+export function keyMeta(path: string): ConfigKeyMeta | undefined {
+  return CONFIG_KEYS.find((key) => key.path === path);
+}
+
+export function getPath(file: JevFileConfig, path: string): unknown {
+  const [section, key] = path.split('.');
+  if (!key) return (file as Record<string, unknown>)[section];
+  return (file as Record<string, Record<string, unknown>>)[section]?.[key];
+}
+
+export function setPath(file: JevFileConfig, path: string, value: unknown): void {
+  const [section, key] = path.split('.');
+  if (!key) {
+    (file as Record<string, unknown>)[section] = value;
+    return;
+  }
+  const holder = ((file as Record<string, Record<string, unknown>>)[section] ??= {});
+  holder[key] = value;
+}
+
+function deletePath(file: JevFileConfig, path: string): boolean {
+  const [section, key] = path.split('.');
+  if (!key) return delete (file as Record<string, unknown>)[section];
+  const holder = (file as Record<string, Record<string, unknown>>)[section];
+  if (!holder || !(key in holder)) return false;
+  delete holder[key];
+  if (Object.keys(holder).length === 0) delete (file as Record<string, unknown>)[section];
+  return true;
+}
+
+export function coerce(meta: ConfigKeyMeta, raw: string): string | number | boolean {
+  if (meta.type === 'number') {
+    const value = Number(raw);
+    if (!Number.isFinite(value)) throw new Error(`${meta.path}: expected a number, got "${raw}"`);
+    return value;
+  }
+  if (meta.type === 'boolean') {
+    if (/^(1|true|yes)$/i.test(raw)) return true;
+    if (/^(0|false|no)$/i.test(raw)) return false;
+    throw new Error(`${meta.path}: expected a boolean, got "${raw}"`);
+  }
+  const value = raw.trim();
+  if (!value) throw new Error(`${meta.path}: expected a non-empty value`);
+  if (meta.path === 'provider' && value !== 'typesafe' && value !== 'openrouter') {
+    throw new Error(`provider: expected "typesafe" or "openrouter", got "${value}"`);
+  }
+  return value;
+}
+
+export function readOrInit(path: string): JevFileConfig {
+  try {
+    return readConfigFile(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return {};
+    throw new Error(`cannot read ${path}: ${(error as Error).message}`);
+  }
+}
+
+export function saveFile(path: string, file: JevFileConfig): void {
+  mkdirSync(dirname(path), { recursive: true });
+  writeFileSync(path, JSON.stringify(file, null, 2) + '\n');
+}
+
+function takeProjectFlag(rest: string[]): { project: boolean; positional: string[] } {
+  const positional = rest.filter((arg) => arg !== '-l' && arg !== '--project');
+  return { project: positional.length !== rest.length, positional };
+}
+
+function tryReadFile(path: string, io: CliIo): JevFileConfig | undefined {
+  try {
+    return readConfigFile(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    io.err(`pi-jev: ignoring config at ${path} (${(error as Error).message})`);
+    return undefined;
+  }
+}
+
+export function valueAt(config: unknown, path: string): unknown {
+  const record = config as Record<string, unknown>;
+  // `compaction.*` keys are flat fields on JevConfig; `routing.*` is nested.
+  if (path.startsWith('compaction.')) return record[path.slice('compaction.'.length)];
+  const [section, key] = path.split('.');
+  if (!key) return record[section];
+  return (record[section] as Record<string, unknown> | undefined)?.[key];
+}
+
+export function formatValue(value: unknown): string {
+  if (value === undefined) return 'unset';
+  return String(value);
+}
+
+function show(io: CliIo): number {
+  const global = tryReadFile(io.globalPath, io);
+  const project = tryReadFile(io.projectPath, io);
+  const config = configFromEnv(io.env, mergeConfigFiles(global, project));
+  const width = Math.max(...CONFIG_KEYS.map((key) => key.path.length));
+  for (const meta of CONFIG_KEYS) {
+    const source = io.env[meta.env ?? '']?.trim()
+      ? 'env'
+      : getPath(project ?? {}, meta.path) !== undefined
+        ? 'project'
+        : getPath(global ?? {}, meta.path) !== undefined
+          ? 'global'
+          : 'default';
+    io.out(`${meta.path.padEnd(width)} = ${formatValue(valueAt(config, meta.path)).padEnd(28)} # ${source}`);
+  }
+  io.out(`${'apiKey'.padEnd(width)} = ${config.apiKey ? 'set' : 'unset'}${''.padEnd(23)} # env only`);
+  if (!config.routing.cheap && !config.routing.strong) {
+    io.err('# routing is disabled: set routing.cheap (or routing.strong) to enable it');
+  }
+  return 0;
+}
+
+/** Runs the CLI against injectable IO. Returns the process exit code. */
+export function runCli(argv: readonly string[], io: CliIo): number {
+  const [cmd, sub, ...rest] = argv;
+  if (cmd === undefined || cmd === 'help' || cmd === '--help' || cmd === '-h') {
+    io.out(USAGE);
+    return 0;
+  }
+  if (cmd !== 'config') {
+    io.err(`unknown command "${cmd}"`);
+    io.err(USAGE);
+    return 1;
+  }
+  try {
+    if (sub === undefined) return show(io);
+
+    // Actions: `pi-jev config set|get|unset <key> [value] [-l]`
+    if (sub === 'set') {
+      const { project, positional } = takeProjectFlag(rest);
+      const [keyPath, ...valueParts] = positional;
+      const meta = keyMeta(keyPath ?? '');
+      if (!meta) {
+        io.err(`unknown key "${keyPath}" (API keys are env-only). Run 'pi-jev config keys' to list valid keys.`);
+        return 1;
+      }
+      const raw = valueParts.join(' ');
+      if (!raw.trim()) {
+        io.err(`usage: pi-jev config set ${meta.path} <value>`);
+        return 1;
+      }
+      const value = coerce(meta, raw);
+      const targetPath = project ? io.projectPath : io.globalPath;
+      const file = readOrInit(targetPath);
+      setPath(file, meta.path, value);
+      saveFile(targetPath, file);
+      io.out(`set ${meta.path} = ${String(value)} (${project ? 'project' : 'global'}: ${targetPath})`);
+      return 0;
+    }
+
+    if (sub === 'get' || sub === 'unset') {
+      const { project, positional } = takeProjectFlag(rest);
+      const meta = keyMeta(positional[0] ?? '');
+      if (!meta) {
+        io.err(`unknown key "${positional[0]}" (API keys are env-only). Run 'pi-jev config keys' to list valid keys.`);
+        return 1;
+      }
+      const targetPath = project ? io.projectPath : io.globalPath;
+      if (sub === 'get') {
+        const config = loadConfig({ env: io.env, globalPath: io.globalPath, projectPath: io.projectPath, warn: io.err });
+        io.out(formatValue(valueAt(config, meta.path)));
+        return 0;
+      }
+      const file = readOrInit(targetPath);
+      if (deletePath(file, meta.path)) {
+        saveFile(targetPath, file);
+        io.out(`unset ${meta.path} (${project ? 'project' : 'global'}: ${targetPath})`);
+      } else {
+        io.out(`${meta.path} is not set (${project ? 'project' : 'global'})`);
+      }
+      return 0;
+    }
+
+    if (sub === 'path') {
+      const { project } = takeProjectFlag(rest);
+      io.out(project ? io.projectPath : io.globalPath);
+      return 0;
+    }
+
+    if (sub === 'keys') {
+      const width = Math.max(...CONFIG_KEYS.map((key) => key.path.length));
+      for (const meta of CONFIG_KEYS) {
+        io.out(`${meta.path.padEnd(width)}  ${meta.type.padEnd(7)} ${meta.env ? `env: ${meta.env.padEnd(26)} ` : ''}${meta.description}`);
+      }
+      return 0;
+    }
+
+    // Shorthand: `pi-jev config <key>` = get
+    const meta = keyMeta(sub);
+    if (!meta) {
+      io.err(`unknown key "${sub}" (API keys are env-only). Run 'pi-jev config keys' to list valid keys.`);
+      return 1;
+    }
+    const config = loadConfig({ env: io.env, globalPath: io.globalPath, projectPath: io.projectPath, warn: io.err });
+    io.out(formatValue(valueAt(config, meta.path)));
+    return 0;
+  } catch (error) {
+    io.err(`pi-jev: ${(error as Error).message}`);
+    return 1;
+  }
+}

package/src/commands/completions.ts

@@ -0,0 +1,107 @@
+import { CONFIG_KEYS } from '../shared/config.js';
+import type { ModelOption } from './models.js';
+
+/**
+ * Completion items as pi's autocomplete expects them: `value` replaces the
+ * entire argument text after `/jev `, so multi-word values carry the leading
+ * tokens (e.g. `"set routing.easyMax"`).
+ */
+export interface CompletionItem {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+const ACTIONS: CompletionItem[] = [
+  { value: 'set', label: 'set', description: 'write a key (add -l for the project file)' },
+  { value: 'get', label: 'get', description: 'print the resolved value of a key' },
+  { value: 'unset', label: 'unset', description: 'remove a key' },
+  { value: 'keys', label: 'keys', description: 'list all keys with types and env overrides' },
+  { value: 'path', label: 'path', description: 'print the config file path' },
+];
+
+const FLAG_RE = /^(-l|--project)$/;
+
+function filterItems(items: CompletionItem[], prefix: string): CompletionItem[] | null {
+  const normalized = prefix.trim().toLowerCase();
+  const matches = items.filter((item) => item.value.toLowerCase().startsWith(normalized));
+  return matches.length > 0 ? matches : null;
+}
+
+function keyItems(action: string): CompletionItem[] {
+  return CONFIG_KEYS.map((meta) => ({
+    value: `${action} ${meta.path}`,
+    label: meta.path,
+    description: meta.description,
+  }));
+}
+
+/** Enum-valued keys offer their options; free-form keys get no value completion. */
+export const VALUE_OPTIONS: Record<string, { label: string; description: string }[]> = {
+  provider: [
+    { label: 'openrouter', description: 'OpenRouter Decisions API' },
+    { label: 'typesafe', description: 'TypeSafe System One' },
+  ],
+  disabled: [
+    { label: 'true', description: 'bypass all pi-jev hooks' },
+    { label: 'false', description: 'enable pi-jev hooks' },
+  ],
+};
+
+/**
+ * Completes the argument text after `/jev `. Flags are position-neutral; the
+ * last non-flag token in progress decides what is offered.
+ */
+/** Model refs for cheap/strong value completion; empty when no snapshot is available. */
+const modelOptions: ModelOption[] = [];
+
+/** Refreshes the model snapshot (called on session_start). */
+export function setModelOptions(options: readonly ModelOption[]): void {
+  modelOptions.length = 0;
+  modelOptions.push(...options);
+}
+
+export function completeJevArguments(argText: string): CompletionItem[] | null {
+  const endsWithSpace = /\s$/.test(argText);
+  const tokens = argText.trim().split(/\s+/).filter(Boolean);
+  const prior = (endsWithSpace ? tokens : tokens.slice(0, -1)).filter((token) => !FLAG_RE.test(token));
+  const partial = endsWithSpace || tokens.length === 0 ? '' : tokens[tokens.length - 1];
+
+  // Completing the action itself.
+  if (prior.length === 0 && !endsWithSpace) {
+    return filterItems(ACTIONS, partial);
+  }
+  if (prior.length === 0) return ACTIONS; // space typed, nothing yet: offer the menu
+
+  const action = prior[0];
+  const flags = argText.trim().split(/\s+/).some((token) => FLAG_RE.test(token));
+  const suffix = flags ? ' -l' : '';
+
+  if (action === 'set' || action === 'get' || action === 'unset') {
+    if (prior.length === 1) {
+      const items = keyItems(action + suffix);
+      return filterItems(items, `${action}${suffix} ${partial}`.trim());
+    }
+    if (action === 'set' && prior.length === 2) {
+      const key = prior[1];
+      if (key === 'routing.cheap' || key === 'routing.strong') {
+        if (modelOptions.length === 0) return null;
+        const items = modelOptions.map((model) => ({
+          value: `set ${key} ${model.ref}${suffix}`,
+          label: model.name,
+          description: `${model.provider}${model.image ? ' · images' : ''}${model.reasoning ? ' · thinking' : ''}`,
+        }));
+        return filterItems(items, `set ${key}${suffix} ${partial}`.trim());
+      }
+      const options = VALUE_OPTIONS[key] ?? [];
+      if (options.length === 0) return null;
+      const items = options.map((option) => ({
+        value: `set ${key} ${option.label}${suffix}`,
+        label: option.label,
+        description: option.description,
+      }));
+      return filterItems(items, `set ${key}${suffix} ${partial}`.trim());
+    }
+  }
+  return null;
+}

package/src/commands/extension.ts

@@ -0,0 +1,61 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { completeJevArguments, setModelOptions, type CompletionItem } from './completions.js';
+import { modelsFromContext } from './models.js';
+import { runCli, type CliIo } from '../cli/main.js';
+import { defaultConfigPaths } from '../shared/config.js';
+
+/**
+ * Core of the `/jev` command: same engine as the `pi-jev` CLI. Split out so
+ * tests can drive it against temp config files.
+ */
+export function runJevCommand(rawArgs: string, io: CliIo): number {
+  const argv = rawArgs.trim().split(/\s+/).filter(Boolean);
+  if (argv[0] === 'config') argv.shift(); // tolerate `/jev config ...`
+  return runCli(argv.length > 0 ? ['config', ...argv] : ['config'], io);
+}
+
+/**
+ * The command extension: `/jev` configures the suite from inside pi.
+ * Config is re-read by every hook, so changes apply without a restart.
+ *
+ *   /jev                      show resolved values + each value's source
+ *   /jev set <key> <value>    write a key (`-l` targets the project file)
+ *   /jev get <key>            /jev unset <key>   /jev keys   /jev path
+ */
+export default function (pi: ExtensionAPI): void {
+  pi.on('session_start', (_event, ctx) => {
+    setModelOptions(modelsFromContext(ctx));
+  });
+
+  pi.registerCommand('jev', {
+    description: 'Configure pi-jev: /jev [set|get|unset|keys|path] ...',
+    getArgumentCompletions: (prefix: string): CompletionItem[] | null => completeJevArguments(prefix),
+    handler: async (args, ctx) => {
+      const paths = defaultConfigPaths();
+      if (!(args ?? '').trim()) {
+        // Bare /jev opens the interactive settings menu (TUI mode only).
+        const { openJevSettingsMenu } = await import('./menu.js');
+        await openJevSettingsMenu(ctx, paths, {
+          out: (text) => {
+            ctx.ui.notify(text, 'info');
+          },
+        });
+        return;
+      }
+      const lines: string[] = [];
+      const errs: string[] = [];
+      const code = runJevCommand(args ?? '', {
+        env: process.env,
+        ...defaultConfigPaths(),
+        out: (text) => {
+          lines.push(text);
+        },
+        err: (text) => {
+          errs.push(text);
+        },
+      });
+      const text = [...lines, ...errs].join('\n').trim();
+      ctx.ui.notify(text || '(no output)', code === 0 ? 'info' : 'error');
+    },
+  });
+}