@alexlikevibe/pi-jev 0.2.0

package/src/compaction/extension.ts

@@ -0,0 +1,235 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import type { AgentMessage } from '@earendil-works/pi-agent-core';
+import type { Usage } from '@earendil-works/pi-ai';
+import {
+  JevClient,
+  estimateTokens,
+  goalFromMessages,
+  type JevAsker,
+} from '../vendor/fast-jev-compaction/index.js';
+import { loadConfig, type JevCompactionConfig } from '../shared/config.js';
+import { convertMessages } from './convert.js';
+import { compactWithJev, type JevCompactionStats } from './jev.js';
+import { renderSummary, renderTranscript } from './summarize.js';
+
+/** The slice of `SessionBeforeCompactEvent` the compaction core needs. */
+export interface CompactionSpanInput {
+  messagesToSummarize: readonly AgentMessage[];
+  turnPrefixMessages: readonly AgentMessage[];
+  previousSummary?: string;
+  customInstructions?: string;
+  firstKeptEntryId: string;
+  tokensBefore: number;
+}
+
+export interface JevDetails {
+  engine: 'jev';
+  stats: JevCompactionStats;
+  decisions: Array<{
+    id: string;
+    tool: string;
+    action: string;
+    reason: string;
+    keepCall: number;
+    keepResult: number;
+  }>;
+}
+
+export type JevCompactionRun =
+  | {
+      ok: true;
+      compaction: {
+        summary: string;
+        firstKeptEntryId: string;
+        tokensBefore: number;
+        estimatedTokensAfter: number;
+        usage?: Usage;
+        details: JevDetails;
+      };
+      reduction: number;
+    }
+  | {
+      ok: false;
+      reason: 'empty-span' | 'low-reduction';
+      reduction: number;
+    };
+
+function toUsage(jev: { input: number; output: number }): Usage {
+  const total = jev.input + jev.output;
+  return {
+    input: jev.input,
+    output: jev.output,
+    cacheRead: 0,
+    cacheWrite: 0,
+    totalTokens: total,
+    cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0, total: 0 },
+  };
+}
+
+/**
+ * Core pipeline, separated from the extension hook so tests can drive it with
+ * a fake `JevAsker`. Converts the span, asks Jev which tool calls and results
+ * still matter, and renders the surviving transcript verbatim as the
+ * compaction summary. Returns `ok: false` when the span is empty or the
+ * estimated reduction is below `config.minReduction` (caller falls back to
+ * pi's default compaction). Throws when Jev fails; the caller decides.
+ */
+export async function runJevCompaction(
+  input: CompactionSpanInput,
+  asker: JevAsker,
+  config: JevCompactionConfig,
+): Promise<JevCompactionRun> {
+  const span = [...input.messagesToSummarize, ...input.turnPrefixMessages];
+  const converted = convertMessages(span);
+  if (converted.length === 0) {
+    return { ok: false, reason: 'empty-span', reduction: 0 };
+  }
+
+  const goal = input.customInstructions?.trim() || goalFromMessages(converted);
+  const outcome = await compactWithJev(converted, asker, config, goal);
+
+  const summary = renderSummary(outcome.messages, {
+    goal,
+    previousSummary: input.previousSummary,
+    droppedCalls: outcome.stats.callsDropped,
+    truncatedResults: outcome.stats.resultsDropped,
+  });
+
+  // Size estimation in one consistent unit: render the original and the
+  // compacted span with the same renderer. The previous summary is a fixed
+  // cost on both sides, so the reduction ignores it.
+  const spanTokens = estimateTokens(renderTranscript(converted));
+  const keptTokens = estimateTokens(renderTranscript(outcome.messages));
+  const summaryTokens = estimateTokens(summary);
+  const reduction = spanTokens === 0 ? 0 : 1 - keptTokens / spanTokens;
+
+  if (reduction < config.minReduction) {
+    return { ok: false, reason: 'low-reduction', reduction };
+  }
+
+  return {
+    ok: true,
+    reduction,
+    compaction: {
+      summary,
+      firstKeptEntryId: input.firstKeptEntryId,
+      tokensBefore: input.tokensBefore,
+      estimatedTokensAfter: Math.max(summaryTokens, input.tokensBefore - spanTokens + summaryTokens),
+      usage: outcome.stats.jevUsage ? toUsage(outcome.stats.jevUsage) : undefined,
+      details: {
+        engine: 'jev',
+        stats: outcome.stats,
+        decisions: outcome.decisions.map(decision => ({
+          id: decision.id,
+          tool: decision.tool,
+          action: decision.action,
+          reason: decision.reason,
+          keepCall: decision.keepCall,
+          keepResult: decision.keepResult,
+        })),
+      },
+    },
+  };
+}
+
+function raceAbort<T>(promise: Promise<T>, signal: AbortSignal | undefined): Promise<T> {
+  if (!signal) return promise;
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => reject(new Error('aborted'));
+    if (signal.aborted) {
+      onAbort();
+      return;
+    }
+    signal.addEventListener('abort', onAbort, { once: true });
+    promise.then(
+      value => {
+        signal.removeEventListener('abort', onAbort);
+        resolve(value);
+      },
+      error => {
+        signal.removeEventListener('abort', onAbort);
+        reject(error);
+      },
+    );
+  });
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The extension: on `session_before_compact`, replace pi's LLM-generated
+ * summary with a Jev-compacted verbatim transcript. Any failure, abort, or
+ * insufficient reduction falls back to pi's default compaction.
+ */
+export default function (pi: ExtensionAPI): void {
+  pi.on('session_start', async (_event, ctx) => {
+    const config = loadConfig();
+    if (config.disabled) return;
+    ctx.ui.notify(
+      config.apiKey
+        ? `jev-compaction active (Jev via ${config.provider}): stale tool outputs are dropped, not summarized`
+        : 'jev-compaction: set TYPESAFE_API_KEY or OPENROUTER_API_KEY (or JEVC_API_KEY/JEVC_PROVIDER) to enable; using default compaction',
+      config.apiKey ? 'info' : 'warning',
+    );
+  });
+
+  pi.on('session_before_compact', async (event, ctx) => {
+    // Loaded per event so `/jev set` applies without a restart.
+    const config = loadConfig();
+    if (config.disabled || !config.apiKey) return;
+    if (event.signal?.aborted) return;
+
+    const { preparation, customInstructions } = event;
+    const asker = new JevClient({
+      apiKey: config.apiKey,
+      model: config.model,
+      baseUrl: config.baseUrl,
+    });
+
+    try {
+      const run = await raceAbort(
+        runJevCompaction(
+          {
+            messagesToSummarize: preparation.messagesToSummarize,
+            turnPrefixMessages: preparation.turnPrefixMessages,
+            previousSummary: preparation.previousSummary,
+            customInstructions,
+            firstKeptEntryId: preparation.firstKeptEntryId,
+            tokensBefore: preparation.tokensBefore,
+          },
+          asker,
+          config,
+        ),
+        event.signal,
+      );
+
+      if (!run.ok) {
+        if (run.reason === 'low-reduction') {
+          ctx.ui.notify(
+            `jev-compaction: only ${(run.reduction * 100).toFixed(0)}% reduction; using default compaction`,
+            'warning',
+          );
+        }
+        return; // undefined result -> pi runs its default compaction
+      }
+
+      const stats = run.compaction.details.stats;
+      ctx.ui.notify(
+        `jev-compaction: ${stats.calls - stats.pinned} calls scored — kept ${stats.kept - stats.pinned}, ` +
+          `truncated ${stats.resultsDropped}, dropped ${stats.callsDropped} ` +
+          `(${stats.requests} Jev req, ${(run.reduction * 100).toFixed(0)}% smaller, ${stats.ms} ms)`,
+        'info',
+      );
+      return { compaction: run.compaction };
+    } catch (error) {
+      if (event.signal?.aborted) return;
+      ctx.ui.notify(
+        `jev-compaction failed (${errorMessage(error)}); using default compaction`,
+        'error',
+      );
+      return;
+    }
+  });
+}

