@alisio/core 0.8.0 → 0.10.0

package/dist/context/elide.js

@@ -0,0 +1,222 @@
+import { DEFAULT_READ_BYTES } from "../background/output.js";
+import { estimateTokens } from "../core/compaction.js";
+import { describeCall, parseObject, resultText, segmentId, sha, stableStringify, WRITE_TOOLS, } from "./util.js";
+/**
+ * Deterministic elision by substitution (spec 012 phase 2). Pure functions over `Message[]`: they
+ * never touch the persisted transcript, only compute what a request MAY send instead.
+ */
+/** Version of the elision rules. Bump it whenever a rule or a stub format changes. */
+export const CONTEXT_POLICY_VERSION = 1;
+const READ_STUB_DEFAULT_START = 1;
+const READ_STUB_DEFAULT_LIMIT = 200;
+const HEAD_SHA = /^\{"path":"(?:[^"\\]|\\.)*","sha256":"([0-9a-f]{64})"/;
+/** `sha256` of a read_file result, from the parsed JSON or (clipped results) from its head. */
+function readSha(text) {
+    const value = parseObject(text)?.sha256;
+    if (typeof value === "string" && value.length > 0)
+        return value;
+    if (value !== undefined)
+        return undefined;
+    return HEAD_SHA.exec(text.slice(0, 4096))?.[1];
+}
+/** bg_output arguments with the tool's own defaults applied, as a comparison key. */
+function bgKey(call) {
+    const id = call.args?.id;
+    if (typeof id !== "string")
+        return undefined;
+    const offset = typeof call.args?.offset === "number" ? call.args.offset : 0;
+    const limit = typeof call.args?.limit === "number" ? call.args.limit : DEFAULT_READ_BYTES;
+    return { id, offset, key: `${id}\0${offset}\0${limit}` };
+}
+/**
+ * Hash of what a search found: the exit code and the ripgrep `match`/`context` lines. The summary
+ * lines carry the elapsed time and would make identical searches look different. Text that is not
+ * the expected shape is hashed as is.
+ */
+function searchHash(text) {
+    const out = parseObject(text);
+    if (!out || typeof out.stdout !== "string" || typeof out.exitCode !== "number")
+        return sha(text);
+    const kept = [];
+    for (const line of out.stdout.split("\n")) {
+        if (line === "")
+            continue;
+        const event = parseObject(line);
+        if (!event)
+            return sha(text);
+        if (event.type === "match" || event.type === "context")
+            kept.push(line);
+    }
+    return sha(`${out.exitCode}\n${kept.join("\n")}`);
+}
+const searchKey = (e) => `${e.call.args ? stableStringify(e.call.args) : e.call.arguments}\0${searchHash(e.text)}`;
+/**
+ * Which tool results a later result makes redundant, regardless of age. `witness` is the index of
+ * the EARLIEST later result that proves it, so it never changes when messages are appended. Every
+ * rule is existential ("some later result exists"), which is what makes the set grow monotonically.
+ * Error results are neither candidates nor witnesses.
+ */
+export function elisionCandidates(messages) {
+    return analyze(messages).candidates;
+}
+function analyze(messages) {
+    const calls = new Map();
+    const entries = [];
+    messages.forEach((m, index) => {
+        if (m.role === "assistant") {
+            for (const c of m.calls)
+                calls.set(c.id, describeCall(c.name, c.arguments));
+        }
+        else if (m.role === "tool" && m.result.isError !== true) {
+            const call = calls.get(m.callId);
+            if (call)
+                entries.push({ index, callId: m.callId, call, text: resultText(m) });
+        }
+    });
+    const out = new Map();
+    const byIndex = new Map(entries.map((e) => [e.index, e]));
+    const byPath = new Map();
+    const byTask = new Map();
+    const bySearch = new Map();
+    for (const e of entries) {
+        if (e.call.path) {
+            const list = byPath.get(e.call.path) ?? [];
+            list.push(e);
+            byPath.set(e.call.path, list);
+        }
+        else if (e.call.name === "bg_output") {
+            const id = bgKey(e.call)?.id;
+            if (id !== undefined)
+                byTask.set(id, [...(byTask.get(id) ?? []), e]);
+        }
+        else if (e.call.name === "search_text") {
+            const key = searchKey(e);
+            bySearch.set(key, [...(bySearch.get(key) ?? []), e]);
+        }
+    }
+    for (const list of byPath.values()) {
+        list.forEach((x, at) => {
+            if (x.call.name !== "read_file")
+                return;
+            const shaX = readSha(x.text);
+            const w = list.slice(at + 1).find((later) => {
+                if (WRITE_TOOLS.has(later.call.name))
+                    return true;
+                if (later.call.name !== "read_file")
+                    return false;
+                const shaW = readSha(later.text);
+                return shaX !== undefined && shaW !== undefined && shaX !== shaW;
+            });
+            if (w)
+                out.set(x.index, { reason: "superseded_read", witness: w.index });
+        });
+    }
+    for (const list of byTask.values()) {
+        list.forEach((x, at) => {
+            const mine = bgKey(x.call);
+            if (!mine)
+                return;
+            const emptyPoll = parseObject(x.text)?.text === "";
+            const w = list
+                .slice(at + 1)
+                .find((later) => emptyPoll || bgKey(later.call)?.key === mine.key);
+            if (w)
+                out.set(x.index, { reason: "stale_bg_output", witness: w.index });
+        });
+    }
+    for (const list of bySearch.values()) {
+        list.forEach((x, at) => {
+            const w = list[at + 1];
+            if (w)
+                out.set(x.index, { reason: "duplicate_search", witness: w.index });
+        });
+    }
+    return { candidates: out, entries: byIndex };
+}
+/** JSON text restricted to printable ASCII on one line, so a stub never needs escaping again. */
+const quote = (value) => (JSON.stringify(value) ?? "null").replace(/[^\x20-\x7e]/g, (c) => `\\u${c.charCodeAt(0).toString(16).padStart(4, "0")}`);
+/** The replacement text. It depends only on the elided call's arguments and its own result head. */
+function stubFor(reason, x) {
+    if (reason === "superseded_read") {
+        const { startLine, limit } = x.call.args ?? {};
+        const window = typeof startLine === "number" || typeof limit === "number"
+            ? ` lines ${typeof startLine === "number" ? startLine : READ_STUB_DEFAULT_START}+${typeof limit === "number" ? limit : READ_STUB_DEFAULT_LIMIT}`
+            : "";
+        return `[elided: read_file ${quote(x.call.path)}@${(readSha(x.text) ?? "unknown").slice(0, 8)}${window}; re-read to view]`;
+    }
+    if (reason === "stale_bg_output") {
+        const mine = bgKey(x.call);
+        return `[elided: bg_output ${quote(mine?.id)} offset ${mine?.offset ?? 0}; a later bg_output covers it]`;
+    }
+    return `[elided: search_text ${quote(x.call.args?.pattern)}; identical to a later result]`;
+}
+/** Estimated tokens of everything a message puts in front of the model. */
+function visibleTokens(m) {
+    if (m.role === "tool")
+        return estimateTokens(resultText(m));
+    if (m.role === "user")
+        return estimateTokens(m.text);
+    return estimateTokens(m.calls.reduce((text, c) => `${text}\n${c.name} ${c.arguments}`, m.text));
+}
+/**
+ * Projects the history a request would carry: tool results that a later result made redundant are
+ * replaced by a one-line stub once they are `minAgeTurns` assistant messages old (counted inside the
+ * eligible prefix). With `epochMessages` E > 0 only the prefix `floor(n / E) * E` is eligible, so the
+ * projected history grows by appending between epochs and a provider prompt cache stays valid.
+ */
+export function projectContext(messages, o) {
+    const n = messages.length;
+    const epoch = Number.isFinite(o.epochMessages) ? Math.max(0, Math.floor(o.epochMessages)) : 0;
+    const minAge = Number.isFinite(o.minAgeTurns) ? Math.max(1, Math.floor(o.minAgeTurns)) : 1;
+    const boundary = epoch > 0 ? Math.floor(n / epoch) * epoch : n;
+    const prefix = boundary === n ? messages : messages.slice(0, boundary);
+    const { candidates, entries } = analyze(prefix);
+    const tokensBefore = messages.reduce((t, m) => t + visibleTokens(m), 0);
+    if (candidates.size === 0)
+        return { messages, elisions: [], tokensBefore, tokensAfter: tokensBefore, boundary };
+    // Assistant messages after each index, inside the prefix.
+    const assistantsAfter = new Array(boundary).fill(0);
+    let seen = 0;
+    for (let i = boundary - 1; i >= 0; i--) {
+        assistantsAfter[i] = seen;
+        if (prefix[i]?.role === "assistant")
+            seen++;
+    }
+    const elisions = [];
+    let projected;
+    for (const [index, c] of [...candidates].sort(([a], [b]) => a - b)) {
+        if ((assistantsAfter[index] ?? 0) < minAge)
+            continue;
+        const x = entries.get(index);
+        const m = prefix[index];
+        const w = prefix[c.witness];
+        if (!x || m?.role !== "tool" || w?.role !== "tool")
+            continue;
+        const text = x.text;
+        const stub = stubFor(c.reason, x);
+        // Size guard: a stub that is not shorter would cost more than it saves. It depends on the
+        // elided entry alone, so it never makes a decision flip under append.
+        if (stub.length >= text.length)
+            continue;
+        projected ??= messages.slice();
+        projected[index] = { ...m, result: { ...m.result, content: [{ type: "text", text: stub }] } };
+        elisions.push({
+            index,
+            callId: m.callId,
+            segmentId: segmentId("tool_result", m.callId, text),
+            reason: c.reason,
+            witnessCallId: w.callId,
+            tokensSaved: estimateTokens(text) - estimateTokens(stub),
+        });
+    }
+    if (!projected)
+        return { messages, elisions: [], tokensBefore, tokensAfter: tokensBefore, boundary };
+    const saved = elisions.reduce((t, e) => t + e.tokensSaved, 0);
+    return {
+        messages: projected,
+        elisions,
+        tokensBefore,
+        tokensAfter: tokensBefore - saved,
+        boundary,
+    };
+}

