pi-jev-lens 0.1.0

package/src/presend.ts

@@ -0,0 +1,217 @@
+import type { TypeSafeClient } from "@typesafe-ai/sdk";
+import type { Config } from "./config.ts";
+import { truncate } from "./text.ts";
+import { relevantView, splitBlocks, splitSections, type Block, type Candidates, type View, type ViewKind } from "./views.ts";
+
+export interface PresendState {
+	task: { first_user_request: string; latest_user_message: string };
+	agent: { text_before_call: string; tool: string; args: string };
+	result: { kind: string; is_error: boolean; total_lines: number; total_chars: number };
+	views: Record<string, { lines: number; chars: number; preview: string }>;
+}
+
+export interface PresendDecision {
+	view: ViewKind;
+	needsFull: number;
+	probabilities: Record<string, number>;
+	confidence: number;
+}
+
+export interface PresendClassifier {
+	choose(state: PresendState, kinds: ViewKind[], signal?: AbortSignal): Promise<{ choice: ViewKind; probabilities: Record<string, number>; confidence: number; needsFull: number }>;
+	/** Second step: for each block, P(the agent will need its body). */
+	expand(state: ExpandState, signal?: AbortSignal): Promise<number[]>;
+}
+
+export interface ExpandState {
+	task: PresendState["task"];
+	agent: PresendState["agent"];
+	file: { kind: string; total_lines: number };
+	blocks: { index: number; signature: string; lines: string; preview: string }[];
+}
+
+export function buildExpandState(base: PresendState, blocks: Block[], text: string): ExpandState {
+	const lines = text.split("\n");
+	return {
+		task: base.task,
+		agent: base.agent,
+		file: { kind: base.result.kind, total_lines: base.result.total_lines },
+		blocks: blocks.map((b, index) => ({ index, signature: b.name, lines: `${b.from}-${b.to}`, preview: truncate(lines.slice(b.from - 1, Math.min(b.to, b.from + 2)).join("\n"), 240) })),
+	};
+}
+
+export function expandQuestions(n: number, prompts: PromptVariant = DEFAULT_PROMPTS, kind = "code") {
+	const q: Record<string, { type: "noul"; instructions: string; criteria: { true: string; false: string } }> = {};
+	const [instructions, t, f] = kind === "command" ? [prompts.sectionInstructions, prompts.sectionTrue, prompts.sectionFalse] : [prompts.expandInstructions, prompts.expandTrue, prompts.expandFalse];
+	for (let i = 0; i < n; i++) {
+		q[`b${i}`] = { type: "noul", instructions: instructions.replaceAll("{i}", String(i)), criteria: { true: t, false: f } };
+	}
+	return q;
+}
+
+const VIEW_DESCRIPTIONS: Record<ViewKind, string> = {
+	full: "The complete, unmodified output. Needed when the agent will edit or quote exact text, when details anywhere in the output matter, or when nothing else clearly suffices.",
+	outline: "Structure only: imports, exports, signatures, class and function headers, headings, doc comments, with line numbers. Enough to understand what a file offers and where things are, not enough to edit a body verbatim.",
+	focus: "Only the lines that mention the identifiers from the task and the tool call, with a few lines of context, line-numbered. Enough when the agent is looking for specific names.",
+	signals: "Command output reduced to errors, warnings, failing tests and the final summary lines with context, line-numbered. Enough for reacting to a failed or passed run.",
+	sample: "Header plus a sample of rows and the total count, for tabular or log-like data. Enough to learn the shape of the data, not its contents.",
+	head_tail: "The first and last lines only. Enough to see what the output is and how it ends.",
+	relevant: "Outline plus the full bodies of the blocks the agent will need.",
+	matches: "Search output (grep, rg) reduced to the first matches of every file with the count of further matches per file, plus any non-match lines. Enough to see which files and lines are involved; not enough to read every match.",
+	log: "Script or server output with repeated lines collapsed: the first two and the last occurrence of every repeated line pattern, plus errors and the final lines. Enough to follow what happened; not enough to see every iteration.",
+	tree: "A directory listing reduced to the first few entries of every directory, with the number of omitted entries per directory. Enough to learn the project layout, not enough to find one specific file in a large directory.",
+	testlog: "A test run reduced to the failing tests with their assertion and traceback, the short summary and the final counts. Passing tests and decoration are dropped. Enough for reacting to a test run; not enough to see the output of passing tests.",
+	sections: "The first line of every section of the output (grep match groups, JSON objects, paragraphs, command markers), line-numbered. The bodies of the sections the agent needs are added in a second step. Enough when only some parts of a long mixed output matter.",
+};
+
+export function buildPresendState(
+	cfg: Pick<Config, "stateHeadChars">,
+	input: { firstUser: string; latestUser: string; agentText: string; toolName: string; args: unknown; isError: boolean; cands: Candidates; totalLines: number; totalChars: number },
+): PresendState {
+	const views: PresendState["views"] = {};
+	for (const v of input.cands.views) {
+		views[v.kind] = { lines: v.lines, chars: v.chars, preview: truncate(v.text, v.kind === "full" ? Math.min(1500, cfg.stateHeadChars) : 900) };
+	}
+	return {
+		task: { first_user_request: truncate(input.firstUser, 600), latest_user_message: truncate(input.latestUser, 400) },
+		agent: { text_before_call: truncate(input.agentText, 600), tool: input.toolName, args: truncate(JSON.stringify(input.args ?? {}), 300) },
+		result: { kind: input.cands.kind, is_error: input.isError, total_lines: input.totalLines, total_chars: input.totalChars },
+		views,
+	};
+}
+
+/** Everything the autoresearch loop may vary: prompt texts and view descriptions. Defaults = current best. */
+export interface PromptVariant {
+	viewInstructions: string;
+	viewDescriptions: Partial<Record<ViewKind, string>>;
+	needsFullInstructions: string;
+	needsFullTrue: string;
+	needsFullFalse: string;
+	expandInstructions: string;
+	expandTrue: string;
+	expandFalse: string;
+	/** Second step for command output: per section, will the agent need its contents. */
+	sectionInstructions: string;
+	sectionTrue: string;
+	sectionFalse: string;
+}
+
+export const DEFAULT_PROMPTS: PromptVariant = {
+	viewInstructions:
+		"A coding agent working on `task` just called `agent.tool` with `agent.args` (its reasoning right before the call is `agent.text_before_call`). The output is large. `views` lists candidate presentations of the same output with a preview of each. Which view is the smallest one that still gives the agent everything it needs for its next step? Prefer smaller views only when the agent's purpose is clearly served by them; when in doubt, choose full.",
+	viewDescriptions: {},
+	needsFullInstructions:
+		"Will the agent's next step require the exact, complete text of this output, for example to make an edit whose old text must match, to copy code, or to check details that could be anywhere in it?",
+	needsFullTrue: "The agent asked for this to modify it, copy from it, or review it line by line; the task is about the contents of this specific output.",
+	needsFullFalse: "The agent is orienting itself, checking structure, looking for where something lives, confirming an outcome, or sampling data.",
+	expandInstructions: "The agent working on `task` just read this file (`agent.args`) for the reason in `agent.text_before_call`. Will it need the full body of block `blocks[{i}]` (not just its signature) for its next step?",
+	expandTrue: "The task or the agent's stated purpose concerns this block: it will edit it, call it in a specific way, explain its logic, or debug it.",
+	expandFalse: "The block is unrelated to the task, or knowing its signature and existence is enough.",
+	sectionInstructions: "The agent working on `task` just ran the command `agent.args` for the reason in `agent.text_before_call`. The output is split into sections listed in `blocks`. Will the agent need the contents of section `blocks[{i}]` (not just its first line) for its next step?",
+	sectionTrue: "The section holds the result, error, value or match the agent ran the command to see, or something it will quote, compare or act on.",
+	sectionFalse: "The section is boilerplate, an unrelated match, setup or progress output, or its first line already tells the agent what it needs.",
+};
+
+export function presendQuestions(kinds: ViewKind[], prompts: PromptVariant = DEFAULT_PROMPTS) {
+	const criteria: Record<string, string> = {};
+	for (const k of kinds) criteria[k] = prompts.viewDescriptions[k] ?? VIEW_DESCRIPTIONS[k];
+	return {
+		view: { type: "choice" as const, instructions: prompts.viewInstructions, criteria },
+		needs_full: { type: "noul" as const, instructions: prompts.needsFullInstructions, criteria: { true: prompts.needsFullTrue, false: prompts.needsFullFalse } },
+	};
+}
+
+export class JevPresend implements PresendClassifier {
+	constructor(private client: TypeSafeClient, private model: string, private prompts: PromptVariant = DEFAULT_PROMPTS) {}
+	async expand(state: ExpandState, signal?: AbortSignal): Promise<number[]> {
+		const r = await this.client.systemOne({ state: state as never, questions: expandQuestions(state.blocks.length, this.prompts, state.file.kind), model: this.model }, { signal, timeout: 15000 });
+		return state.blocks.map((_, i) => (r.answers[`b${i}`] as { noul: number }).noul);
+	}
+	async choose(state: PresendState, kinds: ViewKind[], signal?: AbortSignal) {
+		const r = await this.client.systemOne({ state: state as never, questions: presendQuestions(kinds, this.prompts), model: this.model }, { signal, timeout: 15000 });
+		return { choice: r.answers.view.choice as ViewKind, probabilities: r.answers.view.probabilities as Record<string, number>, confidence: r.answers.view.confidence, needsFull: r.answers.needs_full.noul };
+	}
+}
+
+export class MockPresend implements PresendClassifier {
+	async expand(state: ExpandState): Promise<number[]> {
+		// deterministic: blocks whose signature mentions a term from the task
+		const words = (state.task.first_user_request + " " + state.agent.args).toLowerCase();
+		return state.blocks.map((b) => (b.signature.toLowerCase().split(/[^a-z0-9_]+/).some((w) => w.length > 4 && words.includes(w)) ? 0.9 : 0.1));
+	}
+	constructor(private pick: (state: PresendState, kinds: ViewKind[]) => ViewKind = (s, kinds) => (s.result.kind === "data" && kinds.includes("sample") ? "sample" : kinds.includes("outline") ? "outline" : "full")) {}
+	async choose(state: PresendState, kinds: ViewKind[]) {
+		const choice = this.pick(state, kinds);
+		const probabilities: Record<string, number> = {};
+		for (const k of kinds) probabilities[k] = k === choice ? 0.9 : 0.1 / Math.max(1, kinds.length - 1);
+		return { choice, probabilities, confidence: 0.9, needsFull: choice === "full" ? 0.9 : 0.1 };
+	}
+}
+
+/**
+ * Turn jev's answers into a view, erring on the side of sending more:
+ * full when needsFull is likely, when full itself carries real mass, or when the chosen view is not confident.
+ */
+export function decideView(
+	answer: { choice: ViewKind; probabilities: Record<string, number>; confidence: number; needsFull: number },
+	cands: Candidates,
+	cfg: Pick<Config, "presendNeedsFullAbove" | "presendFullMassAbove" | "presendMinConfidence" | "presendCodeNeedsFullAbove" | "presendCommandNeedsFullAbove"> & Partial<Pick<Config, "presendCodePolicy" | "presendCommandPolicy">>,
+): View {
+	const full = cands.views[0];
+	if (cands.kind === "command" && cfg.presendCommandPolicy === "sections") {
+		// sections-first: when jev would send full but does not think exact full text is needed, send the
+		// section headers and let the second step put back the sections it needs (full if that reaches 90 %).
+		const sections = cands.views.find((v) => v.kind === "sections");
+		if (sections && answer.choice === "full" && answer.needsFull <= cfg.presendCommandNeedsFullAbove) return sections;
+	}
+	if (cands.kind === "code" && cfg.presendCodePolicy === "outline") {
+		// outline-first: structure now, bodies via the expansion step, everything else via recall.
+		// Only when the expansion step can run (2+ blocks): an outline nobody can expand was edited from at once.
+		const outline = cands.views.find((v) => v.kind === "outline");
+		const blocks = (cands as { blocks?: Block[] }).blocks;
+		if (outline && blocks && blocks.length >= 2) return outline;
+		if (outline && !(blocks && blocks.length >= 2)) return full;
+	}
+	const needsFullAbove = cands.kind === "code" ? Math.min(cfg.presendNeedsFullAbove, cfg.presendCodeNeedsFullAbove) : cands.kind === "command" ? cfg.presendCommandNeedsFullAbove : cfg.presendNeedsFullAbove;
+	if (answer.needsFull > needsFullAbove) return full;
+	// For code, "focus" alone is a locating aid; if it wins, upgrade to outline so structure comes along (the second step may expand bodies).
+	if (cands.kind === "code" && answer.choice === "focus") { const outline = cands.views.find((v) => v.kind === "outline"); if (outline) return outline; }
+	if ((answer.probabilities.full ?? 0) > cfg.presendFullMassAbove) return full;
+	if (answer.confidence < cfg.presendMinConfidence) return full;
+	return cands.views.find((v) => v.kind === answer.choice) ?? full;
+}
+
+/**
+ * Second node of the pre-send graph: when a code file was reduced to its outline (or command output to its
+ * section headers), ask jev which block bodies the agent will need and put those back. Returns undefined when not applicable.
+ */
+export async function expandRelevantBlocks(
+	presend: PresendClassifier,
+	base: PresendState,
+	text: string,
+	cands: Candidates,
+	chosen: View,
+	threshold: number,
+	signal?: AbortSignal,
+	precomputed?: Block[],
+	/** Command output only: send full when no section reaches this probability (0 = headers alone are allowed). */
+	floor = 0,
+): Promise<{ view: View; blocks: Block[]; probs: number[] } | undefined> {
+	const isCode = cands.kind === "code" && (chosen.kind === "outline" || chosen.kind === "focus");
+	const isCommand = cands.kind === "command" && chosen.kind === "sections";
+	if (!isCode && !isCommand) return undefined;
+	const blocks = precomputed && precomputed.length >= 2 ? precomputed : isCommand ? splitSections(text) : splitBlocks(text);
+	if (blocks.length < 2) return undefined;
+	const probs = await presend.expand(buildExpandState(base, blocks, text), signal);
+	const expand = new Set<number>();
+	probs.forEach((p, i) => { if (p > threshold) expand.add(i); });
+	// the import/constants header is small and often edited (new imports): always keep it whole when short
+	if (isCode && blocks[0]?.name.startsWith("(header") && blocks[0].to - blocks[0].from < 20) expand.add(0);
+	// Command output where every section scores low is "cannot tell", not "nothing needed" (docs read for
+	// orientation score flat and low): headers alone would drop what the agent came for, so send it all.
+	if (isCommand && Math.max(...probs) < floor) return { view: cands.views[0], blocks, probs };
+	const outline = cands.views.find((v) => v.kind === (isCommand ? "sections" : "outline"));
+	const view = relevantView(text, cands.kind, blocks, expand, outline?.included);
+	if (view.chars >= cands.views[0].chars * 0.9) return { view: cands.views[0], blocks, probs };
+	return { view, blocks, probs };
+}

