@bobobowis/jev-kit 0.0.0-stage → 0.1.0

package/dist/cli/common.js

@@ -0,0 +1,40 @@
+/**
+ * What every subcommand shares: the client, the reporter, list flags, stdin, and a deadline.
+ */
+import { JevClient, sharedJev } from "../core/client.js";
+import { createDecider, createReporter } from "../events/index.js";
+export const processIo = () => ({ stdout: process.stdout, stderr: process.stderr, stdin: process.stdin });
+/**
+ * `--mock` selects the offline mock explicitly; otherwise the client picks TypeSafe or OpenRouter
+ * from the keys. A deadline gets its own client, so a call cut off by it is aborted, not left running.
+ */
+export function clientFor(mock, timeoutMs) {
+    if (!mock && !timeoutMs)
+        return sharedJev;
+    let client;
+    return () => (client ??= new JevClient(mock ? { provider: "mock" } : { timeoutMs }));
+}
+export function deciderFor(harness, opts) {
+    const reporter = createReporter({ harness, quiet: opts.quiet, stderr: opts.stderr });
+    return { reporter, decide: createDecider(reporter, opts.client ?? clientFor(opts.mock, opts.timeoutMs)) };
+}
+export const list = (raw) => (raw ?? "").split(",").map((s) => s.trim()).filter(Boolean);
+export async function readAll(stdin) {
+    let text = "";
+    for await (const chunk of stdin)
+        text += typeof chunk === "string" ? chunk : chunk.toString("utf8");
+    return text;
+}
+/** Resolve with the work, or with `fallback` once `ms` pass. The work keeps running but nobody waits. */
+export async function withDeadline(work, ms, fallback) {
+    let timer;
+    const late = new Promise((resolve) => { timer = setTimeout(() => resolve(fallback()), ms); });
+    try {
+        return await Promise.race([work, late]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+export class UsageError extends Error {
+}

package/dist/cli/hook.d.ts

@@ -0,0 +1,3 @@
+import { type Io } from "./common.ts";
+export declare const HOOK_HELP: string;
+export declare function hook(argv: string[], io: Io): Promise<number>;

package/dist/cli/hook.js

@@ -0,0 +1,82 @@
+/**
+ * jev hook: run as a Claude Code or Codex hook. Reads the hook payload on stdin, writes the
+ * harness's response on stdout. Fails open: a Jev error, a timeout, or a bad payload allows the
+ * action. Never exits 2, which both harnesses read as "block".
+ */
+import { parseArgs } from "node:util";
+import { ALL_GUARDS, runHarnessHook, HOOK_LINES } from "../hooks/index.js";
+import { deciderFor, list, readAll, withDeadline } from "./common.js";
+export const HOOK_HELP = `Usage: jev hook --harness claude|codex --event <HookEvent> [options]
+
+Reads the hook payload on stdin and answers on stdout. Exit 0 always, except 1 for bad options.
+
+Options:
+  --harness <name>     claude or codex
+  --event <name>       PreToolUse, PostToolUse, UserPromptSubmit, Stop, PreCompact
+  --guards <list>      bash,write,result (default: all)
+  --compact            run the Level 7 advisor on UserPromptSubmit and Stop
+  --lines <n,n,n>      notice, recommend, request lines in context tokens (default ${HOOK_LINES.notice},${HOOK_LINES.recommend},${HOOK_LINES.request})
+  --window <tokens>    the model's context window, for percentages
+  --timeout-ms <ms>    give up and allow after this long (default 8000)
+  --mock               use the offline mock instead of a Jev key
+`;
+export async function hook(argv, io) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv, strict: true,
+            options: {
+                harness: { type: "string" }, event: { type: "string" }, guards: { type: "string" }, compact: { type: "boolean" },
+                lines: { type: "string" }, window: { type: "string" }, "timeout-ms": { type: "string" }, mock: { type: "boolean" }, help: { type: "boolean", short: "h" },
+            },
+        }));
+    }
+    catch (err) {
+        io.stderr.write(`jev hook: ${err.message}\n\n${HOOK_HELP}`);
+        return 1;
+    }
+    if (values.help) {
+        io.stdout.write(HOOK_HELP);
+        return 0;
+    }
+    const harness = values.harness;
+    if (harness !== "claude" && harness !== "codex") {
+        io.stderr.write(`jev hook: --harness must be claude or codex\n`);
+        return 1;
+    }
+    if (!values.event) {
+        io.stderr.write(`jev hook: --event is required\n`);
+        return 1;
+    }
+    const guards = values.guards ? list(values.guards) : ALL_GUARDS;
+    const unknown = guards.filter((g) => !ALL_GUARDS.includes(g));
+    if (unknown.length) {
+        io.stderr.write(`jev hook: unknown guard ${unknown.join(", ")}; known: ${ALL_GUARDS.join(", ")}\n`);
+        return 1;
+    }
+    let lines = HOOK_LINES;
+    if (values.lines) {
+        const [notice, recommend, request] = list(values.lines).map(Number);
+        if (![notice, recommend, request].every((n) => Number.isFinite(n) && n > 0) || !(notice < recommend && recommend < request)) {
+            io.stderr.write(`jev hook: --lines needs three increasing token counts, for example 50000,100000,150000\n`);
+            return 1;
+        }
+        lines = { notice, recommend, request };
+    }
+    const window = values.window ? Number(values.window) : null;
+    const timeoutMs = values["timeout-ms"] ? Number(values["timeout-ms"]) : 8000;
+    const { reporter, decide } = deciderFor(harness, { mock: values.mock, stderr: io.stderr, timeoutMs, client: io.client });
+    let payload;
+    try {
+        payload = JSON.parse(await readAll(io.stdin));
+    }
+    catch (err) {
+        reporter.report("error", { hook: values.event, message: `unreadable hook payload: ${err?.message ?? err}` });
+        return 0;
+    }
+    const response = await withDeadline(runHarnessHook(values.event, payload, { harness, guards, compact: values.compact, lines, window, decide, report: (k, p) => reporter.report(k, p) })
+        .catch((err) => { reporter.report("error", { hook: values.event, message: err?.message ?? String(err) }); return null; }), timeoutMs, () => { reporter.report("error", { hook: values.event, message: `timed out after ${timeoutMs} ms; allowed` }); return null; });
+    if (response)
+        io.stdout.write(JSON.stringify(response));
+    return 0;
+}

