@alisio/core 0.8.0 → 0.10.0

package/dist/context/usage.d.ts

@@ -0,0 +1,96 @@
+import type { ContextSegmentKind, Message } from "@alisio/sdk";
+import { type CallInfo } from "./util.ts";
+/**
+ * Usage ledger of the Context Governor (spec 012 phase 4, section 3.4). It measures, per tool
+ * result, whether the agent later acted on the same file path. The numbers are advisory and
+ * heuristic: they never drive elision, they are never persisted, and they hold no content (only
+ * normalized paths in memory, never in a summary).
+ *
+ * Pure and deterministic: the summary depends only on the sequence of histories handed to `record`
+ * and on the workspace.
+ */
+export interface UsageCounts {
+    observed: number;
+    used: number;
+}
+export interface UsageSummary {
+    /** Attributable results the model saw in full in a request older than the latest one. */
+    observed: number;
+    /** Of those, the ones a later call acted on (same path; re-reads excluded). */
+    used: number;
+    byKind: Partial<Record<ContextSegmentKind, UsageCounts>>;
+    /** Per tool name, keys sorted. */
+    byTool: Record<string, UsageCounts>;
+    /** Results with no path to match (bg_output, web results, writes, errors, shell output...). */
+    unattributed: number;
+    /** Attributable results seen only in the latest request: not decidable yet. */
+    pending: number;
+    /** Results the model only ever saw as an elision stub (`on` mode). */
+    stubOnly: number;
+    /** Calls that re-read a path whose earlier read is still in the ledger. */
+    rereads: number;
+    /** Entries dropped by the size cap. */
+    evicted: number;
+}
+export interface UsageLedgerOptions {
+    workspace: string;
+    /** Entries kept (default 4096); the oldest are evicted first. */
+    maxEntries?: number;
+    /** Keys kept per entry (default 32). */
+    maxKeysPerEntry?: number;
+    /** Paths a tool declares for an input (`ToolDefinition.paths`); may throw. */
+    pathsOf?: (tool: string, args: Record<string, unknown>) => string[] | undefined;
+    /** Whether a tool is side-effect free: only those results can be attributed by declared paths. */
+    isRead?: (tool: string) => boolean;
+}
+export declare const usedRatio: (c: UsageCounts) => number | undefined;
+/** POSIX-normalized, workspace-relative when inside it, no `./`, no trailing `/`, case kept. */
+export declare function normalizePath(path: string, workspace: string): string;
+type PathsOf = UsageLedgerOptions["pathsOf"];
+/**
+ * Keys that identify what a tool result is about, or undefined when it cannot be attributed.
+ * `read_file`: its path. `list_files`: the listed files. `search_text`: the paths of the ripgrep
+ * `match` lines (the `path` argument, often ".", is ignored). Other tools only through `isRead`
+ * plus their declared `paths` (done by the ledger).
+ */
+export declare function attributionKeys(call: CallInfo, text: string, workspace: string, pathsOf?: PathsOf, maxKeys?: number): string[] | undefined;
+/** What a later call names: its `path` argument, its declared paths and, for processes, the command. */
+export declare function referencedPaths(call: CallInfo, workspace: string, pathsOf?: PathsOf): {
+    paths: string[];
+    command?: string;
+};
+export declare class UsageLedger {
+    private readonly workspace;
+    private readonly maxEntries;
+    private readonly maxKeys;
+    private readonly pathsOf;
+    private readonly isRead;
+    /** Insertion order is eviction order. */
+    private readonly entries;
+    /** key -> call ids of the entries that carry it. */
+    private readonly index;
+    private readonly retired;
+    private seenCalls;
+    private latest;
+    private reread;
+    private evictedCount;
+    constructor(options: UsageLedgerOptions);
+    /** Number of seams recorded; the runner numbers the next one `seams + 1`. */
+    get seams(): number;
+    /**
+     * Feeds the history of one model request. `request` must grow on every call; `stubbed` holds the
+     * call ids whose result the model got as an elision stub in this request.
+     */
+    record(request: number, history: Message[], stubbed: ReadonlySet<string>): void;
+    private add;
+    private drop;
+    private credit;
+    /**
+     * Whether a later call acted on the result of `callId`: `true` or `false` once the result is
+     * decidable, `undefined` when it cannot be (unknown, not attributable, only seen as a stub, or
+     * seen only in the latest request).
+     */
+    decided(callId: string): boolean | undefined;
+    summary(): UsageSummary;
+}
+export {};