package/src/shell-display.ts

@@ -0,0 +1,90 @@
+/** A deliberately small shell subset, not a general shell parser. Unknown syntax fails closed. */
+export function displayedFiles(command: string): string[] | undefined {
+	if (command.length > 16384 || /[<>`$\\()#\r]/.test(command)) return undefined;
+	const tokens: { value: string; operator?: boolean }[] = [];
+	for (let i = 0; i < command.length;) {
+		const c = command[i];
+		if (c === " " || c === "\t") { i++; continue; }
+		if (";|&\n".includes(c)) {
+			let value = c;
+			if (command[i + 1] === c && (c === "&" || c === "|")) { value += c; i++; }
+			if (value === "&" || value === "||") return undefined;
+			tokens.push({ value, operator: true }); i++; continue;
+		}
+		if (c === "'" || c === '"') {
+			const end = command.indexOf(c, i + 1);
+			if (end < 0 || (end + 1 < command.length && !/[\s;|&]/.test(command[end + 1]))) return undefined;
+			const value = command.slice(i + 1, end);
+			// Quoted wildcard/brace paths need literal matching, not shell expansion.
+			if (/[{}*?\[\]\n]/.test(value)) return undefined;
+			tokens.push({ value }); i = end + 1; continue;
+		}
+		let end = i;
+		while (end < command.length && !/[\s;|&]/.test(command[end])) end++;
+		const value = command.slice(i, end);
+		if (!value || /['"]/.test(value)) return undefined;
+		tokens.push({ value }); i = end;
+	}
+	const files: string[] = [];
+	let stage: string[] = [], filter = false;
+	const finish = () => {
+		const paths = displayStage(stage);
+		if (!paths || (filter ? paths.length !== 0 : paths.length === 0)) return false;
+		files.push(...paths);
+		stage = [];
+		return files.length <= 256;
+	};
+	for (const token of tokens) {
+		if (!token.operator) { stage.push(token.value); continue; }
+		if (!stage.length) {
+			if (token.value === "\n" && !filter) continue;
+			return undefined;
+		}
+		if (!finish()) return undefined;
+		filter = token.value === "|";
+	}
+	if (stage.length) { if (!finish()) return undefined; }
+	else if (filter || tokens.at(-1)?.value === "&&") return undefined;
+	return files.length ? files : undefined;
+}
+
+/** Only content-preserving cat, line-limited head/tail, and sed -n range-p are recognized. */
+function displayStage(words: string[]): string[] | undefined {
+	const [executable, ...args] = words;
+	if (!executable || !/^(?:(?:\/usr)?\/bin\/)?(?:cat|head|tail|sed)$/.test(executable)) return undefined;
+	const cmd = executable.split("/").pop();
+	let i = 0;
+	if (cmd === "sed") {
+		if (args[i++] !== "-n" || !/^\d+(?:,(?:\d+|\$))?p$/.test(args[i++] ?? "")) return undefined;
+	} else if (cmd === "head" || cmd === "tail") {
+		if (args[i] === "-n") { i++; if (!/^\d+$/.test(args[i++] ?? "")) return undefined; }
+		else if (/^-\d+$/.test(args[i] ?? "")) i++;
+	}
+	if (args[i] === "--") i++;
+	const paths: string[] = [];
+	for (const arg of args.slice(i)) {
+		if (!arg || arg.startsWith("-") || /[~!]/.test(arg)) return undefined;
+		const expanded = expandBraces(arg);
+		if (!expanded) return undefined;
+		paths.push(...expanded);
+	}
+	return paths;
+}
+
+function expandBraces(word: string): string[] | undefined {
+	let pending = [word];
+	for (;;) {
+		const next: string[] = [];
+		let expanded = false;
+		for (const item of pending) {
+			const m = /^(.*?)\{([^{}]+)\}(.*)$/.exec(item);
+			if (!m) { if (/[{}]/.test(item)) return undefined; next.push(item); continue; }
+			if (!m[2].includes(",")) return undefined;
+			for (const alt of m[2].split(",")) next.push(m[1] + alt + m[3]);
+			expanded = true;
+			if (next.length > 256) return undefined;
+		}
+		if (!expanded) return next;
+		pending = next;
+	}
+}

package/src/text.ts

@@ -0,0 +1,68 @@
+import type { AgentMessage } from "./pi-types.ts";
+
+export function contentText(content: unknown): string {
+	if (typeof content === "string") return content;
+	if (!Array.isArray(content)) return "";
+	const parts: string[] = [];
+	for (const block of content) {
+		if (!block || typeof block !== "object") continue;
+		const b = block as { type?: string; text?: string; thinking?: string; name?: string; arguments?: unknown };
+		if (b.type === "text" && typeof b.text === "string") parts.push(b.text);
+	}
+	return parts.join("\n");
+}
+
+export function toolCallsOf(message: AgentMessage): { name: string; arguments: unknown }[] {
+	if (message.role !== "assistant") return [];
+	const out: { name: string; arguments: unknown }[] = [];
+	for (const block of message.content) {
+		if (block.type === "toolCall") out.push({ name: block.name, arguments: block.arguments });
+	}
+	return out;
+}
+
+export function head(s: string, n: number): string {
+	return s.length <= n ? s : s.slice(0, n);
+}
+
+export function tail(s: string, n: number): string {
+	return s.length <= n ? "" : s.slice(-n);
+}
+
+export function truncate(s: string, n: number): string {
+	return s.length <= n ? s : `${s.slice(0, n)}…`;
+}
+
+/** Rough token estimate matching pi's heuristic (chars / 4). */
+export function estimateTokensOfText(s: string): number {
+	return Math.ceil(s.length / 4);
+}
+
+/** Short, stable description of a tool call for stubs and memory pointers. */
+export function describeToolCall(toolName: string, args: unknown, outputChars: number, lines: number): string {
+	const a = (args ?? {}) as Record<string, unknown>;
+	const pick = (k: string): string | undefined => (typeof a[k] === "string" ? (a[k] as string) : undefined);
+	let what = "";
+	switch (toolName) {
+		case "read":
+			what = pick("path") ?? "";
+			break;
+		case "bash":
+			what = truncate((pick("command") ?? "").replace(/\s+/g, " "), 80);
+			break;
+		case "grep":
+			what = `${pick("pattern") ?? ""} in ${pick("path") ?? "."}`;
+			break;
+		case "find":
+		case "ls":
+			what = pick("path") ?? pick("pattern") ?? "";
+			break;
+		case "edit":
+		case "write":
+			what = pick("path") ?? "";
+			break;
+		default:
+			what = truncate(JSON.stringify(a), 80);
+	}
+	return `${toolName} ${what}`.trim() + ` (${lines} lines, ${outputChars} chars)`;
+}

package/src/treesitter.ts

@@ -0,0 +1,220 @@
+/**
+ * Tree-sitter backed structure for code views: exact top-level blocks (functions, classes,
+ * methods, top-level assignments) with signature lines, for the languages that ship in
+ * tree-sitter-wasms. Falls back to undefined when the language is unknown or parsing fails,
+ * in which case views.ts uses its regex heuristics.
+ */
+import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, extname, join } from "node:path";
+import type { Block } from "./views.ts";
+
+const require = createRequire(import.meta.url);
+
+/** Grammars shipped by @vscode/tree-sitter-wasm (ABI-compatible with web-tree-sitter 0.27). */
+const LANG_BY_EXT: Record<string, string> = {
+	".js": "javascript", ".mjs": "javascript", ".cjs": "javascript", ".jsx": "javascript",
+	".ts": "typescript", ".mts": "typescript", ".cts": "typescript", ".tsx": "tsx",
+	".py": "python", ".pyx": "python", ".go": "go", ".rs": "rust", ".java": "java", ".rb": "ruby",
+	".c": "c", ".h": "c", ".cc": "cpp", ".cpp": "cpp", ".hpp": "cpp", ".cs": "c-sharp", ".php": "php",
+	".sh": "bash", ".bash": "bash", ".css": "css",
+	".kt": "kotlin", ".kts": "kotlin",
+};
+
+/** Extra grammar packages: language → wasm path resolver (the VS Code bundle has no Kotlin). */
+const EXTRA_WASM: Record<string, () => string | undefined> = {
+	kotlin: () => {
+		try {
+			const dir = dirname(require.resolve("@binclusive/tree-sitter-kotlin-wasm/package.json"));
+			const { readdirSync } = require("node:fs") as typeof import("node:fs");
+			const walk = (d: string): string | undefined => { for (const f of readdirSync(d, { withFileTypes: true })) { const p = join(d, f.name); if (f.isDirectory() && f.name !== "node_modules") { const r = walk(p); if (r) return r; } else if (f.name.endsWith(".wasm")) return p; } return undefined; };
+			return walk(dir);
+		} catch { return undefined; }
+	},
+};
+
+/** Node types that count as top-level blocks, per language family. */
+const BLOCK_TYPES = new Set([
+	"function_declaration", "function_definition", "generator_function_declaration", "class_declaration", "class_definition",
+	"method_definition", "method_declaration", "abstract_class_declaration", "interface_declaration", "type_alias_declaration",
+	"enum_declaration", "module", "internal_module", "lexical_declaration", "variable_declaration", "export_statement",
+	"decorated_definition", "function_item", "impl_item", "struct_item", "enum_item", "trait_item", "mod_item", "const_item", "static_item",
+	"type_item", "func_literal", "method_declaration", "type_declaration", "var_declaration", "const_declaration",
+	"class_specifier", "struct_specifier", "namespace_definition", "template_declaration", "preproc_function_def",
+	"function_signature", "singleton_method", "module", "class", "method", "object_declaration", "property_declaration",
+	"companion_object", "constructor_declaration", "record_declaration", "annotation_type_declaration", "macro_definition", "extern_crate_declaration",
+]);
+const HEADER_TYPES = new Set(["import_statement", "import_declaration", "import_from_statement", "package_clause", "package_declaration", "use_declaration", "preproc_include", "require_call", "using_directive", "comment", "expression_statement", "attribute_item", "mod_item"]);
+
+type TS = typeof import("web-tree-sitter");
+let ts: TS | undefined;
+let inited: Promise<void> | undefined;
+const languages = new Map<string, Promise<import("web-tree-sitter").Language | undefined>>();
+
+function wasmDir(): string | undefined {
+	try {
+		return join(dirname(require.resolve("@vscode/tree-sitter-wasm/package.json")), "wasm");
+	} catch {
+		return undefined;
+	}
+}
+
+async function init(): Promise<TS | undefined> {
+	if (ts) return ts;
+	if (!inited) {
+		inited = (async () => {
+			try {
+				const mod = (await import("web-tree-sitter")) as TS;
+				await mod.Parser.init();
+				ts = mod;
+			} catch {
+				ts = undefined;
+			}
+		})();
+	}
+	await inited;
+	return ts;
+}
+
+async function language(name: string) {
+	if (!languages.has(name)) {
+		languages.set(name, (async () => {
+			const mod = await init();
+			const dir = wasmDir();
+			if (!mod || !dir) return undefined;
+			const file = EXTRA_WASM[name]?.() ?? join(dir, `tree-sitter-${name}.wasm`);
+			if (!file || !existsSync(file)) return undefined;
+			try { return await mod.Language.load(file); } catch { return undefined; }
+		})());
+	}
+	return languages.get(name)!;
+}
+
+export function languageForPath(path: string): string | undefined {
+	return LANG_BY_EXT[extname(path).toLowerCase()];
+}
+
+/**
+ * Top-level blocks from the syntax tree: each named child of the root that is a declaration
+ * becomes a block spanning its full line range (including a directly preceding comment).
+ * Leading imports and other non-block statements are folded into a header block.
+ */
+export async function treeSitterBlocks(path: string, text: string, maxBlocks = 48): Promise<Block[] | undefined> {
+	const lang = languageForPath(path);
+	if (!lang) return undefined;
+	const mod = await init();
+	const L = await language(lang);
+	if (!mod || !L) return undefined;
+	const parser = new mod.Parser();
+	parser.setLanguage(L);
+	const tree = parser.parse(text);
+	if (!tree) return undefined;
+	const lines = text.split("\n");
+	const root = tree.rootNode;
+	// Python and Ruby put everything under "module"/"program"; unwrap one level when the root has a single block child.
+	let children = root.namedChildren;
+	if (children.length === 1 && (children[0].type === "module" || children[0].type === "program")) children = children[0].namedChildren;
+	const blocks: Block[] = [];
+	let pendingComment: number | undefined;
+	let headerEnd = 0;
+	for (const c of children) {
+		if (!c) continue;
+		const startLine = c.startPosition.row;
+		const endLine = c.endPosition.row;
+		if (c.type === "comment") { if (pendingComment === undefined) pendingComment = startLine; continue; }
+		let node = c;
+		// export const x = ...; export default class ...; decorated defs
+		if ((c.type === "export_statement" || c.type === "decorated_definition") && c.namedChildren.length) {
+			const inner = c.namedChildren.find((n) => n && BLOCK_TYPES.has(n.type));
+			if (inner) node = inner;
+		}
+		// Multi-line top-level assignments (config dicts, tables, constants) are blocks too.
+		const isBigAssignment = (node.type === "expression_statement" || node.type === "assignment") && endLine - startLine >= 3;
+		// one-line declarations (type aliases, Kotlin data classes, Rust consts) are blocks too: they belong in the outline
+		const isBlock = BLOCK_TYPES.has(node.type) || isBigAssignment;
+		if (!isBlock) { pendingComment = undefined; if (blocks.length === 0) headerEnd = endLine; continue; }
+		const from = (pendingComment ?? startLine) + 1;
+		pendingComment = undefined;
+		const sig = lines[startLine].trim().slice(0, 120);
+		// Large classes: expose their methods as blocks so the second step can pick individual bodies.
+		const body = node.namedChildren.find((n) => n && (n.type === "class_body" || n.type === "block" || n.type === "declaration_list" || n.type === "field_declaration_list"));
+		const methods = body ? body.namedChildren.filter((n) => n && (n.type === "method_definition" || n.type === "function_definition" || n.type === "method_declaration" || n.type === "constructor_declaration" || n.type === "decorated_definition" || n.type === "function_item" || n.type === "function_declaration" || n.type === "companion_object" || n.type === "property_declaration")) : [];
+		if (endLine - startLine > 40 && methods.length >= 2) {
+			blocks.push({ name: sig, from, to: methods[0]!.startPosition.row });
+			for (let k = 0; k < methods.length; k++) {
+				const mm = methods[k]!;
+				const mEnd = k + 1 < methods.length ? methods[k + 1]!.startPosition.row : endLine + 1;
+				blocks.push({ name: `${sig.replace(/[{:]\s*$/, "")} › ${lines[mm.startPosition.row].trim().slice(0, 80)}`, from: mm.startPosition.row + 1, to: mEnd });
+			}
+			continue;
+		}
+		blocks.push({ name: sig, from, to: endLine + 1 });
+	}
+	tree.delete();
+	parser.delete();
+	if (blocks.length < 2) return blocks.length === 0 ? [] : undefined;
+	// fill gaps so the block list partitions the file
+	const out: Block[] = [];
+	if (blocks[0].from > 1) out.push({ name: "(header: imports, constants)", from: 1, to: blocks[0].from - 1 });
+	for (let i = 0; i < blocks.length; i++) {
+		const b = { ...blocks[i] };
+		const next = blocks[i + 1];
+		if (next && next.from > b.to + 1) b.to = next.from - 1;
+		if (!next && b.to < lines.length) b.to = lines.length;
+		out.push(b);
+	}
+	void headerEnd;
+	return out.slice(0, maxBlocks);
+}
+
+const SIGNATURE_TYPES = new Set(["function_declaration", "function_definition", "method_definition", "method_declaration", "constructor_declaration", "function_item", "decorated_definition", "class_declaration", "class_definition", "interface_declaration", "struct_item", "enum_item", "trait_item", "impl_item", "object_declaration", "companion_object", "type_alias_declaration", "type_item", "record_declaration", "enum_declaration", "abstract_class_declaration", "singleton_method", "method", "class", "module", "func_literal", "generator_function_declaration", "lexical_declaration", "property_declaration"]);
+
+/** 0-based rows of every declaration signature in the tree, at any nesting depth (methods in small classes, nested functions). */
+async function signatureRows(path: string, text: string): Promise<number[] | undefined> {
+	const lang = languageForPath(path);
+	if (!lang) return undefined;
+	const mod = await init();
+	const L = await language(lang);
+	if (!mod || !L) return undefined;
+	const parser = new mod.Parser();
+	parser.setLanguage(L);
+	const tree = parser.parse(text);
+	if (!tree) return undefined;
+	const rows = new Set<number>();
+	const walk = (n: import("web-tree-sitter").Node, depth: number) => {
+		if (depth > 6) return;
+		for (const c of n.namedChildren) {
+			if (!c) continue;
+			if (SIGNATURE_TYPES.has(c.type)) {
+				// property/lexical declarations only when they hold a function (arrow functions, lambdas) or are top-level
+				if ((c.type === "lexical_declaration" || c.type === "property_declaration") && depth > 0 && !/=>|lambda|fun\b|function\b/.test(text.split("\n")[c.startPosition.row])) continue;
+				rows.add(c.startPosition.row);
+			}
+			walk(c, depth + 1);
+		}
+	};
+	walk(tree.rootNode, 0);
+	tree.delete();
+	parser.delete();
+	return [...rows].sort((a, b) => a - b);
+}
+
+/** Signature lines (block starts) as an outline index list, 0-based. */
+export async function treeSitterOutline(path: string, text: string): Promise<number[] | undefined> {
+	const sigs = await signatureRows(path, text);
+	if (!sigs) return undefined;
+	const blocks = (await treeSitterBlocks(path, text)) ?? [];
+	const idx: number[] = [...sigs];
+	const lines = text.split("\n");
+	if (blocks.length === 0) for (let i = 0; i < Math.min(lines.length, 60); i++) if (/^\s*(import|from|require|use|package|#include|using)\b/.test(lines[i])) idx.push(i);
+	for (const b of blocks) {
+		if (b.name.startsWith("(header")) {
+			// imports plus any one-line declarations (Kotlin data classes, type aliases, constants) that were too short to be blocks
+			for (let i = b.from - 1; i < b.to; i++) if (/^\s*(import|from|require|use|package|#include|using)\b/.test(lines[i]) || /^(export\s+)?(const|let|var|val|type|typealias|data class|sealed class|enum class|class|interface|object|fun|def|pub|static|final)\b/.test(lines[i])) idx.push(i);
+			continue;
+		}
+		// the signature line is the first non-comment line of the block
+		for (let i = b.from - 1; i < b.to; i++) { if (!/^\s*(\/\/|\/\*|\*|#|"""|''')/.test(lines[i]) && lines[i].trim()) { idx.push(i); break; } }
+	}
+	return idx;
+}

package/src/types.ts

@@ -0,0 +1,45 @@
+export type Bucket = "keep" | "trim" | "forget";
+
+export interface Probabilities {
+	needed: number;
+	outcomeOnly: number;
+	durable: number;
+}
+
+export interface Decision {
+	/** toolCallId of the tool result this decision is about. */
+	id: string;
+	toolName: string;
+	bucket: Bucket;
+	durable: boolean;
+	p: Probabilities;
+	/** One-line description used in the stub, fixed at decision time so the stub never changes. */
+	summary: string;
+	tokensBefore: number;
+	decidedAt: number;
+	/** "pending" until first applied in a context call; then frozen forever. */
+	status: "pending" | "applied";
+	appliedAtCall?: number;
+	/** Why the decision was applied (rolling, cold-cache, compaction, forced). */
+	appliedReason?: string;
+}
+
+export interface DurableNote {
+	source: "user" | "agent" | "tool";
+	text: string;
+	p: number;
+	at: number;
+}
+
+export interface CallStats {
+	call: number;
+	at: number;
+	messages: number;
+	tokensOriginal: number;
+	tokensSent: number;
+	tokensPruned: number;
+	appliedNow: number;
+	frozen: number;
+	pendingHeld: number;
+	coldCache: boolean;
+}