package/dist/cli/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli/index.js

@@ -0,0 +1,21 @@
+#!/usr/bin/env node
+/**
+ * The `jev` bin. Everything lives in main.ts, so tests can call it without a process.
+ */
+import { main } from "./main.js";
+import { processIo } from "./common.js";
+// A reader that stops early (`jev files ... | head -1`) closes the pipe: that ends the output, not an error.
+process.stdout.on("error", (err) => {
+    if (err.code === "EPIPE")
+        process.exit(process.exitCode ?? 0);
+    throw err;
+});
+const argv = process.argv.slice(2);
+main(argv, processIo()).then((code) => {
+    // A hook must exit as soon as it has answered: a Jev call abandoned at the deadline would
+    // otherwise hold the process, and the harness waits for it. Exit once stdout has flushed.
+    if (argv[0] === "hook")
+        process.stdout.write("", () => process.exit(code));
+    else
+        process.exitCode = code;
+});

package/dist/cli/main.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The `jev` command: one bin, one subcommand per delivery surface.
+ */
+import { HOOK_HELP } from "./hook.ts";
+import type { Io } from "./common.ts";
+export { HOOK_HELP };
+export declare function helpText(): string;
+export declare function main(argv: string[], io: Io): Promise<number>;

package/dist/cli/main.js