package/src/compaction/jev.ts

@@ -0,0 +1,133 @@
+import {
+  applyJevDecisions,
+  batchCalls,
+  decideCall,
+  questionsFor,
+  type DecisionOutcome,
+} from './decision.js';
+import {
+  collectToolCalls,
+  fitState,
+  goalFromMessages,
+  messageChars,
+  resolveOptions,
+  type JevAnswer,
+  type JevAsker,
+  type JevQuestions,
+  type Message,
+  type ToolCall,
+} from '../vendor/fast-jev-compaction/index.js';
+import type { JevCompactionConfig } from '../shared/config.js';
+
+export interface JevCompactionStats {
+  messagesBefore: number;
+  messagesAfter: number;
+  charsBefore: number;
+  charsAfter: number;
+  calls: number;
+  kept: number;
+  resultsDropped: number;
+  callsDropped: number;
+  pinned: number;
+  /** Borderline results kept because of a confident low-staleness score. */
+  guarded: number;
+  /** Calls whose answers were missing/malformed; kept conservatively. */
+  missing: number;
+  stateTokens: number;
+  stateStage: string;
+  requests: number;
+  ms: number;
+  jevUsage?: { input: number; output: number };
+}
+
+export interface JevCompactionOutcome {
+  /** Compacted transcript; untouched messages are the input objects. */
+  messages: Message[];
+  decisions: DecisionOutcome[];
+  stats: JevCompactionStats;
+}
+
+/**
+ * Compacts the converted span with Jev: every non-pinned tool call gets two
+ * `noul` questions (keep the call, keep its result verbatim) plus one `score`
+ * question (result staleness) whose confident answer can rescue a borderline
+ * result. Batches run concurrently; the same fitted state is sent with each.
+ */
+export async function compactWithJev(
+  messages: readonly Message[],
+  asker: JevAsker,
+  config: JevCompactionConfig,
+  goal?: string,
+): Promise<JevCompactionOutcome> {
+  const started = Date.now();
+  const resolvedGoal = goal?.trim() || goalFromMessages(messages);
+  const resolved = resolveOptions({
+    goal: resolvedGoal,
+    keepThreshold: config.keepThreshold,
+    preserveRecentMessages: config.preserveRecentMessages,
+    maxStateTokens: config.maxStateTokens,
+    maxRequestTokens: config.maxRequestTokens,
+    truncateHeadChars: config.truncateHeadChars,
+  });
+
+  const calls = collectToolCalls(messages, resolved.preserveRecentMessages);
+  const candidates = calls.filter(call => !call.pinned);
+
+  const answers: Record<string, JevAnswer> = {};
+  let stateTokens = 0;
+  let stateStage = '';
+  let batches: ToolCall[][] = [];
+  let jevUsage: { input: number; output: number } | undefined;
+
+  if (candidates.length > 0) {
+    const fitted = fitState(messages, calls, resolved);
+    stateTokens = fitted.tokens;
+    stateStage = fitted.stage;
+    batches = batchCalls(candidates, stateTokens, config.maxRequestTokens);
+    const responses = await Promise.all(
+      batches.map(async batch => {
+        const questions: JevQuestions = Object.assign({}, ...batch.map(questionsFor));
+        return asker.ask(fitted.state, questions);
+      }),
+    );
+    for (const response of responses) {
+      Object.assign(answers, response.answers);
+      if (response.usage) {
+        const input = response.usage.input_tokens ?? 0;
+        const output = response.usage.output_tokens ?? 0;
+        jevUsage = jevUsage
+          ? { input: jevUsage.input + input, output: jevUsage.output + output }
+          : { input, output };
+      }
+    }
+  }
+
+  const decisions = calls.map(call => decideCall(call, answers, config));
+  const kept = applyJevDecisions(messages, decisions, calls, resolved.truncateHeadChars);
+
+  const count = (predicate: (decision: ReturnType<typeof decideCall>) => boolean): number =>
+    decisions.filter(predicate).length;
+
+  return {
+    messages: kept,
+    decisions,
+    stats: {
+      messagesBefore: messages.length,
+      messagesAfter: kept.length,
+      charsBefore: messages.reduce((sum, message) => sum + messageChars(message), 0),
+      charsAfter: kept.reduce((sum, message) => sum + messageChars(message), 0),
+      calls: calls.length,
+      kept: count(decision => decision.action === 'keep' && !decision.pinned),
+      resultsDropped: count(decision => decision.action === 'drop_result'),
+      callsDropped: count(decision => decision.action === 'drop_call'),
+      pinned: count(decision => decision.pinned),
+      guarded: count(decision => decision.guarded),
+      missing: count(decision => decision.missing),
+      stateTokens,
+      stateStage,
+      requests: batches.length,
+      ms: Date.now() - started,
+      jevUsage,
+    },
+  };
+}

