@alexlikevibe/pi-jev 0.2.0

package/src/shared/config.ts

@@ -0,0 +1,280 @@
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { DEFAULT_MODEL, SYSTEM_ONE_URL } from '../vendor/fast-jev-compaction/index.js';
+
+/**
+ * Shared configuration for the pi-jev extension suite. Values resolve from
+ * layered sources, highest first: environment variables (prefix `JEVC_`), a
+ * project file (`.pi/jev.json`), a global file (`~/.pi/agent/jev.json`), then
+ * defaults. Each extension in `extensions/` reads the parts it needs;
+ * enabling/disabling an extension itself is done with `pi config`, not env
+ * flags.
+ *
+ * The `pi-jev config` CLI writes those files; API keys stay env-only.
+ *
+ * Jev can be reached through two transports with identical request/response
+ * shapes (`{ model, state, questions }` → `{ answers }`):
+ *
+ * - `typesafe`   — the TypeSafe System One endpoint (`TYPESAFE_API_KEY`)
+ * - `openrouter` — OpenRouter's Decisions API (`OPENROUTER_API_KEY`), which
+ *   forwards to TypeSafe directly
+ */
+
+export type JevProvider = 'typesafe' | 'openrouter';
+
+/** OpenRouter Decisions API (alpha). */
+export const OPENROUTER_DECISIONS_URL = 'https://openrouter.ai/api/alpha/decisions';
+/** Default Jev model slug on OpenRouter (versioned; override with `JEVC_MODEL`). */
+export const OPENROUTER_JEV_MODEL = 'typesafe/jev-1.13';
+
+/** Compaction feature options (consumed by src/compaction/*). */
+export interface JevCompactionConfig {
+  /** Transport selected via `JEVC_PROVIDER` or auto-detected from keys. */
+  provider: JevProvider;
+  /** API key for the selected transport (from `JEVC_API_KEY` or the transport's own variable). */
+  apiKey: string;
+  /** Resolved Jev model slug (already provider-specific). */
+  model: string;
+  /** Resolved endpoint URL. */
+  baseUrl: string;
+  /** Minimum keep probability for a call or result to stay verbatim. */
+  keepThreshold: number;
+  /** Band under `keepThreshold` where a confident low-staleness score still keeps a result. */
+  borderline: number;
+  /** Newest messages within the summarized span that are never touched. */
+  preserveRecentMessages: number;
+  /** Characters of a dropped tool result retained before its note. */
+  truncateHeadChars: number;
+  /** Minimum estimated span reduction, or the feature falls back to default compaction. */
+  minReduction: number;
+  /** Estimated token ceiling for the Jev state. */
+  maxStateTokens: number;
+  /** Estimated ceiling for state plus one batch of questions. */
+  maxRequestTokens: number;
+  /** Set via `JEVC_DISABLED` to bypass the hooks entirely (all features). */
+  disabled: boolean;
+}
+
+/** Model-routing feature options (consumed by src/routing/*). */
+export interface RoutingConfig {
+  /** Easy-request target, `"provider/model-id"`. Routing is enabled when cheap or strong is set. */
+  cheap: string | undefined;
+  /** Hard-request target, `"provider/model-id"`; optional. */
+  strong: string | undefined;
+  /** Difficulty level (0..2) at or below which the cheap model is used. */
+  easyMax: number;
+  /** Difficulty level (0..2) at or above which the strong model is used. */
+  hardMin: number;
+  /** Minimum Jev confidence to act on a decision. */
+  minConfidence: number;
+}
+
+export interface JevConfig extends JevCompactionConfig {
+  routing: RoutingConfig;
+}
+
+const DEFAULTS = {
+  keepThreshold: 0.5,
+  borderline: 0.1,
+  /** Small: pi already excludes the newest ~20k tokens from the span. */
+  preserveRecentMessages: 3,
+  truncateHeadChars: 300,
+  minReduction: 0.15,
+  maxStateTokens: 25_000,
+  maxRequestTokens: 30_000,
+  easyMax: 0.5,
+  hardMin: 1.5,
+  minConfidence: 0.6,
+};
+
+function number(env: Record<string, string | undefined>, key: string, fallback: number): number {
+  const raw = env[key];
+  if (raw === undefined || raw.trim() === '') return fallback;
+  const value = Number(raw);
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function flag(env: Record<string, string | undefined>, key: string): boolean {
+  return /^(1|true|yes)$/i.test(env[key] ?? '');
+}
+
+/** Boolean with source precedence: an explicitly set env value (even `0`) wins over the file. */
+function layeredFlag(env: Record<string, string | undefined>, key: string, fileValue: boolean | undefined): boolean {
+  const raw = env[key]?.trim();
+  if (raw) return /^(1|true|yes)$/i.test(raw);
+  return fileValue ?? false;
+}
+
+/**
+ * Picks the transport: explicit `JEVC_PROVIDER` wins; otherwise TypeSafe when
+ * its key is present, OpenRouter when only `OPENROUTER_API_KEY` is present,
+ * and `typesafe` otherwise. `JEVC_API_KEY` alone does not influence the
+ * choice (it could belong to either transport); set `JEVC_PROVIDER` to use it
+ * with OpenRouter.
+ */
+function resolveProvider(env: Record<string, string | undefined>): JevProvider {
+  const explicit = env.JEVC_PROVIDER?.trim().toLowerCase();
+  if (explicit === 'typesafe' || explicit === 'openrouter') return explicit;
+  if ((env.TYPESAFE_API_KEY ?? '').trim()) return 'typesafe';
+  if ((env.OPENROUTER_API_KEY ?? '').trim()) return 'openrouter';
+  return 'typesafe';
+}
+
+function keyFor(provider: JevProvider, env: Record<string, string | undefined>): string {
+  const own = provider === 'openrouter' ? env.OPENROUTER_API_KEY : env.TYPESAFE_API_KEY;
+  return env.JEVC_API_KEY?.trim() || own?.trim() || '';
+}
+
+/** File-based configuration layer; every field is optional. API keys never live here. */
+export interface JevFileConfig {
+  provider?: JevProvider;
+  model?: string;
+  baseUrl?: string;
+  disabled?: boolean;
+  routing?: {
+    cheap?: string;
+    strong?: string;
+    easyMax?: number;
+    hardMin?: number;
+    minConfidence?: number;
+  };
+  compaction?: {
+    keepThreshold?: number;
+    borderline?: number;
+    preserveRecentMessages?: number;
+    truncateHeadChars?: number;
+    minReduction?: number;
+    maxStateTokens?: number;
+    maxRequestTokens?: number;
+  };
+}
+
+/** Metadata for one configurable key; drives the `pi-jev config` CLI. */
+export interface ConfigKeyMeta {
+  path: string;
+  type: 'string' | 'number' | 'boolean';
+  env?: string;
+  default?: string | number | boolean;
+  description: string;
+}
+
+/**
+ * All user-facing keys. `apiKey` is deliberately absent (env-only), and the
+ * routing thresholds (easyMax/hardMin/minConfidence) stay internal defaults —
+ * still tunable through `JEVC_ROUTE_*` env vars, but not exposed here.
+ */
+export const CONFIG_KEYS: readonly ConfigKeyMeta[] = [
+  { path: 'provider', type: 'string', env: 'JEVC_PROVIDER', description: 'Jev transport: typesafe or openrouter' },
+  { path: 'model', type: 'string', env: 'JEVC_MODEL', description: 'Jev model slug (e.g. typesafe/jev-1.13 on OpenRouter)' },
+  { path: 'baseUrl', type: 'string', env: 'JEVC_BASE_URL', description: 'Jev endpoint URL' },
+  { path: 'disabled', type: 'boolean', env: 'JEVC_DISABLED', default: false, description: 'Bypass all pi-jev hooks' },
+  { path: 'routing.cheap', type: 'string', env: 'JEVC_ROUTE_CHEAP', description: '"provider/model-id" for easy requests (enables routing)' },
+  { path: 'routing.strong', type: 'string', env: 'JEVC_ROUTE_STRONG', description: '"provider/model-id" for hard requests (optional)' },
+  { path: 'compaction.keepThreshold', type: 'number', env: 'JEVC_KEEP_THRESHOLD', default: DEFAULTS.keepThreshold, description: 'Minimum keep probability for verbatim retention' },
+  { path: 'compaction.borderline', type: 'number', env: 'JEVC_BORDERLINE', default: DEFAULTS.borderline, description: 'Band where a confident low-staleness score still keeps a result' },
+  { path: 'compaction.preserveRecentMessages', type: 'number', env: 'JEVC_PRESERVE_RECENT', default: DEFAULTS.preserveRecentMessages, description: 'Newest messages within the summarized span that are never touched' },
+  { path: 'compaction.truncateHeadChars', type: 'number', env: 'JEVC_TRUNCATE_HEAD', default: DEFAULTS.truncateHeadChars, description: 'Characters of a dropped tool result retained before its note' },
+  { path: 'compaction.minReduction', type: 'number', env: 'JEVC_MIN_REDUCTION', default: DEFAULTS.minReduction, description: 'Minimum estimated span reduction, else default compaction' },
+  { path: 'compaction.maxStateTokens', type: 'number', env: 'JEVC_MAX_STATE_TOKENS', default: DEFAULTS.maxStateTokens, description: 'Estimated token ceiling for the Jev state' },
+  { path: 'compaction.maxRequestTokens', type: 'number', env: 'JEVC_MAX_REQUEST_TOKENS', default: DEFAULTS.maxRequestTokens, description: 'Estimated ceiling for state plus one batch of questions' },
+];
+
+/** Default config file locations, mirroring pi's own settings layout. */
+export function defaultConfigPaths(): { globalPath: string; projectPath: string } {
+  return {
+    globalPath: join(homedir(), '.pi', 'agent', 'jev.json'),
+    projectPath: join(process.cwd(), '.pi', 'jev.json'),
+  };
+}
+
+/** Reads and parses one config file. Throws on missing or malformed JSON. */
+export function readConfigFile(path: string): JevFileConfig {
+  const raw = readFileSync(path, 'utf8');
+  const parsed: unknown = JSON.parse(raw);
+  if (parsed === null || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`config at ${path} must be a JSON object`);
+  }
+  return parsed as JevFileConfig;
+}
+
+function readTolerant(path: string, scope: string, warn: (message: string) => void): JevFileConfig | undefined {
+  try {
+    return readConfigFile(path);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    warn(`pi-jev: ignoring ${scope} config at ${path} (${(error as Error).message})`);
+    return undefined;
+  }
+}
+
+export function mergeConfigFiles(global?: JevFileConfig, project?: JevFileConfig): JevFileConfig | undefined {
+  if (!global) return project;
+  if (!project) return global;
+  return {
+    ...global,
+    ...project,
+    routing: { ...global.routing, ...project.routing },
+    compaction: { ...global.compaction, ...project.compaction },
+  };
+}
+
+/** Resolves the full config: env > project file > global file > defaults. */
+export function configFromEnv(
+  env: Record<string, string | undefined> = process.env,
+  file?: JevFileConfig,
+): JevConfig {
+  const explicit = env.JEVC_PROVIDER?.trim().toLowerCase();
+  const provider: JevProvider = explicit === 'typesafe' || explicit === 'openrouter'
+    ? explicit
+    : file?.provider === 'typesafe' || file?.provider === 'openrouter'
+      ? file.provider
+      : resolveProvider(env);
+  return {
+    provider,
+    apiKey: keyFor(provider, env),
+    model: env.JEVC_MODEL?.trim() || file?.model?.trim()
+      || (provider === 'openrouter' ? OPENROUTER_JEV_MODEL : DEFAULT_MODEL),
+    baseUrl: env.JEVC_BASE_URL?.trim() || file?.baseUrl?.trim()
+      || (provider === 'openrouter' ? OPENROUTER_DECISIONS_URL : SYSTEM_ONE_URL),
+    keepThreshold: number(env, 'JEVC_KEEP_THRESHOLD', file?.compaction?.keepThreshold ?? DEFAULTS.keepThreshold),
+    borderline: number(env, 'JEVC_BORDERLINE', file?.compaction?.borderline ?? DEFAULTS.borderline),
+    preserveRecentMessages: Math.max(
+      0,
+      Math.floor(number(env, 'JEVC_PRESERVE_RECENT', file?.compaction?.preserveRecentMessages ?? DEFAULTS.preserveRecentMessages)),
+    ),
+    truncateHeadChars: Math.max(
+      0,
+      Math.floor(number(env, 'JEVC_TRUNCATE_HEAD', file?.compaction?.truncateHeadChars ?? DEFAULTS.truncateHeadChars)),
+    ),
+    minReduction: number(env, 'JEVC_MIN_REDUCTION', file?.compaction?.minReduction ?? DEFAULTS.minReduction),
+    maxStateTokens: Math.max(1, number(env, 'JEVC_MAX_STATE_TOKENS', file?.compaction?.maxStateTokens ?? DEFAULTS.maxStateTokens)),
+    maxRequestTokens: Math.max(1, number(env, 'JEVC_MAX_REQUEST_TOKENS', file?.compaction?.maxRequestTokens ?? DEFAULTS.maxRequestTokens)),
+    disabled: layeredFlag(env, 'JEVC_DISABLED', file?.disabled),
+    routing: {
+      cheap: env.JEVC_ROUTE_CHEAP?.trim() || file?.routing?.cheap?.trim() || undefined,
+      strong: env.JEVC_ROUTE_STRONG?.trim() || file?.routing?.strong?.trim() || undefined,
+      easyMax: number(env, 'JEVC_ROUTE_EASY_MAX', file?.routing?.easyMax ?? DEFAULTS.easyMax),
+      hardMin: number(env, 'JEVC_ROUTE_HARD_MIN', file?.routing?.hardMin ?? DEFAULTS.hardMin),
+      minConfidence: number(env, 'JEVC_ROUTE_MIN_CONFIDENCE', file?.routing?.minConfidence ?? DEFAULTS.minConfidence),
+    },
+  };
+}
+
+/** Loads config files and env into a full `JevConfig`. Malformed files warn and are skipped. */
+export function loadConfig(
+  opts: {
+    env?: Record<string, string | undefined>;
+    globalPath?: string;
+    projectPath?: string;
+    warn?: (message: string) => void;
+  } = {},
+): JevConfig {
+  const paths = { ...defaultConfigPaths(), ...opts };
+  const warn = opts.warn ?? ((message: string) => console.warn(message));
+  const file = mergeConfigFiles(
+    readTolerant(paths.globalPath, 'global', warn),
+    readTolerant(paths.projectPath, 'project', warn),
+  );
+  return configFromEnv(opts.env ?? process.env, file);
+}