@@ -0,0 +1,41 @@
+/**
+ * The `jev` command: one bin, one subcommand per delivery surface.
+ */
+import { hook, HOOK_HELP } from "./hook.js";
+import { setup } from "./setup.js";
+import { mcp } from "./mcp.js";
+import { ask, files, gate, guard } from "./ask.js";
+const SUBCOMMANDS = [
+    ["ask", "Ask a question block about a state, files, or a command's output; JSON on stdout", ask],
+    ["files", "Ask the same question block about each file, in parallel", files],
+    ["gate", "One yes or no question; exit 0 yes, 1 no, 2 usage, 3 Jev error", gate],
+    ["guard", "Check a shell command or a file write with the Level 6 gates; exit 0 allow, 1 block", guard],
+    ["setup", "Write or merge the Jev hooks and MCP server into a project's Claude Code or Codex config", setup],
+    ["hook", "Run as a Claude Code or Codex hook: guards and the compaction advisor", hook],
+    ["mcp", "Serve the Jev tools over stdio MCP", mcp],
+];
+export { HOOK_HELP };
+export function helpText() {
+    const width = Math.max(...SUBCOMMANDS.map(([n]) => n.length));
+    return [
+        "Usage: jev <command> [options]",
+        "",
+        "Commands:",
+        ...SUBCOMMANDS.map(([n, s]) => `  ${n.padEnd(width)}  ${s}`),
+        "",
+        "Run `jev <command> --help` for a command's options.",
+    ].join("\n");
+}
+export async function main(argv, io) {
+    const [command, ...rest] = argv;
+    if (!command || command === "--help" || command === "-h" || command === "help") {
+        io.stdout.write(helpText() + "\n");
+        return 0;
+    }
+    const entry = SUBCOMMANDS.find(([n]) => n === command);
+    if (!entry) {
+        io.stderr.write(`jev: unknown command "${command}".\n\n${helpText()}\n`);
+        return 2;
+    }
+    return entry[2](rest, io);
+}

package/dist/cli/mcp.d.ts

@@ -0,0 +1,3 @@
+import { type Io } from "./common.ts";
+export declare const MCP_HELP = "Usage: jev mcp [--level 7..10 | --tools a,b] [--cwd dir] [--mock]\n\nServes the Jev tools over stdio MCP. Paths resolve against --cwd (default: where it was started).\nWith neither --level nor --tools it serves all of them.\n";
+export declare function mcp(argv: string[], io: Io): Promise<number>;

package/dist/cli/mcp.js

@@ -0,0 +1,47 @@
+/**
+ * jev mcp: serve the Jev tools over stdio MCP, by level or by tool name.
+ */
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { serve } from "../mcp/server.js";
+import { selectTools } from "../tools/sets.js";
+import { deciderFor, list } from "./common.js";
+export const MCP_HELP = `Usage: jev mcp [--level 7..10 | --tools a,b] [--cwd dir] [--mock]
+
+Serves the Jev tools over stdio MCP. Paths resolve against --cwd (default: where it was started).
+With neither --level nor --tools it serves all of them.
+`;
+const version = () => {
+    try {
+        return JSON.parse(readFileSync(new URL("../../package.json", import.meta.url), "utf8")).version;
+    }
+    catch {
+        return "0.0.0";
+    }
+};
+export async function mcp(argv, io) {
+    let values;
+    try {
+        ({ values } = parseArgs({ args: argv, strict: true, options: { level: { type: "string" }, tools: { type: "string" }, cwd: { type: "string" }, mock: { type: "boolean" }, help: { type: "boolean", short: "h" } } }));
+    }
+    catch (err) {
+        io.stderr.write(`jev mcp: ${err.message}\n\n${MCP_HELP}`);
+        return 2;
+    }
+    if (values.help) {
+        io.stdout.write(MCP_HELP);
+        return 0;
+    }
+    let tools;
+    try {
+        tools = selectTools({ level: values.level !== undefined ? Number(values.level) : undefined, names: values.tools ? list(values.tools) : undefined });
+    }
+    catch (err) {
+        io.stderr.write(`jev mcp: ${err.message}\n`);
+        return 2;
+    }
+    const { reporter, decide } = deciderFor("mcp", { mock: values.mock, stderr: io.stderr, client: io.client });
+    await serve({ tools, cwd: resolve(values.cwd ?? process.cwd()), decide, report: (k, p) => reporter.report(k, p), version: version() });
+    return 0;
+}

package/dist/cli/setup.d.ts