package/dist/context/usage.js

@@ -0,0 +1,264 @@
+import { posix } from "node:path";
+import { describeCall, parseObject, resultText } from "./util.js";
+export const usedRatio = (c) => c.observed ? c.used / c.observed : undefined;
+const DEFAULT_MAX_ENTRIES = 4096;
+const DEFAULT_MAX_KEYS = 32;
+/** POSIX-normalized, workspace-relative when inside it, no `./`, no trailing `/`, case kept. */
+export function normalizePath(path, workspace) {
+    let p = posix.normalize(path);
+    const ws = posix.normalize(workspace).replace(/\/+$/, "");
+    if (ws && p === ws)
+        return ".";
+    if (ws && p.startsWith(`${ws}/`))
+        p = p.slice(ws.length + 1);
+    if (p.length > 1 && p.endsWith("/"))
+        p = p.slice(0, -1);
+    return p;
+}
+function declaredPaths(call, pathsOf) {
+    if (!call.args || !pathsOf)
+        return [];
+    try {
+        return (pathsOf(call.name, call.args) ?? []).filter((p) => typeof p === "string");
+    }
+    catch {
+        return [];
+    }
+}
+const unique = (items, max) => [...new Set(items)].slice(0, max);
+/**
+ * Keys that identify what a tool result is about, or undefined when it cannot be attributed.
+ * `read_file`: its path. `list_files`: the listed files. `search_text`: the paths of the ripgrep
+ * `match` lines (the `path` argument, often ".", is ignored). Other tools only through `isRead`
+ * plus their declared `paths` (done by the ledger).
+ */
+export function attributionKeys(call, text, workspace, pathsOf, maxKeys = DEFAULT_MAX_KEYS) {
+    let found = [];
+    if (call.name === "read_file") {
+        if (typeof call.args?.path === "string")
+            found = [call.args.path];
+    }
+    else if (call.name === "list_files") {
+        const files = parseObject(text)?.files;
+        if (Array.isArray(files))
+            found = files.filter((f) => typeof f === "string");
+    }
+    else if (call.name === "search_text") {
+        const stdout = parseObject(text)?.stdout;
+        if (typeof stdout === "string") {
+            for (const line of stdout.split("\n")) {
+                if (!line.includes('"match"'))
+                    continue;
+                const event = parseObject(line);
+                const data = event?.type === "match" ? event.data : undefined;
+                if (typeof data?.path?.text === "string")
+                    found.push(data.path.text);
+            }
+        }
+    }
+    else {
+        found = declaredPaths(call, pathsOf);
+    }
+    const keys = unique(found.map((p) => normalizePath(p, workspace)), maxKeys);
+    return keys.length > 0 ? keys : undefined;
+}
+/** What a later call names: its `path` argument, its declared paths and, for processes, the command. */
+export function referencedPaths(call, workspace, pathsOf) {
+    const raw = [...(typeof call.args?.path === "string" ? [call.args.path] : [])];
+    raw.push(...declaredPaths(call, pathsOf));
+    const paths = unique(raw.map((p) => normalizePath(p, workspace)), DEFAULT_MAX_KEYS);
+    if (call.name !== "run_process" && call.name !== "shell")
+        return { paths };
+    const args = call.args?.args;
+    const command = [
+        typeof call.args?.command === "string" ? call.args.command : "",
+        ...(Array.isArray(args) ? args.filter((a) => typeof a === "string") : []),
+    ]
+        .filter(Boolean)
+        .join(" ");
+    return { paths, ...(command ? { command } : {}) };
+}
+const escapeRegExp = (s) => s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+/** Heuristic: the key as a whole word of the command, delimited by whitespace, quotes and `=:(),;`. */
+const inCommand = (command, key) => command.includes(key) &&
+    new RegExp(`(^|[\\s"'=:(])${escapeRegExp(key)}($|[\\s"'):,;])`).test(command);
+export class UsageLedger {
+    workspace;
+    maxEntries;
+    maxKeys;
+    pathsOf;
+    isRead;
+    /** Insertion order is eviction order. */
+    entries = new Map();
+    /** key -> call ids of the entries that carry it. */
+    index = new Map();
+    retired = new Set();
+    seenCalls = new Set();
+    latest = 0;
+    reread = 0;
+    evictedCount = 0;
+    constructor(options) {
+        this.workspace = options.workspace;
+        this.maxEntries = Math.max(1, options.maxEntries ?? DEFAULT_MAX_ENTRIES);
+        this.maxKeys = Math.max(1, options.maxKeysPerEntry ?? DEFAULT_MAX_KEYS);
+        this.pathsOf = options.pathsOf;
+        this.isRead = options.isRead ?? (() => true);
+    }
+    /** Number of seams recorded; the runner numbers the next one `seams + 1`. */
+    get seams() {
+        return this.latest;
+    }
+    /**
+     * Feeds the history of one model request. `request` must grow on every call; `stubbed` holds the
+     * call ids whose result the model got as an elision stub in this request.
+     */
+    record(request, history, stubbed) {
+        this.latest = Math.max(this.latest, request);
+        const calls = new Map();
+        const fresh = [];
+        const results = [];
+        for (const m of history) {
+            if (m.role === "assistant") {
+                for (const c of m.calls) {
+                    const info = describeCall(c.name, c.arguments);
+                    calls.set(c.id, info);
+                    if (!this.seenCalls.has(c.id))
+                        fresh.push({ id: c.id, call: info });
+                }
+            }
+            else if (m.role === "tool")
+                results.push(m);
+        }
+        // (1) Credit the calls that are new at this seam against what was observed before it.
+        for (const { id, call } of fresh)
+            this.credit(id, call, request);
+        this.seenCalls = new Set(calls.keys());
+        // (2) Add the results not seen yet.
+        for (const m of results) {
+            if (this.entries.has(m.callId) || this.retired.has(m.callId))
+                continue;
+            const call = calls.get(m.callId);
+            const isError = m.result.isError === true;
+            let keys;
+            if (call && !isError && (this.isRead(call.name) || call.name === "read_file"))
+                keys = attributionKeys(call, resultText(m), this.workspace, this.pathsOf, this.maxKeys);
+            this.add({
+                callId: m.callId,
+                tool: call?.name ?? "tool",
+                observedAt: request,
+                stubOnly: stubbed.has(m.callId),
+                keys: keys ?? [],
+                used: false,
+            });
+        }
+    }
+    add(entry) {
+        this.entries.set(entry.callId, entry);
+        for (const key of entry.keys) {
+            const ids = this.index.get(key) ?? new Set();
+            ids.add(entry.callId);
+            this.index.set(key, ids);
+        }
+        while (this.entries.size > this.maxEntries) {
+            const oldest = this.entries.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.drop(oldest);
+            this.evictedCount++;
+        }
+    }
+    drop(callId) {
+        const entry = this.entries.get(callId);
+        if (!entry)
+            return;
+        this.entries.delete(callId);
+        for (const key of entry.keys) {
+            const ids = this.index.get(key);
+            ids?.delete(callId);
+            if (ids?.size === 0)
+                this.index.delete(key);
+        }
+        this.retired.add(callId);
+        if (this.retired.size > this.maxEntries) {
+            const first = this.retired.values().next().value;
+            if (first !== undefined)
+                this.retired.delete(first);
+        }
+    }
+    credit(callId, call, request) {
+        const { paths, command } = referencedPaths(call, this.workspace, this.pathsOf);
+        const hit = new Set();
+        for (const path of paths)
+            for (const id of this.index.get(path) ?? [])
+                hit.add(id);
+        if (command)
+            for (const [key, ids] of this.index) {
+                if (inCommand(command, key) || inCommand(command, `${this.workspace}/${key}`))
+                    for (const id of ids)
+                        hit.add(id);
+            }
+        let counted = false;
+        for (const id of hit) {
+            const entry = this.entries.get(id);
+            if (!entry || entry.observedAt >= request || entry.callId === callId || entry.stubOnly)
+                continue;
+            if (call.name === "read_file" && entry.tool === "read_file") {
+                // A re-read of the same path is the model checking again, not acting on it.
+                counted ||= true;
+                continue;
+            }
+            entry.used = true;
+        }
+        if (counted)
+            this.reread++;
+    }
+    /**
+     * Whether a later call acted on the result of `callId`: `true` or `false` once the result is
+     * decidable, `undefined` when it cannot be (unknown, not attributable, only seen as a stub, or
+     * seen only in the latest request).
+     */
+    decided(callId) {
+        const e = this.entries.get(callId);
+        if (!e || e.stubOnly || e.keys.length === 0 || e.observedAt >= this.latest)
+            return undefined;
+        return e.used;
+    }
+    summary() {
+        const byTool = new Map();
+        let observed = 0;
+        let used = 0;
+        let unattributed = 0;
+        let pending = 0;
+        let stubOnly = 0;
+        for (const e of this.entries.values()) {
+            if (e.stubOnly)
+                stubOnly++;
+            else if (e.keys.length === 0)
+                unattributed++;
+            else if (e.observedAt >= this.latest)
+                pending++;
+            else {
+                const counts = byTool.get(e.tool) ?? { observed: 0, used: 0 };
+                counts.observed++;
+                observed++;
+                if (e.used) {
+                    counts.used++;
+                    used++;
+                }
+                byTool.set(e.tool, counts);
+            }
+        }
+        const sorted = [...byTool].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+        return {
+            observed,
+            used,
+            byKind: observed > 0 || pending > 0 ? { tool_result: { observed, used } } : {},
+            byTool: Object.fromEntries(sorted),
+            unattributed,
+            pending,
+            stubOnly,
+            rereads: this.reread,
+            evicted: this.evictedCount,
+        };
+    }
+}