package/src/vendor/fast-jev-compaction/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025
+
+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/src/vendor/fast-jev-compaction/client.ts

@@ -0,0 +1,43 @@
+import { buildJevRequest, parseJevResponse } from './request.js';
+import type { JevAsker, JevQuestions, JevResponse, JevState } from './types.js';
+
+export interface JevClientOptions {
+  /** Defaults to `process.env.TYPESAFE_API_KEY`. */
+  apiKey?: string;
+  /** Defaults to `jev-latest`. */
+  model?: string;
+  /** Defaults to the System One endpoint. */
+  baseUrl?: string;
+  /** Defaults to the global `fetch`. */
+  fetch?: typeof fetch;
+}
+
+/** Asks Jev over HTTP with the global `fetch` (or an injected one). */
+export class JevClient implements JevAsker {
+  private readonly apiKey: string;
+  private readonly model: string | undefined;
+  private readonly baseUrl: string | undefined;
+  private readonly fetcher: typeof fetch;
+
+  constructor(options: JevClientOptions = {}) {
+    this.apiKey = options.apiKey ?? process.env.TYPESAFE_API_KEY ?? '';
+    this.model = options.model;
+    this.baseUrl = options.baseUrl;
+    this.fetcher = options.fetch ?? fetch;
+  }
+
+  async ask(state: JevState, questions: JevQuestions): Promise<JevResponse> {
+    if (!this.apiKey) throw new Error('TYPESAFE_API_KEY is not configured');
+    const request = buildJevRequest(
+      { apiKey: this.apiKey, model: this.model, baseUrl: this.baseUrl },
+      state,
+      questions,
+    );
+    const response = await this.fetcher(request.url, {
+      method: request.method,
+      headers: request.headers,
+      body: request.body,
+    });
+    return parseJevResponse(response.status, response.ok, await response.text());
+  }
+}