@@ -0,0 +1,3 @@
+import { type Io } from "./common.ts";
+export declare const SETUP_HELP = "Usage: jev setup --harness claude|codex [options]\n\nWrites or merges the Jev entries into the project's agent config, leaving everything else alone.\nClaude Code: .mcp.json and .claude/settings.json. Codex: a marked block in .codex/config.toml.\nEach run sets the whole selection: running it again replaces only what it set up before.\n\nOptions:\n  --harness <name>    claude or codex\n  --guards <list>     bash,write,result: the Level 6 hooks\n  --tools <list>      Jev tools to serve over MCP, for example ask_jev,ask_jev_files\n  --compact           the Level 7 advisor hooks\n  --level <n>         a lab level: 6 guards, 7 advisor, 8 to 10 their tools\n  --out <dir>         the project directory (default: the current one)\n  --command <cmd>     how to run jev in the hooks and the MCP entry (default: node and this package's bin)\n  --hook-args <args>  extra jev hook flags, for example \"--lines 60000,120000,180000\"\n  --dry-run           print what would change, write nothing\n";
+export declare function setup(argv: string[], io: Io): Promise<number>;

package/dist/cli/setup.js

@@ -0,0 +1,79 @@
+/**
+ * jev setup: wire the Jev hooks and MCP server into a project's Claude Code or Codex config.
+ */
+import { parseArgs } from "node:util";
+import { relative } from "node:path";
+import { toPosix } from "../files/read-state.js";
+import { apply, describeSelection, plan, SetupError } from "../setup/index.js";
+import { list } from "./common.js";
+export const SETUP_HELP = `Usage: jev setup --harness claude|codex [options]
+
+Writes or merges the Jev entries into the project's agent config, leaving everything else alone.
+Claude Code: .mcp.json and .claude/settings.json. Codex: a marked block in .codex/config.toml.
+Each run sets the whole selection: running it again replaces only what it set up before.
+
+Options:
+  --harness <name>    claude or codex
+  --guards <list>     bash,write,result: the Level 6 hooks
+  --tools <list>      Jev tools to serve over MCP, for example ask_jev,ask_jev_files
+  --compact           the Level 7 advisor hooks
+  --level <n>         a lab level: 6 guards, 7 advisor, 8 to 10 their tools
+  --out <dir>         the project directory (default: the current one)
+  --command <cmd>     how to run jev in the hooks and the MCP entry (default: node and this package's bin)
+  --hook-args <args>  extra jev hook flags, for example "--lines 60000,120000,180000"
+  --dry-run           print what would change, write nothing
+`;
+export async function setup(argv, io) {
+    let values;
+    try {
+        ({ values } = parseArgs({
+            args: argv, strict: true,
+            options: {
+                harness: { type: "string" }, guards: { type: "string" }, tools: { type: "string" }, compact: { type: "boolean" },
+                level: { type: "string" }, out: { type: "string" }, command: { type: "string" }, "hook-args": { type: "string" },
+                "dry-run": { type: "boolean" }, help: { type: "boolean", short: "h" },
+            },
+        }));
+    }
+    catch (err) {
+        io.stderr.write(`jev setup: ${err.message}\n\n${SETUP_HELP}`);
+        return 2;
+    }
+    if (values.help) {
+        io.stdout.write(SETUP_HELP);
+        return 0;
+    }
+    const harness = values.harness;
+    if (harness !== "claude" && harness !== "codex") {
+        io.stderr.write("jev setup: --harness must be claude or codex\n");
+        return 2;
+    }
+    const dir = values.out ?? process.cwd();
+    try {
+        const selection = {
+            guards: values.guards ? list(values.guards) : undefined,
+            tools: values.tools ? list(values.tools) : undefined,
+            compact: values.compact,
+            level: values.level !== undefined ? Number(values.level) : undefined,
+        };
+        const changes = plan({
+            harness, dir, ...selection,
+            command: values.command ? values.command.split(/\s+/).filter(Boolean) : undefined,
+            hookArgs: values["hook-args"] ? values["hook-args"].split(/\s+/).filter(Boolean) : undefined,
+        });
+        const changed = changes.filter((c) => c.changed);
+        if (values["dry-run"]) {
+            for (const c of changes)
+                io.stdout.write(`--- ${toPosix(relative(dir, c.path) || c.path)}${c.changed ? "" : " (unchanged)"}\n${c.after}`);
+            return 0;
+        }
+        apply(changes);
+        io.stdout.write(changed.length ? `jev setup: wrote ${changed.map((c) => toPosix(relative(dir, c.path))).join(", ")}\n` : "jev setup: no changes\n");
+        io.stdout.write(`jev setup: on: ${describeSelection(selection)}. Running it again replaces this selection.\n`);
+        return 0;
+    }
+    catch (err) {
+        io.stderr.write(`jev setup: ${err instanceof SetupError ? err.message : err?.message ?? err}\n`);
+        return 1;
+    }
+}

