jev-lens 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Didrik Rognstad
+
+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,52 @@
+# jev-lens (core)
+
+The host-independent part of [jev-lens](https://github.com/dizk/jev-lens): given one large tool result and what the
+agent is doing, build candidate views from the output's own lines, let [jev](https://docs.typesafe.ai) pick one,
+expand the blocks or sections the agent will need, and return the view to send. Used by the pi extension
+`pi-jev-lens` and by the Claude Code plugin. Nothing here depends on either host.
+
+```sh
+npm install jev-lens
+```
+
+```ts
+import { createPresend, Lens, loadConfig, sliceRecall } from "jev-lens";
+
+const cfg = loadConfig();                       // JEV_LENS_* environment, TYPESAFE_API_KEY or a key file
+const { presend, mock } = createPresend(cfg);   // jev, or a deterministic mock when there is no key
+const lens = new Lens({ cfg, presend, footer: { recall: (id) => `Call recall with id "${id}".` } });
+
+const out = await lens.compress({
+	toolCallId: "call_1",
+	toolName: "read",                             // canonical names: read, bash, grep, find, ls, edit, write
+	args: { path: "src/auth.ts" },                // canonical args: { path }, { command }, { pattern, path }
+	text: fullOutput,
+	context: { firstUser: task, latestUser: lastPrompt, agentText: textBeforeTheCall },
+});
+if (out.compressed) send(out.text); else send(fullOutput);   // out.text = view + footer
+
+// later, when the agent calls recall:
+sliceRecall({ text: fullOutput, toolName: "read", args }, { lines: "120-180" }).text;
+```
+
+`Lens.compress` returns what was decided and why (`kind`, `view`, `answer`, `expanded`, `candidates`, `reason`,
+`ms`) so a host can log it. It throws when jev fails; the host then sends the full output.
+
+What else is exported:
+
+| export | purpose |
+|---|---|
+| `buildCandidates`, `buildCandidatesAsync`, `detectKind`, the `*View` functions | the views, synchronously or with tree-sitter outlines and blocks for code |
+| `languageForPath`, `treeSitterBlocks`, `treeSitterOutline` | tree-sitter over the grammars in `@vscode/tree-sitter-wasm` (plus Kotlin) |
+| `displayedFiles` | which files a shell command like `cat a.py; sed -n 1,40p b.py` displays, so the output gets code views |
+| `buildPresendState`, `presendQuestions`, `expandQuestions`, `decideView`, `expandRelevantBlocks`, `DEFAULT_PROMPTS` | the jev questions, the state they see, and the thresholds |
+| `JevPresend`, `MockPresend`, `createPresend`, `promptsWithVariant` | the classifiers |
+| `loadConfig`, `loadConfigWithVariant`, `keyFilePath`, `storeKey`, `resolveApiKey` | configuration from `JEV_LENS_*` variables and a host-chosen key file |
+| `sliceRecall`, `recallMissText`, `RECALL_DESCRIPTION`, `RECALL_PARAM_DESCRIPTIONS` | the recall tool, identical in every host |
+| `JevClassifier`, `MockClassifier`, `buildItemState` | the post-send "is this still needed" questions the pi extension uses for optional pruning |
+| `Health`, `estimateTokensOfText`, `contentText`, `truncate`, `describeToolCall` | helpers |
+
+The environment variables are documented in the [pi extension's README](https://github.com/dizk/jev-lens/tree/main/packages/pi#configuration-environment);
+the core reads the same ones. Research log and benchmark numbers: [STATUS.md](https://github.com/dizk/jev-lens/blob/main/STATUS.md).
+
+MIT.

package/dist/classifier.d.ts

@@ -0,0 +1,78 @@
+import type { Config } from "./config.ts";
+import type { Probabilities } from "./types.ts";
+/** Everything jev sees about one tool result. Built identically by the extension and the replay harness. */
+export interface ItemState {
+    task: {
+        first_user_request: string;
+        latest_user_message: string;
+    };
+    item: {
+        tool: string;
+        args: string;
+        is_error: boolean;
+        total_chars: number;
+        output_head: string;
+        output_tail: string;
+    };
+    after: {
+        assistant_text: string;
+        next_tool_calls: {
+            name: string;
+            args: string;
+        }[];
+    };
+}
+export interface TextState {
+    task: {
+        first_user_request: string;
+    };
+    message: string;
+    role: "user" | "agent";
+}
+export interface Classifier {
+    classifyToolResult(state: ItemState, signal?: AbortSignal): Promise<Probabilities>;
+}
+export declare function buildItemState(cfg: Pick<Config, "stateHeadChars" | "stateTailChars">, input: {
+    firstUser: string;
+    latestUser: string;
+    toolName: string;
+    args: unknown;
+    isError: boolean;
+    output: string;
+    afterText: string;
+    afterCalls: {
+        name: string;
+        arguments: unknown;
+    }[];
+}): ItemState;
+export declare const TOOL_RESULT_QUESTIONS: {
+    needed: {
+        type: "noul";
+        instructions: string;
+        criteria: {
+            true: string;
+            false: string;
+        };
+    };
+    outcome_only: {
+        type: "noul";
+        instructions: string;
+        criteria: {
+            true: string;
+            false: string;
+        };
+    };
+};
+export declare class JevClassifier implements Classifier {
+    private client;
+    private model;
+    constructor(cfg: Pick<Config, "apiKey" | "model">);
+    classifyToolResult(state: ItemState, signal?: AbortSignal): Promise<Probabilities>;
+}
+/** Deterministic stand-in for tests and dry runs. Never touches the network. */
+export declare class MockClassifier implements Classifier {
+    private rule;
+    constructor(rule?: (state: ItemState) => Probabilities);
+    classifyToolResult(state: ItemState): Promise<Probabilities>;
+}
+export declare function defaultMockRule(state: ItemState): Probabilities;

package/dist/classifier.js

@@ -0,0 +1,67 @@
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import { head, tail, truncate } from "./text.js";
+export function buildItemState(cfg, input) {
+    return {
+        task: {
+            first_user_request: truncate(input.firstUser, 600),
+            latest_user_message: truncate(input.latestUser, 400),
+        },
+        item: {
+            tool: input.toolName,
+            args: truncate(JSON.stringify(input.args ?? {}), 300),
+            is_error: input.isError,
+            total_chars: input.output.length,
+            output_head: head(input.output, cfg.stateHeadChars),
+            output_tail: input.output.length > cfg.stateHeadChars ? tail(input.output, cfg.stateTailChars) : "",
+        },
+        after: {
+            assistant_text: truncate(input.afterText, 800),
+            next_tool_calls: input.afterCalls.slice(0, 8).map((c) => ({ name: c.name, args: truncate(JSON.stringify(c.arguments ?? {}), 150) })),
+        },
+    };
+}
+export const TOOL_RESULT_QUESTIONS = {
+    needed: {
+        type: "noul",
+        instructions: "`item` is the output of a tool the coding agent ran while working on `task`. `after` shows what the agent said and which tools it called right after seeing this output. Will the agent still need the full text of `item.output_head` and `item.output_tail` verbatim in its upcoming steps?",
+        criteria: {
+            true: "The agent is still working on what this output shows: it will edit, quote, compare against, or reason over specific lines of it; or it has not acted on it yet; or the output holds details (line numbers, exact error text, exact code) it will need again.",
+            false: "The agent already acted on it (edited the file, fixed the error, answered from it), moved on to a different area, the output was a dead end or irrelevant, or it is cheap to regenerate by running the same tool again.",
+        },
+    },
+    outcome_only: {
+        type: "noul",
+        instructions: "Is the useful information in `item` limited to its outcome, such as success or failure, the final status lines, an error message, or a count, so that the middle of the output could be dropped without losing anything the agent needs?",
+        criteria: {
+            true: "Command output, logs, install or build noise, test runs where only the pass/fail summary or the failing case matters.",
+            false: "Source code, file contents, search results, directory listings, or any output where specific lines in the middle carry the information.",
+        },
+    },
+};
+export class JevClassifier {
+    client;
+    model;
+    constructor(cfg) {
+        this.client = new TypeSafeClient({ apiKey: cfg.apiKey });
+        this.model = cfg.model;
+    }
+    async classifyToolResult(state, signal) {
+        const r = await this.client.systemOne({ state: state, questions: TOOL_RESULT_QUESTIONS, model: this.model }, { signal, timeout: 15000 });
+        return { needed: r.answers.needed.noul, outcomeOnly: r.answers.outcome_only.noul };
+    }
+}
+/** Deterministic stand-in for tests and dry runs. Never touches the network. */
+export class MockClassifier {
+    rule;
+    constructor(rule = defaultMockRule) {
+        this.rule = rule;
+    }
+    async classifyToolResult(state) {
+        return this.rule(state);
+    }
+}
+export function defaultMockRule(state) {
+    const big = state.item.total_chars > 2000;
+    const cmd = state.item.tool === "bash";
+    return { needed: big ? 0.1 : 0.9, outcomeOnly: cmd ? 0.9 : 0.1 };
+}

package/dist/config.d.ts

@@ -0,0 +1,96 @@
+export type SealMode = "off" | "rolling" | "batch" | "budget";
+export interface Config {
+    /** Disable all pruning (classification still runs and logs). */
+    enabled: boolean;
+    /**
+     * rolling: apply decisions at the next LLM call (smallest prompt, one cache rewrite per call while pruning).
+     * batch: apply only when the cache is cold or on compaction (best cache, prompt shrinks late).
+     * budget: like batch, but also apply when pending prunable tokens exceed a share of the prompt (one rewrite buys many calls).
+     */
+    mode: SealMode;
+    /** budget mode: apply pending decisions when they remove at least this fraction of the tail they would rewrite... */
+    budgetFraction: number;
+    /** ...and at least this many tokens. */
+    budgetMinTokens: number;
+    /** P(needed) below this → forget (stub). */
+    forgetBelow: number;
+    /** P(needed) below this and P(outcomeOnly) above trimAbove → trim to head+tail. */
+    trimBelow: number;
+    trimAbove: number;
+    /** Tool results smaller than this (estimated tokens) are never touched. */
+    minTokens: number;
+    /** Maximum wait for in-flight classifications at context, agent end and shutdown. */
+    classifyWaitMs: number;
+    /** Provider prompt-cache TTL; idle longer than this means the cache is cold. */
+    cacheTtlMs: number;
+    /** Lines kept at head/tail when trimming. */
+    trimHeadLines: number;
+    trimTailLines: number;
+    /** Max chars of tool output sent to jev (head + tail). */
+    stateHeadChars: number;
+    stateTailChars: number;
+    /** Pre-send compression of large tool results (jev picks a view before the output is ever sent). */
+    presend: boolean;
+    /** Only results at least this large (estimated tokens) are considered for pre-send compression. */
+    presendMinTokens: number;
+    /** Send full when P(needs full) is above this. */
+    presendNeedsFullAbove: number;
+    /** Send full when the "full" option itself gets more than this probability mass. */
+    presendFullMassAbove: number;
+    /** Separate needs-full threshold for command output (test runs), where "exact full text" is rarely what the agent needs. */
+    presendCommandNeedsFullAbove: number;
+    /** Code policy: "gate" (default) = jev's needs-full/full-mass gates decide between full and a view; "outline" = code is always sent as outline plus the blocks the second step expands (17 % edit-miss on 500 real trajectories, see STATUS). */
+    presendCodePolicy: "gate" | "outline";
+    /** Stricter needs-full threshold for source code, where a wrong view costs an edit (jev's answers vary run to run by ±0.2). */
+    presendCodeNeedsFullAbove: number;
+    /** Send full when the choice confidence is below this (0 = off; a spread over acceptable views is not a reason to send everything). */
+    presendMinConfidence: number;
+    /** Second step for code: expand the bodies of blocks jev says the agent will need (P above this). */
+    presendExpandAbove: number;
+    /** Command policy: "sections" (default) = when jev picks full for command output but needs-full is under the command threshold, send section headers and let the second step expand the sections it needs; "gate" = jev's view choice stands. */
+    presendCommandPolicy: "gate" | "sections";
+    /** Second step for command output: expand a section when P(needed) is above this. */
+    presendSectionExpandAbove: number;
+    /** Command output: when no section reaches this probability the step is uninformative and full is sent (0 = headers alone are allowed). */
+    presendSectionFloor: number;
+    model: string;
+    /** Optional variant file (JEV_LENS_VARIANT): { config, prompts, views } overrides, as produced by eval/bench/autoresearch.ts. */
+    variantFile: string | undefined;
+    /** Force the mock classifier even when a key is present (tests, dry runs). */
+    forceMock: boolean;
+    logFile: boolean;
+    apiKey: string | undefined;
+}
+/** Where the pi extension stores the TypeSafe API key. Other hosts pass their own default. */
+export declare const PI_KEY_FILE: string;
+/** Where the stored TypeSafe API key lives: JEV_LENS_KEY_FILE, else the host's default (pi's when none is given). */
+export declare function keyFilePath(defaultPath?: string): string;
+/** The stored key, if any. */
+export declare function readStoredKey(defaultPath?: string): string | undefined;
+/** Store the key in the host's key file, readable only by the user. */
+export declare function storeKey(key: string, defaultPath?: string): string;
+/** Key resolution: environment (or the package's .env, loaded into it), then the stored key. */
+export declare function resolveApiKey(defaultPath?: string): string | undefined;
+/**
+ * Load KEY=VALUE lines from this package's own .env, and from the monorepo root when running from a
+ * source checkout. Never from the target project: an installed copy under node_modules reads only its own directory.
+ */
+export declare function loadDotEnv(): void;
+export interface ConfigOptions {
+    /** The host's default key file (JEV_LENS_KEY_FILE still wins). */
+    keyFile?: string;
+}
+export declare function loadConfig(opts?: ConfigOptions): Config;
+export interface VariantOverrides {
+    name?: string;
+    config?: Partial<Config>;
+    prompts?: Record<string, unknown>;
+    views?: Record<string, number>;
+}
+/** Read a variant file (either a bare variant or an autoresearch best.json with { variant }). */
+export declare function loadVariant(path: string | undefined): VariantOverrides;
+/** Config with a variant's config overrides applied. */
+export declare function loadConfigWithVariant(opts?: ConfigOptions): {
+    cfg: Config;
+    variant: VariantOverrides;
+};

package/dist/config.js

@@ -0,0 +1,119 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+const HERE = dirname(fileURLToPath(import.meta.url));
+/** Where the pi extension stores the TypeSafe API key. Other hosts pass their own default. */
+export const PI_KEY_FILE = join(homedir(), ".pi", "agent", "jev-lens.json");
+/** Where the stored TypeSafe API key lives: JEV_LENS_KEY_FILE, else the host's default (pi's when none is given). */
+export function keyFilePath(defaultPath = PI_KEY_FILE) {
+    return process.env.JEV_LENS_KEY_FILE || defaultPath;
+}
+/** The stored key, if any. */
+export function readStoredKey(defaultPath) {
+    try {
+        const p = keyFilePath(defaultPath);
+        if (!existsSync(p))
+            return undefined;
+        const key = JSON.parse(readFileSync(p, "utf8")).apiKey;
+        return typeof key === "string" && key.trim() ? key.trim() : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Store the key in the host's key file, readable only by the user. */
+export function storeKey(key, defaultPath) {
+    const p = keyFilePath(defaultPath);
+    mkdirSync(dirname(p), { recursive: true });
+    writeFileSync(p, `${JSON.stringify({ apiKey: key.trim() }, null, 2)}\n`, { mode: 0o600 });
+    return p;
+}
+/** Key resolution: environment (or the package's .env, loaded into it), then the stored key. */
+export function resolveApiKey(defaultPath) {
+    return process.env.TYPESAFE_API_KEY || readStoredKey(defaultPath);
+}
+/**
+ * Load KEY=VALUE lines from this package's own .env, and from the monorepo root when running from a
+ * source checkout. Never from the target project: an installed copy under node_modules reads only its own directory.
+ */
+export function loadDotEnv() {
+    const pkgRoot = join(HERE, "..");
+    const dirs = [pkgRoot];
+    if (!HERE.includes("node_modules"))
+        dirs.push(join(pkgRoot, "..", ".."));
+    for (const dir of dirs) {
+        const p = join(dir, ".env");
+        if (!existsSync(p))
+            continue;
+        for (const line of readFileSync(p, "utf8").split("\n")) {
+            const m = line.match(/^\s*([A-Z0-9_]+)\s*=\s*(.*?)\s*$/);
+            if (!m || !m[2] || process.env[m[1]])
+                continue;
+            process.env[m[1]] = m[2].replace(/^["']|["']$/g, "");
+        }
+    }
+}
+function num(name, fallback) {
+    const v = process.env[name];
+    if (v === undefined || v === "")
+        return fallback;
+    const n = Number(v);
+    return Number.isFinite(n) ? n : fallback;
+}
+export function loadConfig(opts = {}) {
+    loadDotEnv();
+    const envMode = process.env.JEV_LENS_MODE;
+    const mode = envMode === "batch" || envMode === "budget" || envMode === "rolling" ? envMode : "off";
+    return {
+        enabled: process.env.JEV_LENS_DISABLED !== "1",
+        mode,
+        budgetFraction: num("JEV_LENS_BUDGET_FRACTION", 0.5),
+        budgetMinTokens: num("JEV_LENS_BUDGET_MIN_TOKENS", 1000),
+        forgetBelow: num("JEV_LENS_FORGET_BELOW", 0.25),
+        trimBelow: num("JEV_LENS_TRIM_BELOW", 0.5),
+        trimAbove: num("JEV_LENS_TRIM_ABOVE", 0.6),
+        minTokens: num("JEV_LENS_MIN_TOKENS", 150),
+        classifyWaitMs: num("JEV_LENS_CLASSIFY_WAIT_MS", 2500),
+        cacheTtlMs: num("JEV_LENS_CACHE_TTL_MS", 5 * 60 * 1000),
+        trimHeadLines: num("JEV_LENS_TRIM_HEAD", 15),
+        trimTailLines: num("JEV_LENS_TRIM_TAIL", 15),
+        stateHeadChars: num("JEV_LENS_STATE_HEAD", 2500),
+        stateTailChars: num("JEV_LENS_STATE_TAIL", 800),
+        presend: process.env.JEV_LENS_PRESEND !== "0",
+        presendMinTokens: num("JEV_LENS_PRESEND_MIN_TOKENS", 1200),
+        presendNeedsFullAbove: num("JEV_LENS_PRESEND_NEEDS_FULL_ABOVE", 0.5),
+        presendFullMassAbove: num("JEV_LENS_PRESEND_FULL_MASS_ABOVE", 0.5),
+        presendCodeNeedsFullAbove: num("JEV_LENS_PRESEND_CODE_NEEDS_FULL_ABOVE", 0.5),
+        presendCommandNeedsFullAbove: num("JEV_LENS_PRESEND_COMMAND_NEEDS_FULL_ABOVE", 0.65),
+        presendCodePolicy: process.env.JEV_LENS_PRESEND_CODE_POLICY === "outline" ? "outline" : "gate",
+        presendMinConfidence: num("JEV_LENS_PRESEND_MIN_CONFIDENCE", 0),
+        presendExpandAbove: num("JEV_LENS_PRESEND_EXPAND_ABOVE", 0.5),
+        presendCommandPolicy: process.env.JEV_LENS_PRESEND_COMMAND_POLICY === "gate" ? "gate" : "sections",
+        presendSectionExpandAbove: num("JEV_LENS_PRESEND_SECTION_EXPAND_ABOVE", 0.5),
+        presendSectionFloor: num("JEV_LENS_PRESEND_SECTION_FLOOR", 0.3),
+        model: process.env.JEV_LENS_MODEL || "jev-latest",
+        variantFile: process.env.JEV_LENS_VARIANT || undefined,
+        forceMock: process.env.JEV_LENS_CLASSIFIER === "mock",
+        logFile: process.env.JEV_LENS_LOG !== "0",
+        apiKey: resolveApiKey(opts.keyFile),
+    };
+}
+/** Read a variant file (either a bare variant or an autoresearch best.json with { variant }). */
+export function loadVariant(path) {
+    if (!path)
+        return {};
+    try {
+        const raw = JSON.parse(readFileSync(path, "utf8"));
+        return raw.variant ?? raw;
+    }
+    catch {
+        return {};
+    }
+}
+/** Config with a variant's config overrides applied. */
+export function loadConfigWithVariant(opts = {}) {
+    const base = loadConfig(opts);
+    const variant = loadVariant(base.variantFile);
+    return { cfg: { ...base, ...(variant.config ?? {}) }, variant };
+}

package/dist/health.d.ts

@@ -0,0 +1,11 @@
+export type Stage = "presend" | "postsend";
+/** Session-local failure counters. Never expose provider error messages or credentials. */
+export declare class Health {
+    private stages;
+    failure(stage: Stage, error: unknown): void;
+    success(stage: Stage): void;
+    get failing(): boolean;
+    /** At most one warning per stage per session, including work completed without a UI context. */
+    warnings(): string[];
+    lines(): string[];
+}

package/dist/health.js

@@ -0,0 +1,52 @@
+/** Report only validated status codes and fixed advice, never raw provider data. */
+function failureReason(error) {
+    const e = error && typeof error === "object" ? error : {};
+    const status = typeof e.status === "number" && Number.isInteger(e.status) && e.status >= 100 && e.status <= 599 ? e.status : undefined;
+    if (status !== undefined) {
+        const advice = status === 402 ? "Payment required. Check your TypeSafe credits and billing at https://console.typesafe.ai."
+            : status === 401 ? "Authentication failed. Check your TypeSafe API key."
+                : status === 403 ? "Access denied. Check your TypeSafe API key and account permissions."
+                    : status === 429 ? "TypeSafe rejected the request because of a usage limit. Check your rate limits and quota at https://console.typesafe.ai."
+                        : status === 400 || status === 422 ? "TypeSafe rejected the request format. Check SDK compatibility and the model configuration."
+                            : status === 404 ? "TypeSafe could not find the requested resource. Check the model and API endpoint."
+                                : status === 408 || status === 504 ? "The API request timed out. Retry later."
+                                    : status >= 500 ? "TypeSafe reported a server error. Retry later and check service availability."
+                                        : "TypeSafe returned an unexpected HTTP response. Check service availability and account settings.";
+        return `HTTP ${status}: ${advice}`;
+    }
+    if (e.name === "APITimeoutError" || e.name === "TimeoutError")
+        return "Request timed out (no HTTP status). Check your connection and TypeSafe service availability.";
+    if (e.name === "APIConnectionError")
+        return "Connection failed (no HTTP status). Check your network, proxy, and TypeSafe service availability.";
+    if (e.name === "TypeSafeError")
+        return "TypeSafe SDK error (no HTTP status). Check SDK compatibility and configuration.";
+    if (e.name === "TypeError" || e.name === "RangeError" || e.name === "SyntaxError")
+        return `${e.name} during compression (no HTTP status). The cause is unknown. Report this as a jev-lens bug if it persists.`;
+    return "Unclassified error (no HTTP status). The cause is unknown. Report this as a jev-lens bug if it persists.";
+}
+/** Session-local failure counters. Never expose provider error messages or credentials. */
+export class Health {
+    stages = {
+        presend: { failures: 0, failing: false, reason: "", notified: false },
+        postsend: { failures: 0, failing: false, reason: "", notified: false },
+    };
+    failure(stage, error) {
+        const reason = failureReason(error);
+        Object.assign(this.stages[stage], { failures: this.stages[stage].failures + 1, failing: true, reason });
+    }
+    success(stage) { this.stages[stage].failing = false; }
+    get failing() { return Object.values(this.stages).some((s) => s.failing); }
+    /** At most one warning per stage per session, including work completed without a UI context. */
+    warnings() {
+        return Object.entries(this.stages).flatMap(([stage, state]) => {
+            if (!state.failures || state.notified)
+                return [];
+            state.notified = true;
+            const effect = stage === "presend" ? "Full output was kept." : "The affected result was not pruned.";
+            return [`jev-lens: ${stage === "presend" ? "Pre-send compression" : "Post-send classification"} failed. ${effect} ${state.reason} See /jev-lens stats. Further failures appear there without repeated warnings.`];
+        });
+    }
+    lines() {
+        return Object.entries(this.stages).map(([stage, state]) => `${stage} failures: ${state.failures}${state.failures ? state.failing ? ` (last attempt failed). ${state.reason}` : " (a later attempt succeeded)" : ""}`);
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+export * from "./config.ts";
+export * from "./types.ts";
+export * from "./text.ts";
+export * from "./health.ts";
+export * from "./views.ts";
+export * from "./presend.ts";
+export * from "./classifier.ts";
+export * from "./lens.ts";
+export * from "./recall.ts";
+export { languageForPath, treeSitterBlocks, treeSitterOutline } from "./treesitter.ts";

package/dist/index.js

@@ -0,0 +1,10 @@
+export * from "./config.js";
+export * from "./types.js";
+export * from "./text.js";
+export * from "./health.js";
+export * from "./views.js";
+export * from "./presend.js";
+export * from "./classifier.js";
+export * from "./lens.js";
+export * from "./recall.js";
+export { languageForPath, treeSitterBlocks, treeSitterOutline } from "./treesitter.js";

package/dist/lens.d.ts

@@ -0,0 +1,69 @@
+import type { Config, VariantOverrides } from "./config.ts";
+import { type PresendClassifier, type PromptVariant } from "./presend.ts";
+import { type ContentKind, type FooterOptions, type View, type ViewParams } from "./views.ts";
+export interface LensContext {
+    /** The first user request of the session (the task). */
+    firstUser: string;
+    /** The latest user message. */
+    latestUser: string;
+    /** What the agent wrote right before the tool call, if anything. */
+    agentText: string;
+}
+export interface LensInput {
+    /** Id the recall tool will be given (pi's toolCallId, Claude Code's tool_use_id). */
+    toolCallId: string;
+    /** Canonical tool name: read, bash, grep, find, ls, edit, write. Hosts map their own names to these. */
+    toolName: string;
+    /** Canonical arguments: { path } for reads, { command } for shells, { pattern, path } for searches. */
+    args: unknown;
+    /** The full text of the result. */
+    text: string;
+    isError?: boolean;
+    context: LensContext;
+}
+export interface LensAnswer {
+    choice: string;
+    probabilities: Record<string, number>;
+    confidence: number;
+    needsFull: number;
+}
+export interface LensOutcome {
+    /** True when `text` is a reduced view; false when the full output should be sent unchanged. */
+    compressed: boolean;
+    kind: ContentKind | undefined;
+    view: View | undefined;
+    /** The view plus the recall footer when compressed, otherwise the original text. */
+    text: string;
+    /** Estimated tokens of the full output and of what is sent. */
+    tokens: number;
+    sentTokens: number;
+    totalLines: number;
+    /** Why nothing was compressed: too small, no smaller candidate, or jev chose full. */
+    reason?: "small" | "no-candidates" | "full";
+    answer?: LensAnswer;
+    /** Indices of the blocks or sections the second step put back. */
+    expanded?: number[];
+    /** Candidate views as "kind:chars", for logs. */
+    candidates?: string[];
+    ms: number;
+}
+export interface LensOptions {
+    cfg: Config;
+    presend: PresendClassifier;
+    viewParams?: Partial<ViewParams>;
+    /** How the footer names the recall tool; defaults to pi's phrasing. */
+    footer?: FooterOptions;
+}
+export declare class Lens {
+    private readonly o;
+    constructor(o: LensOptions);
+    /** Decide what to send for one tool result. Throws when jev fails; the host then sends the full output. */
+    compress(input: LensInput, signal?: AbortSignal): Promise<LensOutcome>;
+}
+/** jev when a key is available (or the mock when forced or keyless), so every host makes the same choice. */
+export declare function createPresend(cfg: Config, prompts?: PromptVariant): {
+    presend: PresendClassifier;
+    mock: boolean;
+};
+/** The default prompts with a variant file's overrides applied (autoresearch output). */
+export declare function promptsWithVariant(variant: VariantOverrides): PromptVariant;

package/dist/lens.js

@@ -0,0 +1,58 @@
+/**
+ * The pre-send pipeline, host-independent: given one large tool result and what the agent is doing,
+ * build candidate views, let jev pick one, expand the blocks or sections it will need, and return the
+ * view to send. Hosts (pi, Claude Code) wrap this with their own storage, recall tool and UI.
+ */
+import { TypeSafeClient } from "@typesafe-ai/sdk";
+import { buildPresendState, decideView, DEFAULT_PROMPTS, expandRelevantBlocks, JevPresend, MockPresend } from "./presend.js";
+import { estimateTokensOfText } from "./text.js";
+import { buildCandidatesAsync, extractTerms, footer } from "./views.js";
+export class Lens {
+    o;
+    constructor(o) {
+        this.o = o;
+    }
+    /** Decide what to send for one tool result. Throws when jev fails; the host then sends the full output. */
+    async compress(input, signal) {
+        const { cfg, presend } = this.o;
+        const started = Date.now();
+        const text = input.text;
+        const tokens = estimateTokensOfText(text);
+        const totalLines = text.split("\n").length;
+        const base = { compressed: false, kind: undefined, view: undefined, text, tokens, sentTokens: tokens, totalLines };
+        if (tokens < cfg.presendMinTokens)
+            return { ...base, reason: "small", ms: Date.now() - started };
+        const terms = extractTerms(input.context.latestUser, input.context.agentText, JSON.stringify(input.args ?? {}));
+        const cands = await buildCandidatesAsync(input.toolName, input.args, text, terms, this.o.viewParams ?? {});
+        const candidates = cands.views.map((v) => `${v.kind}:${v.chars}`);
+        if (cands.views.length < 2)
+            return { ...base, kind: cands.kind, reason: "no-candidates", candidates, ms: Date.now() - started };
+        const state = buildPresendState(cfg, { firstUser: input.context.firstUser, latestUser: input.context.latestUser, agentText: input.context.agentText, toolName: input.toolName, args: input.args, isError: input.isError ?? false, cands, totalLines, totalChars: text.length });
+        const answer = await presend.choose(state, cands.views.map((v) => v.kind), signal);
+        let view = decideView(answer, cands, cfg);
+        let expanded;
+        if (view.kind !== "full") {
+            const above = cands.kind === "command" ? cfg.presendSectionExpandAbove : cfg.presendExpandAbove;
+            const ex = await expandRelevantBlocks(presend, state, text, cands, view, above, signal, cands.blocks, cfg.presendSectionFloor);
+            if (ex) {
+                view = ex.view;
+                expanded = ex.probs.map((p, i) => (p > above ? i : -1)).filter((i) => i >= 0);
+            }
+        }
+        const common = { kind: cands.kind, view, tokens, totalLines, answer, expanded, candidates, ms: Date.now() - started };
+        if (view.kind === "full")
+            return { ...common, compressed: false, text, sentTokens: tokens, reason: "full" };
+        const sent = view.text + footer(view, input.toolCallId, totalLines, this.o.footer);
+        return { ...common, compressed: true, text: sent, sentTokens: estimateTokensOfText(view.text) };
+    }
+}
+/** jev when a key is available (or the mock when forced or keyless), so every host makes the same choice. */
+export function createPresend(cfg, prompts = DEFAULT_PROMPTS) {
+    const mock = cfg.forceMock || !cfg.apiKey;
+    return { presend: mock ? new MockPresend() : new JevPresend(new TypeSafeClient({ apiKey: cfg.apiKey }), cfg.model, prompts), mock };
+}
+/** The default prompts with a variant file's overrides applied (autoresearch output). */
+export function promptsWithVariant(variant) {
+    const v = (variant.prompts ?? {});
+    return { ...DEFAULT_PROMPTS, ...v, viewDescriptions: { ...DEFAULT_PROMPTS.viewDescriptions, ...(v.viewDescriptions ?? {}) } };
+}