package/src/compaction/summarize.ts

@@ -0,0 +1,80 @@
+import type { Message } from '../vendor/fast-jev-compaction/index.js';
+
+const ARG_VALUE_LIMIT = 160;
+
+function argValue(value: unknown): string {
+  let text: string;
+  if (typeof value === 'string') text = value;
+  else {
+    try {
+      text = JSON.stringify(value) ?? String(value);
+    } catch {
+      text = '[unserializable]';
+    }
+  }
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length <= ARG_VALUE_LIMIT ? flat : `${flat.slice(0, ARG_VALUE_LIMIT - 1)}…`;
+}
+
+function renderCall(name: string, input: Record<string, unknown>): string {
+  const args = Object.entries(input)
+    .map(([key, value]) => `${key}=${argValue(value)}`)
+    .join(' ');
+  return args.length > 0 ? `${name}(${args})` : name;
+}
+
+/**
+ * Renders messages as a flat transcript in the same style pi uses for
+ * summarization, so the LLM reads a familiar format. Applied to both the
+ * original and the compacted span, it doubles as the size estimator.
+ */
+export function renderTranscript(messages: readonly Message[]): string {
+  const lines: string[] = [];
+  for (const message of messages) {
+    const trimmed = message.text.trim();
+    if (trimmed.length > 0) {
+      lines.push(`[${message.role === 'user' ? 'User' : 'Assistant'}]: ${trimmed}`);
+    }
+    if (message.toolUses.length > 0) {
+      lines.push(`[Assistant tool calls]: ${message.toolUses.map(call => renderCall(call.tool, call.input)).join('; ')}`);
+    }
+    for (const result of message.toolResults ?? []) {
+      lines.push(`[Tool result]: ${result.text.trim()}`);
+    }
+  }
+  return lines.join('\n\n');
+}
+
+export interface SummaryOptions {
+  goal?: string;
+  previousSummary?: string;
+  droppedCalls?: number;
+  truncatedResults?: number;
+}
+
+/**
+ * Builds the compaction summary: the previous summary (kept verbatim, it is
+ * already compact) followed by the Jev-retained transcript wrapped in a note
+ * explaining what the truncation markers mean.
+ */
+export function renderSummary(messages: readonly Message[], options: SummaryOptions = {}): string {
+  const parts: string[] = [];
+
+  const previous = options.previousSummary?.trim();
+  if (previous) {
+    parts.push(`<summary-of-earlier-context>\n${previous}\n</summary-of-earlier-context>`);
+  }
+
+  const header = [
+    'Earlier conversation retained by Jev selective compaction.',
+    'User and assistant text is verbatim.',
+  ];
+  if ((options.droppedCalls ?? 0) > 0) header.push(`${options.droppedCalls} obsolete tool calls were removed.`);
+  if ((options.truncatedResults ?? 0) > 0) {
+    header.push(`${options.truncatedResults} tool results were truncated (marked); re-run a tool if its full output is needed again.`);
+  }
+  if (options.goal?.trim()) header.push(`Ongoing goal: ${options.goal.trim()}`);
+
+  parts.push(`<compacted-conversation>\n${header.join(' ')}\n\n${renderTranscript(messages)}\n</compacted-conversation>`);
+  return parts.join('\n\n');
+}