package/dist/context/util.d.ts

@@ -0,0 +1,22 @@
+import type { Message } from "@alisio/sdk";
+/** Tools whose `path` argument names the file the call reads or changes. */
+export declare const PATH_TOOLS: Set<string>;
+export declare const WRITE_TOOLS: Set<string>;
+export declare const sha: (text: string) => string;
+/** Stable 12-hex id of a segment: kind, call id or position, and a hash of its content. */
+export declare const segmentId: (kind: string, key: string | number, content: string) => string;
+export declare function parseObject(text: string): Record<string, unknown> | undefined;
+/** Key-order independent serialization, so equal arguments compare equal. */
+export declare function stableStringify(value: unknown): string;
+/** Text parts of a tool result joined with newlines (what the model sees). */
+export declare const resultText: (m: Extract<Message, {
+    role: "tool";
+}>) => string;
+export interface CallInfo {
+    name: string;
+    arguments: string;
+    /** Parsed JSON arguments when they form an object, else undefined. */
+    args?: Record<string, unknown>;
+    path?: string;
+}
+export declare function describeCall(name: string, argumentsText: string): CallInfo;

package/dist/context/util.js

@@ -0,0 +1,36 @@
+import { createHash } from "node:crypto";
+/** Tools whose `path` argument names the file the call reads or changes. */
+export const PATH_TOOLS = new Set(["read_file", "write_file", "edit_file"]);
+export const WRITE_TOOLS = new Set(["write_file", "edit_file"]);
+export const sha = (text) => createHash("sha256").update(text).digest("hex");
+/** Stable 12-hex id of a segment: kind, call id or position, and a hash of its content. */
+export const segmentId = (kind, key, content) => sha(`${kind}\0${key}\0${sha(content)}`).slice(0, 12);
+export function parseObject(text) {
+    try {
+        const value = JSON.parse(text);
+        return value && typeof value === "object" && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Key-order independent serialization, so equal arguments compare equal. */
+export function stableStringify(value) {
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(",")}]`;
+    if (value && typeof value === "object")
+        return `{${Object.entries(value)
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([k, v]) => `${JSON.stringify(k)}:${stableStringify(v)}`)
+            .join(",")}}`;
+    return JSON.stringify(value) ?? "null";
+}
+/** Text parts of a tool result joined with newlines (what the model sees). */
+export const resultText = (m) => m.result.content.map((p) => (p.type === "text" ? p.text : "")).join("\n");
+export function describeCall(name, argumentsText) {
+    const args = parseObject(argumentsText);
+    const path = PATH_TOOLS.has(name) && typeof args?.path === "string" ? args.path : undefined;
+    return { name, arguments: argumentsText, ...(args ? { args } : {}), ...(path ? { path } : {}) };
+}

package/dist/core/compaction.d.ts

@@ -103,8 +103,13 @@ export declare function reduceMessagesToBudget(messages: Message[], targetChars:
  */
 export declare function serializeForSummary(messages: Message[], maxItemChars?: number): string;
 export declare function renderCheckpoint(c: CompactionCheckpoint): string;
-/** Summarizer instructions: JSON checkpoint plus any extension-requested fields. */
-export declare function checkpointInstructions(extraInstructions?: string[], fields?: Record<string, string>): string;
+/** Top-level field the governed summarizer fills with verbatim user quotes (spec 012, phase 3). */
+export declare const INVARIANTS_FIELD = "alisio_invariants";
+/**
+ * Summarizer instructions: JSON checkpoint plus any extension-requested fields. `governed` (the
+ * Context Governor in `on` mode) asks for one more field; without it the text is unchanged.
+ */
+export declare function checkpointInstructions(extraInstructions?: string[], fields?: Record<string, string>, governed?: boolean): string;
 export interface CheckpointOutput {
     structured: boolean;
     checkpoint?: CompactionCheckpoint;

package/dist/core/compaction.js

@@ -306,9 +306,15 @@ export function renderCheckpoint(c) {
         section("Relevant files", c.relevantFiles),
     ].join("\n\n");
 }
-/** Summarizer instructions: JSON checkpoint plus any extension-requested fields. */
-export function checkpointInstructions(extraInstructions = [], fields = {}) {
-    const extra = Object.entries(fields)
+/** Top-level field the governed summarizer fills with verbatim user quotes (spec 012, phase 3). */
+export const INVARIANTS_FIELD = "alisio_invariants";
+const INVARIANTS_ASK = `array of strings: verbatim quotes (exact substrings) of USER messages that state durable instructions or constraints; never paraphrase; [] if none`;
+/**
+ * Summarizer instructions: JSON checkpoint plus any extension-requested fields. `governed` (the
+ * Context Governor in `on` mode) asks for one more field; without it the text is unchanged.
+ */
+export function checkpointInstructions(extraInstructions = [], fields = {}, governed = false) {
+    const extra = Object.entries(governed ? { ...fields, [INVARIANTS_FIELD]: INVARIANTS_ASK } : fields)
         .map(([name, description]) => `,\n "${name}": ${description}`)
         .join("");
     return [

package/dist/core/contracts.d.ts

@@ -177,6 +177,14 @@ export interface SessionStore {
     eventsPage?(session: string, options?: PageOptions): EventPage;
     /** Marks queued/running runs whose owner process is not alive as interrupted. */
     interruptRuns?(): number;
+    /**
+     * Atomic read-modify-write of the session's `options` (`SQLiteStore` implements it). Without it
+     * the runner keeps what it would store there, for the context invariants, in memory.
+     */
+    mutateSessionOptions?<T>(id: string, change: (current: Record<string, unknown>) => {
+        patch?: Record<string, unknown>;
+        value: T;
+    }): T;
 }
 export interface ContextSource {
     /** System instructions; `sessionId` scopes lazily attached nested instructions. */

package/dist/core/runner.d.ts

@@ -1,4 +1,7 @@
 import { type Attachment, type DatasetRef, type Message, type ModelProvider, type RunEvent, type ToolDefinition, type ToolResult } from "@alisio/sdk";
+import { type ContextGovernorOptions, type GovernanceSnapshot } from "../context/governance.ts";
+import { type Invariant, type InvariantSources } from "../context/invariants.ts";
+import { UsageLedger, type UsageSummary } from "../context/usage.ts";
 import type { ProofRecorder } from "../proof/recorder.ts";
 import type { PathAccess } from "../runtime/access.ts";
 import type { ApprovalHandler, ArtifactPublisherFactory, CapabilityGate, ContextSource, DecisionsFactory, Policy, RunnerExtensions, SessionStore } from "./contracts.ts";
@@ -62,6 +65,17 @@ export interface RunnerOptions {
      *  unknown (or absurdly large, see `MAX_TRUSTED_WINDOW`) the char budget falls back. */
     contextWindow?: (model: string) => number | undefined;
     compaction?: CompactionSettings;
+    /**
+     * Context Governor (spec 012). Unset or `mode: "off"` changes nothing. `shadow` computes what
+     * would be elided and keeps it in `governance()` while the request stays byte-identical; `on`
+     * sends the projected history. Compaction, limits and persistence always use the raw history.
+     */
+    contextGovernor?: ContextGovernorOptions;
+    /**
+     * Live sources of the `<invariants>` block (goal, plan, Proof criteria, grants). Only read when
+     * the governor is `shadow` or `on`; a missing source leaves its section out.
+     */
+    invariantSources?: InvariantSources;
     /** When set, write/process tools not allowed by the policy are offered and ask first. */
     approve?: ApprovalHandler;
     /**
@@ -194,6 +208,16 @@ export declare class AgentRunner {
     private reported;
     /** Conversation size in characters right after the last automatic compaction, per session. */
     private compactedChars;
+    /** What the Context Governor decided for the latest request of each session (shadow and on). */
+    private governed;
+    /** Usage ledger per session (shadow and on; process-local, LRU of `USAGE_LEDGER_SESSIONS`). */
+    private usage;
+    /** Effects the user approved for the whole session, per session (`on` mode; process-local). */
+    private sessionEffects;
+    /** Instruction quotes of a session whose store cannot keep session options (process-local). */
+    private invariantMemory;
+    /** Quotes promoted and refused by the compactions of this process, per session. */
+    private promotions;
     /** Where human waits are opened; the clocks of the active runs listen to it. */
     readonly humanWaits: HumanWaits;
     constructor(options: RunnerOptions);
@@ -262,6 +286,49 @@ export declare class AgentRunner {
     }>;
     /** The output-token budget for `model`: user value, else catalog maximum, else fallback. */
     private outputLimit;
+    /** Latest Context Governor decision for a session (core-internal; counts and ids only). */
+    governance(sessionId: string): GovernanceSnapshot | undefined;
+    /**
+     * Heuristic usage of the tool results this process showed the model in a session (shadow and on
+     * only; undefined otherwise). Lost on restart; advisory, it never drives elision.
+     */
+    contextUsage(sessionId: string): UsageSummary | undefined;
+    private usageLedger;
+    /**
+     * Forgets the user instructions kept for a session: the stored `contextInvariants` and every
+     * in-memory entry. Core-internal; there is no per-item removal before phase 5.
+     */
+    clearInvariants(sessionId: string): void;
+    /** The stored instruction list of a session, or undefined for old or never-compacted sessions. */
+    private invariantState;
+    /**
+     * The `<invariants>` block for the next request of a session: empty before the first compaction
+     * (a history that starts with a checkpoint, or a stored compaction count). Built fresh from the
+     * stored instructions and the live sources, never saved.
+     */
+    private invariantBlock;
+    /** The collected invariants, or undefined before the first compaction (see `invariantBlock`). */
+    private invariantList;
+    /**
+     * What the `ContextReport` of a session is built from (spec 012 phase 5): the governor settings,
+     * the active history, the invariants of the next request and the in-memory usage ledger. Read
+     * only. `off` and runners without a governor return no history, because `off` measures nothing.
+     */
+    contextInputs(sessionId: string): {
+        governor: ContextGovernorOptions;
+        messages: Message[];
+        invariants: {
+            items: Array<{
+                kind: Invariant["kind"];
+                text: string;
+            }>;
+            omitted: number;
+        };
+        ledger?: UsageLedger;
+        governance?: GovernanceSnapshot;
+    } | undefined;
+    /** Keeps the user's verbatim quotes the summarizer proposed (see `promoteInstructions`). */
+    private promoteInvariants;
     /** Change the model used by subsequent turns of a session; recorded in the store. */
     setModel(sessionId: string, model: string): void;
     /** Manually compact a session outside a run. */