package/dist/compact/compact-on-demand.d.ts

@@ -0,0 +1,22 @@
+/**
+ * Level 7, option B: should_i_compact on demand.
+ * The same four questions and the same tiers, but the agent asks. The tool returns a typed verdict it can act on instead of a nudge it might miss.
+ */
+import type { CompactAction, CompactAnswers, CompactDecision, Lines, Usage } from "./should-compact.ts";
+export interface CompactVerdict {
+    should_compact: boolean;
+    tier: CompactDecision["tier"];
+    reason: string;
+    context_tokens: number | null;
+    context_percent: number | null;
+    lines: Lines;
+    signals: {
+        switched_gears: number;
+        at_boundary: number;
+        needs_history: number;
+        mid_operation: number;
+    };
+    next_step: string;
+}
+/** The tool result the agent reads. Booleans and numbers first, prose last. */
+export declare function compactVerdict(d: CompactDecision, a: CompactAnswers, usage: Usage | null, lines: Lines, action?: CompactAction): CompactVerdict;

package/dist/compact/compact-on-demand.js

@@ -0,0 +1,29 @@
+/** The tool result the agent reads. Booleans and numbers first, prose last. */
+export function compactVerdict(d, a, usage, lines, action = "compact_now") {
+    const should = d.tier === "recommend" || d.tier === "request";
+    return {
+        should_compact: should,
+        tier: d.tier,
+        reason: d.reason,
+        context_tokens: usage ? usage.tokens : null,
+        context_percent: usage && usage.pct !== null ? Number(usage.pct.toFixed(1)) : null,
+        lines,
+        signals: {
+            switched_gears: a.switched_gears.noul,
+            at_boundary: a.at_boundary.noul,
+            needs_history: a.needs_history.score,
+            mid_operation: a.mid_operation.noul,
+        },
+        next_step: action === "ask_user"
+            ? should
+                ? "Ask the user to run /compact with a one line note of what to keep, then continue the current request."
+                : d.tier === "notice"
+                    ? "Optional. Continue, or suggest /compact to the user at a clean point."
+                    : "Continue. Nothing to do."
+            : should
+                ? "Call compact_now with a short note to yourself, then continue the current request."
+                : d.tier === "notice"
+                    ? "Optional. Continue, or call compact_now if you are at a clean point."
+                    : "Continue. Nothing to do.",
+    };
+}

package/dist/compact/evaluate.d.ts

@@ -0,0 +1,36 @@
+/**
+ * One evaluation of the Level 7 decision from a harness-neutral view of the session: the user
+ * requests so far, the last turn, and context usage when the harness reports it. pi builds the
+ * input from its session; the Claude and Codex hooks build it from the transcript.
+ */
+import type { Decider } from "../events/index.ts";
+import { type CompactAction, type CompactAnswers, type CompactDecision, type CompactState, type Lines, type Usage } from "./should-compact.ts";
+export interface TurnInput {
+    /** Every user request so far, oldest first. */
+    requests: string[];
+    /** The last compaction summary, when there was one. */
+    summary?: string;
+    /** The assistant's last text, empty when the turn was tool calls only. */
+    recentTurn: string;
+    toolsThisTurn: string[];
+    /** Null when the harness gives no reading. */
+    usage: Usage | null;
+    /** Whether there is anything the harness could compact. */
+    compactable: boolean;
+    lines: Lines;
+    turn?: number;
+}
+export interface Evaluation {
+    decision: CompactDecision;
+    message: string | null;
+    usage: Usage | null;
+    answers: CompactAnswers | null;
+    state: CompactState;
+}
+/** The state Jev sees. Built in code from the session, no LLM involved. */
+export declare function buildCompactState(input: TurnInput): CompactState;
+/**
+ * Ask the four questions and decide the tier, reporting a `hook` event either way. The first
+ * request is silent with no call: there is nothing to move on from yet.
+ */
+export declare function evaluateCompaction(input: TurnInput, source: string, decide: Decider, report: (kind: string, payload: Record<string, unknown>) => void, action?: CompactAction): Promise<Evaluation>;