package/dist/context/format.d.ts

@@ -0,0 +1,21 @@
+import type { ContextReport, ContextSegment } from "@alisio/sdk";
+import type { GovernanceSnapshot } from "./governance.ts";
+import type { UsageSummary } from "./usage.ts";
+/**
+ * The "Context Governor" block of `/stats`, shared by the core handler and the TUI report.
+ * `undefined` when there is nothing to show (mode `off`, or no request has been measured yet), so
+ * the section is omitted. Counts and ratios only; the usage figures are a path heuristic for this
+ * process and session (spec 012 section 3.4).
+ */
+export declare function formatContextGovernorStatsSection(input: {
+    governance?: GovernanceSnapshot;
+    usage?: UsageSummary;
+}): string | undefined;
+/** The segments a reader needs explained: pinned, elided and low ones. The rest is counted. */
+export declare const notableSegments: (report: ContextReport) => ContextSegment[];
+/**
+ * `/context` as markdown, for the TUI and the core command catalog. It renders the same
+ * `ContextReport` the web panel and the route show: every elided, pinned and low segment with its
+ * reason, and counts for the rest. Ids, counts and estimates only.
+ */
+export declare function formatContextReport(report: ContextReport): string;

package/dist/context/format.js

@@ -0,0 +1,81 @@
+const REASONS = ["superseded_read", "stale_bg_output", "duplicate_search"];
+const percent = (used, observed) => Math.round((used / observed) * 100);
+/**
+ * The "Context Governor" block of `/stats`, shared by the core handler and the TUI report.
+ * `undefined` when there is nothing to show (mode `off`, or no request has been measured yet), so
+ * the section is omitted. Counts and ratios only; the usage figures are a path heuristic for this
+ * process and session (spec 012 section 3.4).
+ */
+export function formatContextGovernorStatsSection(input) {
+    const { governance: g, usage: u } = input;
+    const hasUsage = !!u && u.observed + u.pending + u.unattributed + u.stubOnly + u.rereads > 0;
+    if (!g && !hasUsage)
+        return undefined;
+    const lines = ["**Context Governor**", ""];
+    if (g) {
+        lines.push(`- Mode: ${g.mode} · policy v${g.policyVersion}`);
+        const reasons = REASONS.filter((r) => g.byReason[r] > 0).map((r) => `${r} ${g.byReason[r]}`);
+        lines.push(`- Last request: ${g.messages} messages · ${g.elided} elided${reasons.length ? ` (${reasons.join(", ")})` : ""} · ~${g.tokensSaved} tokens saved (estimate)`);
+        const inv = g.invariants;
+        if (inv.count > 0 || inv.chars > 0 || inv.omitted > 0)
+            lines.push(`- Invariants: ${inv.count} (${inv.chars} chars, ${inv.omitted} omitted)`);
+    }
+    if (u && hasUsage) {
+        if (u.observed > 0) {
+            const tools = Object.entries(u.byTool)
+                .filter(([, c]) => c.observed > 0)
+                .sort(([an, a], [bn, b]) => b.observed - a.observed || (an < bn ? -1 : an > bn ? 1 : 0))
+                .map(([name, c]) => `${name} ${c.used}/${c.observed}`);
+            lines.push(`- Tool results used later: ${u.used} of ${u.observed} (${percent(u.used, u.observed)}%)${tools.length ? ` · ${tools.join(" · ")}` : ""}`);
+        }
+        lines.push(`- Not attributable: ${u.unattributed} · pending: ${u.pending} · re-reads: ${u.rereads}${u.stubOnly > 0 ? ` · stub only: ${u.stubOnly}` : ""}`);
+    }
+    lines.push('- Counts cover this process only; "used" is a path heuristic, not a measure of what the model needed.');
+    return lines.join("\n");
+}
+const cell = (text) => text.replace(/[|\r\n]+/g, " ").trim();
+/** The segments a reader needs explained: pinned, elided and low ones. The rest is counted. */
+export const notableSegments = (report) => report.segments.filter((s) => s.criticality === "pinned" || s.criticality === "low" || s.elided);
+/**
+ * `/context` as markdown, for the TUI and the core command catalog. It renders the same
+ * `ContextReport` the web panel and the route show: every elided, pinned and low segment with its
+ * reason, and counts for the rest. Ids, counts and estimates only.
+ */
+export function formatContextReport(report) {
+    if (report.mode === "off")
+        return [
+            "**Context**",
+            "",
+            "- The Context Governor is off, so nothing is measured for this session.",
+            '- Set `context.governor` to `"shadow"` (measure only) or `"on"` (also elide) to see which segments the next request carries and why.',
+        ].join("\n");
+    const reasons = REASONS.filter((r) => report.byReason[r] > 0).map((r) => `${r} ${report.byReason[r]}`);
+    const lines = [
+        "**Context**",
+        "",
+        `- Mode: ${report.mode} · policy v${report.policyVersion}${report.request ? ` · latest request #${report.request}` : ""}`,
+        `- History: ${report.messages} messages · ~${report.tokensBefore} tokens (estimate) -> ~${report.tokensAfter} after the policy (${report.mode === "on" ? "applied" : "measured only, not applied"})`,
+        `- Elided${report.mode === "on" ? "" : " (would be)"}: ${report.elided}${reasons.length ? ` (${reasons.join(", ")})` : ""} · ~${report.tokensSaved} tokens saved (estimate)`,
+    ];
+    const ratios = Object.entries(report.usedRatioByKind).map(([kind, ratio]) => `${kind} ${Math.round((ratio ?? 0) * 100)}%`);
+    if (ratios.length)
+        lines.push(`- Used later: ${ratios.join(" · ")} (path heuristic)`);
+    const inv = report.invariants;
+    const kinds = Object.entries(inv.byKind).map(([kind, n]) => `${kind} ${n}`);
+    lines.push(`- Invariants: ${inv.count}${inv.omitted ? ` (${inv.omitted} omitted)` : ""}${kinds.length ? ` · ${kinds.join(" · ")}` : ""} (counts only)`);
+    const notable = notableSegments(report);
+    if (notable.length) {
+        lines.push("", "| Segment | Kind | Origin | Tokens | Criticality | Decision |", "| --- | --- | --- | --- | --- | --- |");
+        for (const s of notable) {
+            const decision = s.elided
+                ? `${report.mode === "on" ? "elided" : "would elide"}: ${s.elided.reason}${s.elided.replacedBy ? ` (replaced by ${cell(s.elided.replacedBy)})` : ""} · ~${s.elided.tokensSaved} saved`
+                : (s.reason ?? "");
+            lines.push(`| \`${s.id}\` | ${s.kind} | ${cell(s.origin ?? "")}${s.callId ? ` (${cell(s.callId)})` : ""} | ${s.tokens} | ${s.criticality} | ${cell(decision)} |`);
+        }
+    }
+    const rest = report.segments.length - notable.length + (report.segmentsOmitted ?? 0);
+    if (rest > 0)
+        lines.push("", `${rest} more segments are ordinary or recent and not listed.`);
+    lines.push("", 'Token figures are estimates; "used" is a path heuristic for this process.');
+    return lines.join("\n");
+}