package/src/vendor/fast-jev-compaction/compact.ts

@@ -0,0 +1,309 @@
+import { noulAnswer } from './request.js';
+import { collectToolCalls, estimateTokens, fitState } from './state.js';
+import type {
+  CallAnswer,
+  CallDecision,
+  CompactOptions,
+  CompactResult,
+  CompactionState,
+  JevAsker,
+  JevQuestions,
+  Message,
+  ResolvedCompactOptions,
+  ToolCall,
+  ToolUse,
+} from './types.js';
+
+export const DEFAULT_OPTIONS: ResolvedCompactOptions = {
+  goal: '',
+  keepThreshold: 0.5,
+  preserveRecentMessages: 6,
+  maxStateTokens: 25_000,
+  maxRequestTokens: 30_000,
+  truncateHeadChars: 300,
+};
+
+/** Tokens the request envelope (`model`, key names) adds around state and questions. */
+const REQUEST_OVERHEAD_TOKENS = 20;
+
+function finite(value: number | undefined, fallback: number): number {
+  return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+
+export function resolveOptions(options: CompactOptions = {}): ResolvedCompactOptions {
+  return {
+    goal: options.goal ?? DEFAULT_OPTIONS.goal,
+    keepThreshold: finite(options.keepThreshold, DEFAULT_OPTIONS.keepThreshold),
+    preserveRecentMessages: Math.max(
+      0,
+      Math.floor(
+        finite(options.preserveRecentMessages, DEFAULT_OPTIONS.preserveRecentMessages),
+      ),
+    ),
+    maxStateTokens: Math.max(1, finite(options.maxStateTokens, DEFAULT_OPTIONS.maxStateTokens)),
+    maxRequestTokens: Math.max(
+      1,
+      finite(options.maxRequestTokens, DEFAULT_OPTIONS.maxRequestTokens),
+    ),
+    truncateHeadChars: Math.max(
+      0,
+      Math.floor(finite(options.truncateHeadChars, DEFAULT_OPTIONS.truncateHeadChars)),
+    ),
+  };
+}
+
+/** The two `noul` questions asked about one call: keep the call, keep its result. */
+export function questionsFor(call: ToolCall): JevQuestions {
+  return {
+    [`call_${call.id}`]: {
+      type: 'noul',
+      instructions: `Tool call ${call.id} (${call.tool}) should stay in the history: knowing this call was made, with its input, still matters for what the assistant does next`,
+    },
+    [`result_${call.id}`]: {
+      type: 'noul',
+      instructions: `The full output of tool call ${call.id} (${call.tool}, ${call.resultChars} chars) should stay in the history verbatim: the assistant still needs its contents and re-running the tool would not do`,
+    },
+  };
+}
+
+/**
+ * Splits the candidate calls into batches whose questions, together with the
+ * (always complete) state, fit one request.
+ */
+export function batchCalls(
+  calls: readonly ToolCall[],
+  stateTokens: number,
+  options: Pick<ResolvedCompactOptions, 'maxRequestTokens'>,
+): ToolCall[][] {
+  const budget = options.maxRequestTokens - stateTokens - REQUEST_OVERHEAD_TOKENS;
+  const batches: ToolCall[][] = [];
+  let current: ToolCall[] = [];
+  let currentTokens = 0;
+  for (const call of calls) {
+    const tokens = estimateTokens(JSON.stringify(questionsFor(call)));
+    if (current.length > 0 && currentTokens + tokens > budget) {
+      batches.push(current);
+      current = [];
+      currentTokens = 0;
+    }
+    if (current.length === 0 && tokens > budget) {
+      throw new Error(
+        `state leaves no room for questions (~${stateTokens} of ${options.maxRequestTokens} tokens)`,
+      );
+    }
+    current.push(call);
+    currentTokens += tokens;
+  }
+  if (current.length > 0) batches.push(current);
+  return batches;
+}
+
+export function decideCall(
+  call: Pick<ToolCall, 'id' | 'tool' | 'pinned'>,
+  answer: CallAnswer,
+  options: Pick<ResolvedCompactOptions, 'keepThreshold'>,
+): CallDecision {
+  const base = { id: call.id, tool: call.tool, ...answer };
+  if (call.pinned) return { ...base, action: 'keep', reason: 'pinned' };
+  if (answer.keepResult >= options.keepThreshold) {
+    return { ...base, action: 'keep', reason: 'kept' };
+  }
+  if (answer.keepCall >= options.keepThreshold) {
+    return { ...base, action: 'drop_result', reason: 'result_dropped' };
+  }
+  return { ...base, action: 'drop_call', reason: 'call_dropped' };
+}
+
+async function askBatch(
+  asker: JevAsker,
+  state: CompactionState,
+  batch: readonly ToolCall[],
+): Promise<Map<string, CallAnswer>> {
+  const questions: JevQuestions = Object.assign({}, ...batch.map(questionsFor));
+  const { answers } = await asker.ask(state, questions);
+  return new Map(
+    batch.map((call) => [
+      call.id,
+      {
+        keepCall: noulAnswer(answers, `call_${call.id}`),
+        keepResult: noulAnswer(answers, `result_${call.id}`),
+      },
+    ]),
+  );
+}
+
+function truncatedResultText(text: string, isError: boolean, headChars: number): string {
+  if (text.length <= headChars + 120) return text;
+  const head = headChars > 0 ? `${text.slice(0, headChars)}\n` : '';
+  return `${head}[fast-jev-compaction truncated ${text.length - headChars} chars of this tool result${
+    isError ? ' (error)' : ''
+  }; re-run the tool if needed]`;
+}
+
+/**
+ * Rebuilds the conversation from the decisions. A dropped call disappears
+ * together with its result; a dropped result keeps a bounded head and note.
+ * Messages that lose all their content are removed; untouched messages are
+ * returned as the same objects they came in as.
+ */
+export function applyDecisions(
+  messages: readonly Message[],
+  decisions: readonly CallDecision[],
+  calls: readonly ToolCall[],
+  headChars: number,
+): Message[] {
+  const byId = new Map(calls.map((call) => [call.id, call]));
+  const actions = new Map<string, CallDecision['action']>();
+  for (const decision of decisions) {
+    const call = byId.get(decision.id);
+    if (call && decision.action !== 'keep') actions.set(call.tool_use_id, decision.action);
+  }
+  const kept: Message[] = [];
+  for (const message of messages) {
+    const touched =
+      message.toolUses.some((tool) => actions.has(tool.tool_use_id)) ||
+      (message.toolResults ?? []).some((result) => actions.has(result.tool_use_id));
+    if (!touched) {
+      kept.push(message);
+      continue;
+    }
+    const toolUses = message.toolUses
+      .filter((tool) => actions.get(tool.tool_use_id) !== 'drop_call')
+      .map((tool) => {
+        if (actions.get(tool.tool_use_id) !== 'drop_result') return tool;
+        const text = truncatedResultText(
+          tool.text ?? '',
+          tool.isError ?? false,
+          headChars,
+        );
+        if ((tool.text ?? '') === text) return tool;
+        const copy: ToolUse = {
+          tool_use_id: tool.tool_use_id,
+          tool: tool.tool,
+          input: tool.input,
+          text,
+        };
+        if (tool.isError) copy.isError = true;
+        return copy;
+      });
+    const toolResults = (message.toolResults ?? [])
+      .filter((result) => actions.get(result.tool_use_id) !== 'drop_call')
+      .map((result) => {
+        if (actions.get(result.tool_use_id) !== 'drop_result') return result;
+        const text = truncatedResultText(result.text, result.isError ?? false, headChars);
+        return text === result.text
+          ? result
+          : {
+              tool_use_id: result.tool_use_id,
+              text,
+              isError: result.isError,
+            };
+      });
+    if (
+      !message.toolUses.some(
+        (tool) => actions.get(tool.tool_use_id) === 'drop_call',
+      ) &&
+      !(message.toolResults ?? []).some(
+        (result) => actions.get(result.tool_use_id) === 'drop_call',
+      ) &&
+      toolUses.every((tool, index) => tool === message.toolUses[index]) &&
+      toolResults.every(
+        (result, index) => result === message.toolResults?.[index],
+      )
+    ) {
+      kept.push(message);
+      continue;
+    }
+    if (message.text.trim().length === 0 && toolUses.length === 0 && toolResults.length === 0) {
+      continue;
+    }
+    const rebuilt: Message = { role: message.role, text: message.text, toolUses };
+    if (toolResults.length > 0) rebuilt.toolResults = toolResults;
+    kept.push(rebuilt);
+  }
+  return kept;
+}
+
+/** Characters of text, tool input and tool output a message holds. */
+export function messageChars(message: Message): number {
+  let total = message.text.length;
+  for (const tool of message.toolUses) {
+    try {
+      total += JSON.stringify(tool.input).length;
+    } catch {
+      total += 20;
+    }
+  }
+  for (const result of message.toolResults ?? []) total += result.text.length;
+  return total;
+}
+
+export function reductionRatio(result: Pick<CompactResult, 'stats'>): number {
+  const { charsBefore, charsAfter } = result.stats;
+  return charsBefore === 0 ? 0 : (charsBefore - charsAfter) / charsBefore;
+}
+
+function count(decisions: readonly CallDecision[], reason: CallDecision['reason']): number {
+  return decisions.filter((decision) => decision.reason === reason).length;
+}
+
+/**
+ * Compacts a transcript by asking Jev, for every tool call outside the pinned
+ * first and newest messages, whether the call and whether its result must
+ * stay. The whole history (results omitted, fitted into `maxStateTokens`) is
+ * sent as state with every batch of questions. Throws when Jev fails or the
+ * history cannot be fitted; the caller decides whether to fall back.
+ */
+export async function compact(
+  messages: readonly Message[],
+  asker: JevAsker,
+  options: CompactOptions = {},
+): Promise<CompactResult> {
+  const started = Date.now();
+  const resolved = resolveOptions(options);
+  const calls = collectToolCalls(messages, resolved.preserveRecentMessages);
+  const candidates = calls.filter((call) => !call.pinned);
+  const charsBefore = messages.reduce((sum, message) => sum + messageChars(message), 0);
+
+  let fitted: { tokens: number; stage: string } = { tokens: 0, stage: '' };
+  let batches: ToolCall[][] = [];
+  const answers = new Map<string, CallAnswer>();
+  if (candidates.length > 0) {
+    const state = fitState(messages, calls, resolved);
+    fitted = state;
+    batches = batchCalls(candidates, state.tokens, resolved);
+    const answered = await Promise.all(
+      batches.map((batch) => askBatch(asker, state.state, batch)),
+    );
+    for (const map of answered) for (const [id, answer] of map) answers.set(id, answer);
+  }
+
+  const decisions = calls.map((call) =>
+    decideCall(call, answers.get(call.id) ?? { keepCall: 1, keepResult: 1 }, resolved),
+  );
+  const kept = applyDecisions(
+    messages,
+    decisions,
+    calls,
+    resolved.truncateHeadChars,
+  );
+  return {
+    messages: kept,
+    decisions,
+    stats: {
+      messagesBefore: messages.length,
+      messagesAfter: kept.length,
+      charsBefore,
+      charsAfter: kept.reduce((sum, message) => sum + messageChars(message), 0),
+      calls: calls.length,
+      kept: count(decisions, 'kept'),
+      resultsDropped: count(decisions, 'result_dropped'),
+      callsDropped: count(decisions, 'call_dropped'),
+      pinned: count(decisions, 'pinned'),
+      stateTokens: fitted.tokens,
+      stateStage: fitted.stage,
+      requests: batches.length,
+      ms: Date.now() - started,
+    },
+  };
+}

package/src/vendor/fast-jev-compaction/index.ts

@@ -0,0 +1,7 @@
+// Vendored subset of https://github.com/tamaratran/fast-jev-compaction (MIT).
+// See LICENSE in this directory. Kept verbatim; upgrade by re-copying from upstream.
+export * from './types.js';
+export * from './request.js';
+export * from './client.js';
+export * from './state.js';
+export * from './compact.js';