package/src/routing/decide.ts

@@ -0,0 +1,81 @@
+import type { JevAnswer, JevQuestions } from '../vendor/fast-jev-compaction/index.js';
+import type { RoutingConfig } from '../shared/config.js';
+
+export const DIFFICULTY_LEVELS = ['trivial', 'moderate', 'complex'] as const;
+
+export const ROUTING_CONTEXT =
+  'A coding assistant is about to start a turn. `prompt` is the user request starting it. The question rates how demanding the request is for the assistant, so that easy requests can go to a cheaper model and hard ones to a stronger model.';
+
+export function routingQuestions(): JevQuestions {
+  return {
+    difficulty: {
+      type: 'score',
+      instructions: `Rate how demanding this coding request is: level 0 is trivial (greetings, quick questions, simple lookups, formatting, single-file mechanical edits), level ${DIFFICULTY_LEVELS.length - 1} is complex (multi-file refactors, subtle debugging, architecture decisions)`,
+      criteria: [...DIFFICULTY_LEVELS],
+    },
+  };
+}
+
+export type RoutingTarget = 'cheap' | 'strong' | null;
+
+export interface RoutingDecision {
+  target: RoutingTarget;
+  /** Raw Jev score, as returned. */
+  score: number;
+  /** Score mapped to the 0..4 level space (see `decideRouting`). */
+  levels: number;
+  confidence: number;
+  reason: 'easy' | 'hard' | 'middle' | 'low-confidence' | 'missing-answer';
+}
+
+function scoreFrom(answers: Record<string, JevAnswer>): { score: number; confidence: number } | undefined {
+  const answer = answers.difficulty;
+  if (
+    answer === null ||
+    typeof answer !== 'object' ||
+    !('score' in answer) ||
+    typeof (answer as { score?: unknown }).score !== 'number' ||
+    !Number.isFinite((answer as { score: number }).score)
+  ) {
+    return undefined;
+  }
+  const confidence =
+    'confidence' in answer && typeof (answer as { confidence?: unknown }).confidence === 'number'
+      ? (answer as { confidence: number }).confidence
+      : 0;
+  return { score: (answer as { score: number }).score, confidence };
+}
+
+/**
+ * Maps a Jev score to the 0..N level space (N = levels - 1), clamped. Jev returns either a 0..1
+ * continuous score or a level index; `score <= 1` is read as normalized
+ * (a literal 1 therefore means "hardest", the conservative direction).
+ */
+export function toLevels(score: number): number {
+  const span = DIFFICULTY_LEVELS.length - 1;
+  return Math.min(span, Math.max(0, (score <= 1 ? score : score / span) * span));
+}
+/**
+ * Pure decision: easy requests go to the cheap model, hard ones to the strong
+ * model, everything else (middle band, low confidence, missing or malformed
+ * answer) keeps the current model.
+ */
+export function decideRouting(answers: Record<string, JevAnswer>, config: RoutingConfig): RoutingDecision {
+  const answer = scoreFrom(answers);
+  if (!answer) {
+    return { target: null, score: 0, levels: 0, confidence: 0, reason: 'missing-answer' };
+  }
+  const levels = toLevels(answer.score);
+  const base = { score: answer.score, levels, confidence: answer.confidence };
+
+  if (answer.confidence < config.minConfidence) {
+    return { ...base, target: null, reason: 'low-confidence' };
+  }
+  if (config.cheap && levels <= config.easyMax) {
+    return { ...base, target: 'cheap', reason: 'easy' };
+  }
+  if (config.strong && levels >= config.hardMin) {
+    return { ...base, target: 'strong', reason: 'hard' };
+  }
+  return { ...base, target: null, reason: 'middle' };
+}