package/dist/context/governance.d.ts

@@ -0,0 +1,58 @@
+import type { ContextGovernedData } from "@alisio/sdk";
+import type { Elision, ElisionReason, Projection } from "./elide.ts";
+import type { UsageSummary } from "./usage.ts";
+/** Mode of the Context Governor (spec 012): `off` is inert, `shadow` measures, `on` applies. */
+export type GovernorMode = "off" | "shadow" | "on";
+/** Settings the runner needs; `application.ts` builds them from `config.context`. */
+export interface ContextGovernorOptions {
+    mode: GovernorMode;
+    minAgeTurns: number;
+    epochMessages: number;
+    policyVersion: number;
+    /** Size cap of the `<invariants>` block (`context.invariants.maxChars`); default 4000. */
+    invariantMaxChars?: number;
+}
+/** Counts of the invariants block; never its content (spec 012 D7). */
+export interface InvariantCounts {
+    /** Invariants rendered into the latest request's block. */
+    count: number;
+    /** Length of that block in characters (0 when none was built). */
+    chars: number;
+    /** Invariants left out because they did not fit `maxChars`. */
+    omitted: number;
+    /** Instruction quotes promoted by the compactions of this process (`on` only). */
+    promoted: number;
+    /** Proposed quotes refused by the substring check or the cap (`on` only). */
+    rejected: number;
+}
+/**
+ * What the governor decided for the latest request of a session. Counts, ids and token estimates
+ * only: never file contents, arguments or stub text (spec 012 D7). `governedEventData` turns it
+ * into the `context_governed` event.
+ */
+export interface GovernanceSnapshot {
+    mode: Exclude<GovernorMode, "off">;
+    policyVersion: number;
+    /** 1-based number of the model request inside the current run. */
+    request: number;
+    messages: number;
+    /** Inventory segments of the history (the rule of `buildInventory`, without pinned context). */
+    segments: number;
+    /** Messages `[0, boundary)` were eligible for elision. */
+    boundary: number;
+    elided: number;
+    byReason: Record<ElisionReason, number>;
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    elisions: Array<Pick<Elision, "index" | "callId" | "segmentId" | "reason" | "tokensSaved">>;
+    invariants: InvariantCounts;
+    /** Call ids elided at this request but not at the previous snapshot of the session. */
+    newlyElided: string[];
+}
+export declare function governanceSnapshot(projection: Projection, options: ContextGovernorOptions, request: number, previous?: GovernanceSnapshot): GovernanceSnapshot;
+/**
+ * The `context_governed` payload of one request. Integers, enum keys, tool names and provider call
+ * ids only; bounded (32 ids, 16 tools), so it stays well under 2 KB.
+ */
+export declare function governedEventData(snapshot: GovernanceSnapshot, usage?: UsageSummary): ContextGovernedData;