package/dist/compact/evaluate.js

@@ -0,0 +1,31 @@
+import { COMPACT_QUESTIONS, decideTier, tierMessage, } from "./should-compact.js";
+const clip = (s, n) => (s.length > n ? s.slice(0, n - 1) + "…" : s);
+/** The state Jev sees. Built in code from the session, no LLM involved. */
+export function buildCompactState(input) {
+    const previous = [...input.requests.slice(0, -1).map((m) => clip(m, 200)), input.summary ? `Summary so far: ${clip(input.summary, 400)}` : ""].filter(Boolean).join("\n");
+    return {
+        current_request: clip(input.requests.at(-1) ?? "", 600),
+        previous_work: previous || "(nothing before this request)",
+        recent_turn: clip(input.recentTurn.trim() || `(tool calls only: ${input.toolsThisTurn.join(", ") || "none"})`, 600),
+        tools_this_turn: input.toolsThisTurn,
+    };
+}
+/**
+ * Ask the four questions and decide the tier, reporting a `hook` event either way. The first
+ * request is silent with no call: there is nothing to move on from yet.
+ */
+export async function evaluateCompaction(input, source, decide, report, action = "compact_now") {
+    const state = buildCompactState(input);
+    const base = { hook: source, turn: input.turn, usage: input.usage, usage_known: input.usage !== null, lines: input.lines, compactable: input.compactable };
+    if (input.requests.length < 2) {
+        const decision = { tier: "silent", reason: "first request, nothing to move on from" };
+        report("hook", { ...base, tier: decision.tier, reason: decision.reason, message: null, skipped: true });
+        return { decision, message: null, usage: input.usage, answers: null, state };
+    }
+    const { answers } = await decide(source, state, COMPACT_QUESTIONS, { turn: input.turn, context: input.usage, lines: input.lines });
+    const a = answers;
+    const decision = decideTier(a, input.usage, input.compactable, input.lines, state);
+    const message = tierMessage(decision, input.usage, action);
+    report("hook", { ...base, tier: decision.tier, reason: decision.reason, message });
+    return { decision, message, usage: input.usage, answers: a, state };
+}

package/dist/compact/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Compaction: the Level 7 decisions. Four questions after a turn, a tier in code, the verdict for an on-demand tool, and the cut point.
+ */
+export * from "./should-compact.ts";
+export * from "./compact-on-demand.ts";
+export * from "./pick-cut-point.ts";
+export * from "./evaluate.ts";

package/dist/compact/index.js

@@ -0,0 +1,7 @@
+/**
+ * Compaction: the Level 7 decisions. Four questions after a turn, a tier in code, the verdict for an on-demand tool, and the cut point.
+ */
+export * from "./should-compact.js";
+export * from "./compact-on-demand.js";
+export * from "./pick-cut-point.js";
+export * from "./evaluate.js";

package/dist/compact/pick-cut-point.d.ts

@@ -0,0 +1,18 @@
+import type { ChoiceAnswer } from "../core/types.ts";
+export interface TurnSummary {
+    /** Zero based index in the session. */
+    index: number;
+    /** The user message that started the turn, trimmed. */
+    request: string;
+}
+/** One Choice over the turns. Keys are the indices, so the pick is always a real turn. */
+export declare function cutPointQuestion(turns: TurnSummary[]): {
+    live_from: import("../core/types.ts").ChoiceQuestion;
+};
+export interface CutPoint {
+    liveFrom: number | null;
+    confidence: number;
+    instructions: string;
+}
+/** The pick as compaction instructions. Low confidence falls back to pi's default cut. */
+export declare function cutPointInstructions(turns: TurnSummary[], answer: ChoiceAnswer, floor?: number): CutPoint;

package/dist/compact/pick-cut-point.js