package/src/routing/extension.ts

@@ -0,0 +1,92 @@
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+import { JevClient, type JevAsker } from '../vendor/fast-jev-compaction/index.js';
+import { loadConfig, type RoutingConfig } from '../shared/config.js';
+import { decideRouting, DIFFICULTY_LEVELS, ROUTING_CONTEXT, routingQuestions, type RoutingDecision } from './decide.js';
+
+/** Asks Jev to rate the request difficulty and maps it to a routing target. */
+export async function runRouting(
+  prompt: string,
+  asker: JevAsker,
+  config: RoutingConfig,
+): Promise<RoutingDecision> {
+  const response = await asker.ask({ context: ROUTING_CONTEXT, prompt }, routingQuestions());
+  return decideRouting(response.answers, config);
+}
+
+/**
+ * Parses a `"provider/model-id"` reference, optionally with a `:thinking`
+ * suffix (pi style, e.g. `deepseek/deepseek-flash:high`).
+ */
+export function parseModelRef(ref: string): { provider: string; id: string; thinking?: string } | undefined {
+  const slash = ref.indexOf('/');
+  if (slash <= 0 || slash === ref.length - 1) return undefined;
+  const rest = ref.slice(slash + 1);
+  const colon = rest.lastIndexOf(':');
+  if (colon > 0) {
+    const thinking = rest.slice(colon + 1);
+    if (thinking) return { provider: ref.slice(0, slash), id: rest.slice(0, colon), thinking };
+  }
+  return { provider: ref.slice(0, slash), id: rest };
+}
+
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * The routing extension: before each agent turn, Jev rates the request
+ * difficulty; confidently easy requests switch to `JEVC_ROUTE_CHEAP`,
+ * confidently hard ones to `JEVC_ROUTE_STRONG`. Every other outcome (middle
+ * band, low confidence, Jev failure, model not found, auth missing) keeps the
+ * current model. Prompts with images never downgrade to a text-only model.
+ */
+export default function (pi: ExtensionAPI): void {
+  pi.on('before_agent_start', async (event, ctx) => {
+    // Loaded per turn so `/jev set` applies without a restart.
+    const config = loadConfig();
+    const routing = config.routing;
+    if (config.disabled || !config.apiKey) return;
+    if (!routing.cheap && !routing.strong) return;
+    if (!event.prompt.trim()) return;
+
+    try {
+      const decision = await runRouting(
+        event.prompt,
+        new JevClient({ apiKey: config.apiKey, model: config.model, baseUrl: config.baseUrl }),
+        routing,
+      );
+      if (!decision.target) return;
+
+      const ref = parseModelRef(decision.target === 'cheap' ? routing.cheap! : routing.strong!);
+      if (!ref) {
+        ctx.ui.notify(`jev-routing: invalid JEVC_ROUTE_${decision.target.toUpperCase()} reference`, 'warning');
+        return;
+      }
+      const model = ctx.modelRegistry.find(ref.provider, ref.id);
+      if (!model) {
+        ctx.ui.notify(`jev-routing: ${ref.provider}/${ref.id} not found; keeping current model`, 'warning');
+        return;
+      }
+      if (ctx.model && ctx.model.id === model.id && ctx.model.provider === model.provider) return;
+      if (decision.target === 'cheap' && (event.images?.length ?? 0) > 0 && !model.input.includes('image')) {
+        return; // never route an image prompt to a text-only model
+      }
+
+      const switched = await pi.setModel(model);
+      if (!switched) {
+        ctx.ui.notify(`jev-routing: auth not configured for ${ref.provider}/${ref.id}; keeping current model`, 'warning');
+        return;
+      }
+      if (ref.thinking) {
+        pi.setThinkingLevel(ref.thinking as Parameters<typeof pi.setThinkingLevel>[0]);
+      }
+      ctx.ui.notify(
+        `jev-routing: ${decision.reason} request (difficulty ${decision.levels.toFixed(1)}/${DIFFICULTY_LEVELS.length - 1}, ` +
+          `confidence ${(decision.confidence * 100).toFixed(0)}%) → ${ref.provider}/${ref.id}`,
+        'info',
+      );
+    } catch (error) {
+      ctx.ui.notify(`jev-routing failed (${errorMessage(error)}); keeping current model`, 'error');
+    }
+  });
+}