package/dist/context/governance.js

@@ -0,0 +1,96 @@
+import { countSegments } from "./inventory.js";
+export function governanceSnapshot(projection, options, request, previous) {
+    const byReason = {
+        superseded_read: 0,
+        stale_bg_output: 0,
+        duplicate_search: 0,
+    };
+    for (const e of projection.elisions)
+        byReason[e.reason]++;
+    const before = new Set(previous?.elisions.map((e) => e.callId));
+    return {
+        mode: options.mode === "on" ? "on" : "shadow",
+        policyVersion: options.policyVersion,
+        request,
+        messages: projection.messages.length,
+        segments: countSegments(projection.messages),
+        boundary: projection.boundary,
+        elided: projection.elisions.length,
+        byReason,
+        tokensBefore: projection.tokensBefore,
+        tokensAfter: projection.tokensAfter,
+        tokensSaved: projection.tokensBefore - projection.tokensAfter,
+        elisions: projection.elisions.map(({ index, callId, segmentId, reason, tokensSaved }) => ({
+            index,
+            callId,
+            segmentId,
+            reason,
+            tokensSaved,
+        })),
+        invariants: { count: 0, chars: 0, omitted: 0, promoted: 0, rejected: 0 },
+        newlyElided: projection.elisions.map((e) => e.callId).filter((id) => !before.has(id)),
+    };
+}
+const MAX_EVENT_IDS = 32;
+const MAX_EVENT_TOOLS = 16;
+/**
+ * The `context_governed` payload of one request. Integers, enum keys, tool names and provider call
+ * ids only; bounded (32 ids, 16 tools), so it stays well under 2 KB.
+ */
+export function governedEventData(snapshot, usage) {
+    const { invariants } = snapshot;
+    const omitted = snapshot.newlyElided.length - MAX_EVENT_IDS;
+    const data = {
+        policyVersion: snapshot.policyVersion,
+        mode: snapshot.mode,
+        request: snapshot.request,
+        messages: snapshot.messages,
+        segments: snapshot.segments,
+        elided: snapshot.elided,
+        byReason: { ...snapshot.byReason },
+        tokensBefore: snapshot.tokensBefore,
+        tokensAfter: snapshot.tokensAfter,
+        tokensSaved: snapshot.tokensSaved,
+    };
+    if (snapshot.newlyElided.length > 0)
+        data.elidedCallIds = snapshot.newlyElided.slice(0, MAX_EVENT_IDS);
+    if (omitted > 0)
+        data.elidedCallIdsOmitted = omitted;
+    if (invariants.count > 0 || invariants.chars > 0 || invariants.omitted > 0)
+        data.invariants = {
+            count: invariants.count,
+            chars: invariants.chars,
+            omitted: invariants.omitted,
+        };
+    if (usage) {
+        const byTool = capTools(usage.byTool);
+        data.usage = {
+            observed: usage.observed,
+            used: usage.used,
+            pending: usage.pending,
+            unattributed: usage.unattributed,
+            ...(Object.keys(usage.byKind).length > 0 ? { byKind: usage.byKind } : {}),
+            ...(Object.keys(byTool).length > 0 ? { byTool } : {}),
+        };
+    }
+    return data;
+}
+/** At most `MAX_EVENT_TOOLS` tools: the busiest ones, the rest folded into `other`. */
+function capTools(byTool) {
+    const all = Object.entries(byTool);
+    if (all.length <= MAX_EVENT_TOOLS)
+        return { ...byTool };
+    const ranked = all.sort(([an, a], [bn, b]) => b.observed - a.observed || (an < bn ? -1 : an > bn ? 1 : 0));
+    const out = {};
+    const other = { observed: 0, used: 0 };
+    ranked.forEach(([name, counts], i) => {
+        if (i < MAX_EVENT_TOOLS - 1 && name !== "other")
+            out[name] = { ...counts };
+        else {
+            other.observed += counts.observed;
+            other.used += counts.used;
+        }
+    });
+    out.other = other;
+    return Object.fromEntries(Object.entries(out).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+}

package/dist/context/invariants.d.ts

@@ -0,0 +1,88 @@
+import type { Message } from "@alisio/sdk";
+/**
+ * Context invariants (spec 012, phase 3): the standing context that must survive every
+ * compaction. They are NEVER written into a saved message (the summarizer would paraphrase them,
+ * D4): user instructions live in `sessions.options.contextInvariants` and the rest is read live,
+ * and all of it is rendered into the request as one transient block.
+ */
+export type InvariantKind = "instruction" | "goal" | "plan" | "criterion" | "grant";
+export interface Invariant {
+    kind: InvariantKind;
+    /** Where it came from: `user:<sha8>`, `goal:<id>`, `plan:<id>@<rev>`, `proof:<id>`, `grant:<name>`. */
+    origin: string;
+    text: string;
+}
+export interface InvariantInputs {
+    /** Saved user instructions, oldest first. */
+    instructions: readonly string[];
+    /** Only a goal that is still live (active, paused, blocked or budget limited). */
+    goal?: {
+        goalId: string;
+        objective: string;
+    };
+    /** Only an approved or implementing plan. */
+    plan?: {
+        planId: string;
+        revision: number;
+        hash: string;
+        title: string;
+        artifactId?: string;
+    };
+    /** `undefined` means Proof is not wired: the section does not exist. */
+    criteria?: readonly {
+        criterionId: string;
+        text: string;
+        required: boolean;
+    }[];
+    grants?: {
+        effects: readonly ("write" | "process" | "external")[];
+        capabilities: readonly string[];
+        externalDirectories: number;
+    };
+}
+/** Live material the runner asks for on every request; a missing source leaves its section out. */
+export interface InvariantSources {
+    goal?(sessionId: string): InvariantInputs["goal"];
+    plan?(sessionId: string): InvariantInputs["plan"];
+    criteria?(sessionId: string): InvariantInputs["criteria"];
+    grants?(sessionId: string): {
+        capabilities: readonly string[];
+        externalDirectories: number;
+    } | undefined;
+}
+/** `sessions.options.contextInvariants`: server-owned, written only by compaction. */
+export interface InvariantState {
+    version: 1;
+    instructions: string[];
+    compactions: number;
+    updatedAt: number;
+}
+export declare const INVARIANT_LIMITS: {
+    readonly maxItems: 20;
+    readonly maxItemChars: 500;
+};
+export declare function collectInvariants(input: InvariantInputs): Invariant[];
+/**
+ * The `<invariants>` block, at most `maxChars` long. Items are never cut: they are taken
+ * first-fit in section order, and one that does not fit is skipped and counted.
+ */
+export declare function renderInvariants(list: readonly Invariant[], maxChars: number): {
+    text: string;
+    included: number;
+    omitted: number;
+};
+/** The stored state, or undefined when absent or malformed (old sessions). Never throws. */
+export declare function readInvariantState(options: Record<string, unknown> | undefined): InvariantState | undefined;
+/**
+ * Accepts the summarizer's proposed instruction quotes only when each one is an exact substring
+ * (whitespace collapsed) of a single plain user message that is being summarized. Checkpoints,
+ * assistant text and tool results can never be promoted. A full list keeps the OLDEST items.
+ */
+export declare function promoteInstructions(previous: readonly string[], proposed: unknown, summarized: readonly Message[], limits?: {
+    maxItems: number;
+    maxItemChars: number;
+}): {
+    instructions: string[];
+    accepted: number;
+    rejected: number;
+};