@@ -0,0 +1,29 @@
+/**
+ * Level 7, option C: pick the cut point.
+ * When compaction runs, which turn starts the work that is still live? A Choice over the session's turns, each described by the user message that started it. Code turns the pick into the compaction instructions.
+ */
+import { choice } from "../core/helpers.js";
+/** One Choice over the turns. Keys are the indices, so the pick is always a real turn. */
+export function cutPointQuestion(turns) {
+    const criteria = {};
+    for (const t of turns)
+        criteria[String(t.index)] = t.request;
+    criteria.none = "Every turn is still live; keep the most recent context only";
+    return {
+        live_from: choice("Which turn in `turns` starts the work that is still live? Earlier turns can be summarized briefly.", criteria),
+    };
+}
+/** The pick as compaction instructions. Low confidence falls back to pi's default cut. */
+export function cutPointInstructions(turns, answer, floor = 0.6) {
+    if (answer.choice === "none" || answer.confidence < floor) {
+        return { liveFrom: null, confidence: answer.confidence, instructions: "Summarize the earlier work briefly and keep the most recent turns in detail." };
+    }
+    const idx = Number(answer.choice);
+    const turn = turns.find((t) => t.index === idx);
+    const from = turn ? `"${turn.request}"` : `turn ${idx}`;
+    return {
+        liveFrom: idx,
+        confidence: answer.confidence,
+        instructions: `The live work starts at ${from}. Summarize everything before it in a few lines. Keep the decisions, file paths, and open questions from ${from} onward in full detail.`,
+    };
+}

package/dist/compact/should-compact.d.ts

@@ -0,0 +1,57 @@
+import type { NoulAnswer, ScoreAnswer } from "../core/types.ts";
+/** What the hook sends. Built in code from the session, no LLM involved. */
+export type CompactState = {
+    /** The latest user message, trimmed. */
+    current_request: string;
+    /** Earlier user messages plus the last compaction summary, trimmed. */
+    previous_work: string;
+    /** The assistant's last text plus the tools it called, trimmed. */
+    recent_turn: string;
+    tools_this_turn: string[];
+};
+export declare const COMPACT_QUESTIONS: {
+    switched_gears: import("../core/types.ts").NoulQuestion;
+    at_boundary: import("../core/types.ts").NoulQuestion;
+    needs_history: import("../core/types.ts").ScoreQuestion;
+    mid_operation: import("../core/types.ts").NoulQuestion;
+};
+export interface CompactAnswers {
+    switched_gears: NoulAnswer;
+    at_boundary: NoulAnswer;
+    needs_history: ScoreAnswer;
+    mid_operation: NoulAnswer;
+}
+export type Tier = "silent" | "notice" | "recommend" | "request";
+/**
+ * Context tokens, not percent: a 1M window makes percent useless for a short session. Low on
+ * purpose so a few file reads cross them. pi's keepRecentTokens must sit below the notice line.
+ */
+export interface Lines {
+    notice: number;
+    recommend: number;
+    request: number;
+}
+export declare const DEFAULT_LINES: Lines;
+/** What the gauge reads: tokens in context, and the same as a percent of the model's window (null when the window is unknown). */
+export interface Usage {
+    tokens: number;
+    pct: number | null;
+}
+/** A gauge reading in words: "12k tokens, 6.0% of the window", or just the tokens. */
+export declare const usageText: (u: Usage) => string;
+export interface CompactDecision {
+    tier: Tier;
+    reason: string;
+}
+/**
+ * The decision, numbers in code. Silent when there is nothing to compact, when the agent is mid
+ * operation, or when the work has not moved on. Otherwise the tier follows usage against the lines.
+ */
+export declare function decideTier(a: CompactAnswers, usage: Usage | null, compactable: boolean, lines: Lines, state?: CompactState): CompactDecision;
+/**
+ * How the agent can act on a tier: call compact_now itself (pi), or ask the user to run /compact
+ * (Claude Code, Codex, where a tool cannot start compaction).
+ */
+export type CompactAction = "compact_now" | "ask_user";
+/** The exact text the agent sees on its next call. Silent returns null: nothing is injected. */
+export declare function tierMessage(d: CompactDecision, usage: Usage | null, action?: CompactAction): string | null;