@alisio/core 0.8.0 → 0.10.0

package/dist/core/runner.js

@@ -1,9 +1,13 @@
 import { isEphemeralRunEventType, textProjection, textResult, } from "@alisio/sdk";
+import { projectContext } from "../context/elide.js";
+import { governanceSnapshot, governedEventData, } from "../context/governance.js";
+import { collectInvariants, promoteInstructions, readInvariantState, renderInvariants, } from "../context/invariants.js";
+import { UsageLedger } from "../context/usage.js";
 import { createNestedDispatcher } from "../forge/nested.js";
 import { hasScratchEstimator, scratchIncomingBytes } from "../forge/scratch-quota.js";
 import { decideEffect, effectAskable } from "../permissions/decide.js";
 import { bindCallInternals } from "./call-internals.js";
-import { checkpointInstructions, estimateTokens, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
+import { checkpointInstructions, estimateTokens, INVARIANTS_FIELD, MAX_TRUSTED_WINDOW, parseCheckpointOutput, planCompaction, reduceMessagesToBudget, shouldCompactContext, summarize, summaryMessage, } from "./compaction.js";
 import { HumanWaits } from "./human-wait.js";
 import { EXIT_PLAN_TOOL, optInAllows } from "./opt-in.js";
 import { resolveMaxOutputTokens } from "./output-limit.js";
@@ -52,8 +56,12 @@ const MIN_MESSAGE_BUDGET_FLOOR = 4_000;
  * would pay for a summarizer call. The hard-limit last-chance compaction ignores it.
  */
 const RECOMPACT_GROWTH_MARGIN = 0.1;
+/** Sessions whose usage ledger one runner keeps in memory (least recently used go first). */
+const USAGE_LEDGER_SESSIONS = 64;
 /** First 40 lines of a script input, for capability approvals. */
 const scriptPreview = (input) => typeof input.code === "string" ? input.code.split(/\r?\n/).slice(0, 40).join("\n") : undefined;
+/** `{ [key]: value }`, or nothing when there is no value (optional properties stay absent). */
+const optional = (key, value) => (value === undefined ? {} : { [key]: value });
 /** A short id for a tool call the user started from a UI (alphanumeric, 9 characters). */
 const uiCallId = () => {
     const alphabet = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
@@ -70,6 +78,16 @@ export class AgentRunner {
     reported = new Map();
     /** Conversation size in characters right after the last automatic compaction, per session. */
     compactedChars = new Map();
+    /** What the Context Governor decided for the latest request of each session (shadow and on). */
+    governed = new Map();
+    /** Usage ledger per session (shadow and on; process-local, LRU of `USAGE_LEDGER_SESSIONS`). */
+    usage = new Map();
+    /** Effects the user approved for the whole session, per session (`on` mode; process-local). */
+    sessionEffects = new Map();
+    /** Instruction quotes of a session whose store cannot keep session options (process-local). */
+    invariantMemory = new Map();
+    /** Quotes promoted and refused by the compactions of this process, per session. */
+    promotions = new Map();
     /** Where human waits are opened; the clocks of the active runs listen to it. */
     humanWaits;
     constructor(options) {
@@ -267,6 +285,173 @@ export class AgentRunner {
             fallback: o.fallbackMaxOutputTokens ?? 4096,
         });
     }
+    /** Latest Context Governor decision for a session (core-internal; counts and ids only). */
+    governance(sessionId) {
+        return this.governed.get(sessionId);
+    }
+    /**
+     * 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) {
+        return this.usage.get(sessionId)?.summary();
+    }
+    usageLedger(sessionId, workspace) {
+        let ledger = this.usage.get(sessionId);
+        if (ledger)
+            this.usage.delete(sessionId);
+        else {
+            const registry = this.options.registry;
+            ledger = new UsageLedger({
+                workspace,
+                pathsOf: (tool, args) => {
+                    try {
+                        return registry.get(tool).paths?.(args);
+                    }
+                    catch {
+                        return undefined;
+                    }
+                },
+                isRead: (tool) => {
+                    try {
+                        return registry.get(tool).effect === "read";
+                    }
+                    catch {
+                        return false;
+                    }
+                },
+            });
+        }
+        this.usage.set(sessionId, ledger);
+        while (this.usage.size > USAGE_LEDGER_SESSIONS) {
+            const oldest = this.usage.keys().next().value;
+            if (oldest === undefined)
+                break;
+            this.usage.delete(oldest);
+        }
+        return ledger;
+    }
+    /**
+     * 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) {
+        this.invariantMemory.delete(sessionId);
+        this.usage.delete(sessionId);
+        this.sessionEffects.delete(sessionId);
+        this.promotions.delete(sessionId);
+        this.options.store.mutateSessionOptions?.(sessionId, (current) => ({
+            ...("contextInvariants" in current ? { patch: { contextInvariants: undefined } } : {}),
+            value: undefined,
+        }));
+    }
+    /** The stored instruction list of a session, or undefined for old or never-compacted sessions. */
+    invariantState(sessionId) {
+        const store = this.options.store;
+        return store.mutateSessionOptions
+            ? readInvariantState(store.get(sessionId).options)
+            : this.invariantMemory.get(sessionId);
+    }
+    /**
+     * 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.
+     */
+    invariantBlock(sessionId, messages, maxChars) {
+        const list = this.invariantList(sessionId, messages);
+        return list ? renderInvariants(list, maxChars) : { text: "", included: 0, omitted: 0 };
+    }
+    /** The collected invariants, or undefined before the first compaction (see `invariantBlock`). */
+    invariantList(sessionId, messages) {
+        const state = this.invariantState(sessionId);
+        const first = messages[0];
+        const compacted = (state?.compactions ?? 0) > 0 ||
+            (first?.role === "user" && !!first.summary && first.text.startsWith("[Checkpoint of"));
+        if (!compacted)
+            return undefined;
+        const sources = this.options.invariantSources;
+        // A broken source never stops a request: its section is simply left out.
+        const read = (source) => {
+            try {
+                return source?.();
+            }
+            catch {
+                return undefined;
+            }
+        };
+        const grants = read(sources?.grants?.bind(sources, sessionId));
+        const effects = [...(this.sessionEffects.get(sessionId) ?? [])];
+        return collectInvariants({
+            instructions: state?.instructions ?? [],
+            ...optional("goal", read(sources?.goal?.bind(sources, sessionId))),
+            ...optional("plan", read(sources?.plan?.bind(sources, sessionId))),
+            ...optional("criteria", read(sources?.criteria?.bind(sources, sessionId))),
+            ...(grants || effects.length
+                ? {
+                    grants: {
+                        effects,
+                        capabilities: grants?.capabilities ?? [],
+                        externalDirectories: grants?.externalDirectories ?? 0,
+                    },
+                }
+                : {}),
+        });
+    }
+    /**
+     * 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) {
+        const governor = this.options.contextGovernor;
+        if (!governor)
+            return undefined;
+        if (governor.mode === "off")
+            return { governor, messages: [], invariants: { items: [], omitted: 0 } };
+        const messages = this.options.store.messages(sessionId);
+        const list = this.invariantList(sessionId, messages) ?? [];
+        const omitted = list.length
+            ? renderInvariants(list, governor.invariantMaxChars ?? 4000).omitted
+            : 0;
+        const ledger = this.usage.get(sessionId);
+        const governance = this.governed.get(sessionId);
+        return {
+            governor,
+            messages,
+            invariants: { items: list.map((i) => ({ kind: i.kind, text: i.text })), omitted },
+            ...(ledger ? { ledger } : {}),
+            ...(governance ? { governance } : {}),
+        };
+    }
+    /** Keeps the user's verbatim quotes the summarizer proposed (see `promoteInstructions`). */
+    promoteInvariants(sessionId, proposed, summarized) {
+        const store = this.options.store;
+        const apply = (state) => {
+            const out = promoteInstructions(state?.instructions ?? [], proposed, summarized);
+            const next = {
+                version: 1,
+                instructions: out.instructions,
+                compactions: (state?.compactions ?? 0) + 1,
+                updatedAt: Date.now(),
+            };
+            return { next, out };
+        };
+        const { out } = store.mutateSessionOptions
+            ? store.mutateSessionOptions(sessionId, (current) => {
+                const result = apply(readInvariantState(current));
+                return { patch: { contextInvariants: result.next }, value: result };
+            })
+            : (() => {
+                const result = apply(this.invariantMemory.get(sessionId));
+                this.invariantMemory.set(sessionId, result.next);
+                return result;
+            })();
+        const total = this.promotions.get(sessionId) ?? { promoted: 0, rejected: 0 };
+        this.promotions.set(sessionId, {
+            promoted: total.promoted + out.accepted,
+            rejected: total.rejected + out.rejected,
+        });
+    }
     /** Change the model used by subsequent turns of a session; recorded in the store. */
     setModel(sessionId, model) {
         const id = model.trim();
@@ -277,6 +462,7 @@ export class AgentRunner {
             return;
         this.options.store.setModel(sessionId, id);
         this.reported.delete(sessionId);
+        this.governed.delete(sessionId);
         this.emitter(sessionId)("model_changed", { model: id, previous });
     }
     /** Manually compact a session outside a run. */
@@ -337,10 +523,14 @@ export class AgentRunner {
                     });
                 }
             reportFailures(contribution.failures);
-            const fields = Object.fromEntries(Object.entries(contribution.fields).map(([name, f]) => [name, f.description]));
+            // Only `on` asks the summarizer for verbatim quotes; a plugin field of the same name is ignored.
+            const govern = o.contextGovernor?.mode === "on";
+            const fields = Object.fromEntries(Object.entries(contribution.fields)
+                .filter(([name]) => !(govern && name === INVARIANTS_FIELD))
+                .map(([name, f]) => [name, f.description]));
             const provider = await (o.providerFor?.(o.store.get(sessionId)) ?? o.provider);
             const { text: raw, truncated: summaryTruncated } = await summarize(provider, {
-                instructions: checkpointInstructions(contribution.instructions, fields),
+                instructions: checkpointInstructions(contribution.instructions, fields, govern),
                 messages: plan.summarized,
                 focus,
                 model,
@@ -348,7 +538,9 @@ export class AgentRunner {
                 signal,
                 sessionId,
             });
-            const output = parseCheckpointOutput(raw, Object.keys(fields));
+            const parsed = parseCheckpointOutput(raw, govern ? [...Object.keys(fields), INVARIANTS_FIELD] : Object.keys(fields));
+            const { [INVARIANTS_FIELD]: proposed, ...extracted } = parsed.extracted;
+            const output = govern ? { ...parsed, extracted } : parsed;
             let after = {
                 inject: [],
                 reports: {},
@@ -374,8 +566,12 @@ export class AgentRunner {
                 .filter((x) => x.trim())
                 .join("\n\n");
             const summary = summaryMessage(body, plan.cut);
+            // Before the history is replaced: if the process dies in between, the next compaction dedupes.
+            if (govern)
+                this.promoteInvariants(sessionId, proposed, plan.summarized);
             o.store.compact(sessionId, plan.cut, summary);
             this.reported.delete(sessionId);
+            this.governed.delete(sessionId);
             const afterTokens = await this.estimateContext(sessionId);
             emit("compaction_completed", {
                 reason,
@@ -568,8 +764,14 @@ export class AgentRunner {
                 if (decision === "deny")
                     throw new Error(`Capability ${capability ?? effect} denied by the user for this call`);
                 // A capability grant never widens the effect: only effect approvals do.
-                if (decision === "session" && !capability)
+                if (decision === "session" && !capability) {
                     policy[effect] = true;
+                    if (o.contextGovernor?.mode === "on" &&
+                        (effect === "write" || effect === "process" || effect === "external")) {
+                        const effects = this.sessionEffects.get(sessionId) ?? new Set();
+                        this.sessionEffects.set(sessionId, effects.add(effect));
+                    }
+                }
             }
             o.store.beginCall(sessionId, call, { runId, effect });
             const publisher = o.artifacts?.({ sessionId, runId, callId: call.id }, (published) => emit("artifact_published", {
@@ -1009,7 +1211,20 @@ export class AgentRunner {
                 let messages = o.store.messages(sessionId);
                 const tools = this.availableTools(options, sessionId);
                 const toolsText = this.toolsText(tools);
-                const chars = () => instructions.length + JSON.stringify(messages).length + toolsText.length;
+                // The `<invariants>` block (`on` only) is part of every request after the first compaction,
+                // so it counts like instructions. Built once per history; shadow measures it at the seam.
+                const maxInvariantChars = o.contextGovernor?.invariantMaxChars ?? 4000;
+                let invariantMemo;
+                const invariants = () => {
+                    if (invariantMemo?.for !== messages)
+                        invariantMemo = {
+                            for: messages,
+                            value: this.invariantBlock(sessionId, messages, maxInvariantChars),
+                        };
+                    return invariantMemo.value;
+                };
+                const blockChars = () => (o.contextGovernor?.mode === "on" ? invariants().text.length : 0);
+                const chars = () => instructions.length + blockChars() + JSON.stringify(messages).length + toolsText.length;
                 // REDUCIBLE content only (instructions + transcript). The fixed tool catalog
                 // (`toolsText`) is a deployment reality — a huge MCP catalog with dozens of tools is
                 // part of every request regardless of history, so it is deliberately excluded from the
@@ -1017,7 +1232,7 @@ export class AgentRunner {
                 // and still fake-fail. Oversized catalogs are a `/plugins` decision, not session growth;
                 // auto-compaction above still measures the FULL request (`chars()`), because window
                 // thresholds protect what the model really sees, tools included.
-                const charsConversation = () => instructions.length + JSON.stringify(messages).length;
+                const charsConversation = () => instructions.length + blockChars() + JSON.stringify(messages).length;
                 const used = () => {
                     const last = this.reported.get(sessionId);
                     return last && last.count <= messages.length
@@ -1060,12 +1275,17 @@ export class AgentRunner {
                 // limit) the run fails with an actionable error.
                 if (charsConversation() > limit) {
                     const reduceInPlace = () => {
-                        const targetChars = Math.max(MIN_MESSAGE_BUDGET_FLOOR, limit - instructions.length);
+                        const targetChars = Math.max(MIN_MESSAGE_BUDGET_FLOOR, limit - instructions.length - blockChars());
                         const reduction = reduceMessagesToBudget(messages, targetChars);
                         if (reduction.truncated > 0) {
                             o.store.overwrite(sessionId, reduction.messages);
+                            const tokensSaved = Math.max(0, estimateTokens(messages) - estimateTokens(reduction.messages));
                             messages = reduction.messages;
-                            emit("context_reduced", { messages: reduction.truncated });
+                            emit("context_reduced", {
+                                messages: reduction.truncated,
+                                reason: "budget",
+                                tokensSaved,
+                            });
                         }
                     };
                     reduceInPlace();
@@ -1105,7 +1325,49 @@ export class AgentRunner {
                 // Providers only ever see the text projection of tool results: ui/image parts are a
                 // display-only extension of the persisted transcript and never reach a model prompt
                 // (raw image bytes included). The store keeps the rich parts for TUI replay.
-                const providerMessages = messages.map((m) => m.role === "tool" ? { ...m, result: textProjection(m.result) } : m);
+                // Context Governor: `off` costs one property read. `shadow` only measures; `on` sends the
+                // projected history. The stored transcript, the compaction triggers and the limits above
+                // always use the raw `messages`.
+                let sent = messages;
+                let invariantsText = "";
+                const governor = o.contextGovernor;
+                if (governor && governor.mode !== "off") {
+                    const projection = projectContext(messages, governor);
+                    const snapshot = governanceSnapshot(projection, governor, requests + 1, this.governed.get(sessionId));
+                    const block = invariants();
+                    const done = this.promotions.get(sessionId);
+                    snapshot.invariants = {
+                        count: block.included,
+                        chars: block.text.length,
+                        omitted: block.omitted,
+                        promoted: done?.promoted ?? 0,
+                        rejected: done?.rejected ?? 0,
+                    };
+                    this.governed.set(sessionId, snapshot);
+                    // The ledger only measures: a fault in it never fails the request or changes `sent`.
+                    let usageSummary;
+                    try {
+                        const ledger = this.usageLedger(sessionId, workspace);
+                        const stubbed = governor.mode === "on"
+                            ? new Set(projection.elisions.map((e) => e.callId))
+                            : new Set();
+                        ledger.record(ledger.seams + 1, messages, stubbed);
+                        usageSummary = ledger.summary();
+                    }
+                    catch {
+                        /* Advisory numbers only. */
+                    }
+                    emit("context_governed", governedEventData(snapshot, usageSummary));
+                    if (governor.mode === "on") {
+                        sent = projection.messages;
+                        invariantsText = block.text;
+                    }
+                }
+                const providerMessages = sent.map((m) => m.role === "tool" ? { ...m, result: textProjection(m.result) } : m);
+                // The invariants block is the last message: built fresh, never saved, never an elision
+                // candidate (it joins the request after the projection).
+                if (invariantsText)
+                    providerMessages.push({ role: "user", text: invariantsText });
                 // After a cut-off response the request carries a transient continuation notice (never
                 // persisted: the stored transcript only ever holds what the model really answered).
                 if (recoveryNotice)

package/dist/eval/compare.d.ts

@@ -46,7 +46,7 @@ export interface Interval {
     wilsonHigh?: number;
 }
 declare const CHANGED_FIELDS: readonly ["configHash", "model", "harnessVersion", "mode", "provider"];
-declare const MEASURED_KEYS: readonly ["medianWallMs", "varianceWallMs", "varianceTokens", "tokensPerSuccess", "wallMsPerSuccess"];
+declare const MEASURED_KEYS: readonly ["medianWallMs", "varianceWallMs", "varianceTokens", "tokensPerSuccess", "wallMsPerSuccess", "cachedInputRatio"];
 type MeasuredKey = (typeof MEASURED_KEYS)[number];
 export interface TaskComparison {
     taskId: string;

package/dist/eval/compare.js

@@ -41,13 +41,18 @@ const MEASURED_KEYS = [
     "varianceTokens",
     "tokensPerSuccess",
     "wallMsPerSuccess",
+    "cachedInputRatio",
 ];
 const delta = (baseline, candidate) => ({
     baseline,
     candidate,
     delta: candidate - baseline,
 });
-const TOKEN_KEYS = ["varianceTokens", "tokensPerSuccess"];
+const TOKEN_KEYS = [
+    "varianceTokens",
+    "tokensPerSuccess",
+    "cachedInputRatio",
+];
 function compareTask(a, b, ctx) {
     const lowPower = a.k < MIN_POWER_K || b.k < MIN_POWER_K;
     const difference = b.successRate.value - a.successRate.value;
@@ -263,6 +268,8 @@ const reportSchema = z.object({
             varianceTokens: z.number().optional(),
             tokensPerSuccess: z.number().optional(),
             wallMsPerSuccess: z.number().optional(),
+            cachedInputRatio: z.number().optional(),
+            cachedInputRuns: z.number().optional(),
         }),
         estimated: z.object({ costUsdPerSuccess: z.number().optional() }).optional(),
     })),
@@ -274,6 +281,15 @@ const reportSchema = z.object({
         budgetExceeded: z.number(),
         runs: z.number().optional(),
         failed: z.number().optional(),
+        cachedInput: z
+            .object({
+            tokens: z.number(),
+            inputTokens: z.number(),
+            ratio: z.number(),
+            runsReporting: z.number(),
+            runsJudged: z.number(),
+        })
+            .optional(),
     }),
     rates: z.object({ inputPerMTokUsd: z.number(), outputPerMTokUsd: z.number() }).optional(),
 });
@@ -315,6 +331,7 @@ const METRIC_LABEL = {
     varianceTokens: "Token variance (main-loop tokens)",
     tokensPerSuccess: "Tokens per success (main-loop tokens, excludes compaction calls)",
     wallMsPerSuccess: "Wall per success (ms)",
+    cachedInputRatio: "Cached input ratio (provider-reported cached / input tokens)",
 };
 const number = (value) => String(Math.round(value * 1000) / 1000);
 function table(headers, rows) {

package/dist/eval/engine.js

@@ -83,6 +83,19 @@ export const CONFIG_HASH_COVERAGE = {
     agents: "excluded",
     web: "excluded",
 };
+/**
+ * The Context Governor keys exist only since spec 012. A switched-off governor with default
+ * settings leaves them out, so the hashes of runs recorded before they existed stay valid.
+ */
+function hashedContext(context) {
+    const { governor, elide, policyVersion, invariants, ...rest } = context;
+    const untouched = governor === "off" &&
+        policyVersion === undefined &&
+        elide.minAgeTurns === 2 &&
+        elide.epochMessages === 32 &&
+        invariants.maxChars === 4000;
+    return untouched ? rest : context;
+}
 /**
  * `sha256:` of the allowlisted effective configuration plus policy, approval mode, budget and
  * enabled built-ins. Excludes secrets, env names, plugin options, absolute paths, endpoints, the
@@ -93,7 +106,7 @@ export function computeConfigHash(config, extras) {
     const picked = {
         limits: config.limits,
         compaction: config.compaction,
-        context: config.context,
+        context: hashedContext(config.context),
         forge: {
             javascript: forge.javascript,
             state: forge.state,
@@ -289,6 +302,10 @@ class RunObserver {
     /** Cumulative tokens reported by the last `turn_completed`. */
     tokens = 0;
     usage;
+    /** Sum of the cached input tokens reported; undefined until a turn reports any. */
+    cachedInput;
+    /** Turns whose usage carried `cachedInput`. */
+    turnsWithCached = 0;
     model;
     timedOut = false;
     turnsExceeded = false;
@@ -311,6 +328,10 @@ class RunObserver {
                     this.usage ??= { input: 0, output: 0 };
                     this.usage.input += usage.input;
                     this.usage.output += usage.output;
+                    if (typeof usage.cachedInput === "number") {
+                        this.turnsWithCached += 1;
+                        this.cachedInput = (this.cachedInput ?? 0) + usage.cachedInput;
+                    }
                 }
                 break;
             }
@@ -386,6 +407,10 @@ class RunObserver {
     get usagePartial() {
         return this.turnsWithUsage > 0 && this.turnsWithUsage < this.turns;
     }
+    /** Some turns that reported usage did not report cached tokens: the cached sum understates. */
+    get cachedPartial() {
+        return this.turnsWithCached > 0 && this.turnsWithCached < this.turnsWithUsage;
+    }
     markAborted() {
         this.bump("run_aborted");
     }
@@ -718,6 +743,11 @@ async function execute(task, opts, plan, fixtureDir) {
         measured: {
             ...(usage ? { inputTokens: usage.input, outputTokens: usage.output } : {}),
             ...(usage && observer.usagePartial ? { usagePartial: true } : {}),
+            // Only the observer sees `cachedInput`; absent stays absent (unknown is not 0).
+            ...(observer.cachedInput !== undefined ? { cachedInputTokens: observer.cachedInput } : {}),
+            ...(observer.cachedInput !== undefined && observer.cachedPartial
+                ? { cachedPartial: true }
+                : {}),
             wallMs,
             turns: observer.turns,
             toolCalls: observer.startedCalls,

package/dist/eval/report.js

@@ -56,6 +56,21 @@ function assertUniform(records, field, hint) {
     if (values.length > 1)
         throw new EvalReportError(`Cannot aggregate runs measured under different ${field}: ${values.map((v) => `"${v}"`).join(", ")}. ${hint}`);
 }
+/** Runs that reported cached input completely: judged, no partial usage, no partial cached sum. */
+function cachedReporters(judged) {
+    return judged.filter((r) => r.measured.cachedInputTokens !== undefined &&
+        !r.measured.cachedPartial &&
+        r.measured.inputTokens !== undefined &&
+        !r.measured.usagePartial);
+}
+function cachedTotals(judged) {
+    const reporters = cachedReporters(judged);
+    if (reporters.length === 0)
+        return undefined;
+    const tokens = sum(reporters.map((r) => r.measured.cachedInputTokens));
+    const inputTokens = sum(reporters.map((r) => r.measured.inputTokens));
+    return { tokens, inputTokens, runsReporting: reporters.length };
+}
 function taskMetrics(taskId, runs, rates) {
     const judged = runs.filter((r) => r.status !== "error");
     const errored = runs.length - judged.length;
@@ -71,6 +86,7 @@ function taskMetrics(taskId, runs, rates) {
     const varianceWallMs = sampleVariance(wallTimes);
     // Same rule as tokensPerSuccess: a spread over the runs that happened to report would mislead.
     const varianceTokens = allReportedUsage ? sampleVariance(tokenSamples) : null;
+    const cached = cachedTotals(judged);
     const measured = {
         ...(medianWallMs === null ? {} : { medianWallMs }),
         ...(varianceWallMs === null ? {} : { varianceWallMs }),
@@ -79,6 +95,13 @@ function taskMetrics(taskId, runs, rates) {
             ? { tokensPerSuccess: sum(tokenSamples) / successes }
             : {}),
         ...(successes > 0 ? { wallMsPerSuccess: sum(wallTimes) / successes } : {}),
+        // A ratio over zero input tokens means nothing: leave it out rather than divide by zero.
+        ...(cached && cached.inputTokens > 0
+            ? {
+                cachedInputRatio: cached.tokens / cached.inputTokens,
+                cachedInputRuns: cached.runsReporting,
+            }
+            : {}),
     };
     const costs = rates ? judged.map((r) => estimateRunCost(r, rates)) : [];
     const costKnown = rates !== undefined && successes > 0 && costs.every((c) => c !== undefined);
@@ -147,6 +170,8 @@ export function buildReport(records, options = {}) {
         ? taskHashes[0][1]
         : `sha256:${createHash("sha256").update(JSON.stringify(taskHashes)).digest("hex")}`;
     const count = (status) => records.filter((r) => r.status === status).length;
+    const judgedRuns = records.filter((r) => r.status !== "error");
+    const armCached = cachedTotals(judgedRuns);
     return {
         schemaVersion: 1,
         suiteId: first.suiteId,
@@ -174,6 +199,17 @@ export function buildReport(records, options = {}) {
             budgetExceeded: count("budget_exceeded"),
             runs: records.length,
             failed: count("fail"),
+            ...(armCached && armCached.inputTokens > 0
+                ? {
+                    cachedInput: {
+                        tokens: armCached.tokens,
+                        inputTokens: armCached.inputTokens,
+                        ratio: armCached.tokens / armCached.inputTokens,
+                        runsReporting: armCached.runsReporting,
+                        runsJudged: judgedRuns.length,
+                    },
+                }
+                : {}),
         },
         ...(options.rates ? { rates: { ...options.rates } } : {}),
     };
@@ -198,6 +234,13 @@ function table(headers, rows) {
 export function lowPowerTasks(report) {
     return report.tasks.filter((t) => t.k < MIN_POWER_K);
 }
+/** The arm's cached-input line: the provider's own figure, or an explicit "not reported". */
+function cachedLine(report) {
+    const c = report.summary.cachedInput;
+    if (!c)
+        return "Cached input: not reported by the provider (no ratio is computed; absent is not zero).";
+    return `Cached input: ${percent(c.ratio)} of input tokens (${count(c.tokens)} of ${count(c.inputTokens)}), from ${c.runsReporting} of ${c.runsJudged} judged runs that reported it.`;
+}
 /** Markdown of a report: conditions, warnings, then Measured and Estimated as separate sections. */
 export function renderReportMarkdown(report) {
     const { conditions: c } = report;
@@ -219,7 +262,7 @@ export function renderReportMarkdown(report) {
     if (weak.length > 0)
         lines.push(`> **Low power:** ${weak.map((t) => `${t.taskId} (k=${t.k})`).join(", ")} ${weak.length === 1 ? "has" : "have"} fewer than ${MIN_POWER_K} judged runs. The intervals are wide; do not read an improvement or a regression from these numbers.`, "");
     const { summary: s } = report;
-    lines.push(`Runs: ${s.runs ?? report.runs.length} (passed ${s.passed}, failed ${s.failed ?? "-"}, budget exceeded ${s.budgetExceeded}, errored ${s.errored}). Errored runs are infrastructure failures: they are excluded from every rate and spread below.`, "", "## Measured", "", "Provider-reported usage and wall time. Success is passes over judged runs, with a 95% Wilson interval; sd is the square root of the sample variance. Token figures are main-loop tokens (excludes compaction calls).", "", table([
+    lines.push(`Runs: ${s.runs ?? report.runs.length} (passed ${s.passed}, failed ${s.failed ?? "-"}, budget exceeded ${s.budgetExceeded}, errored ${s.errored}). Errored runs are infrastructure failures: they are excluded from every rate and spread below.`, "", "## Measured", "", cachedLine(report), "", "Provider-reported usage and wall time. Success is passes over judged runs, with a 95% Wilson interval; sd is the square root of the sample variance. Token figures are main-loop tokens (excludes compaction calls).", "", table([
         "Task",
         "k",
         "Success [Wilson 95%]",

package/dist/forge/javascript/hosts/process-host.d.ts

@@ -4,7 +4,7 @@ export declare const PROCESS_KILL_BACKSTOP_MS = 500;
  * The isolate's whole environment: the marker, and on Windows `SystemRoot` and nothing else (the
  * runtime cannot start without it). No other variable of the parent ever reaches the guest process.
  */
-export declare function isolateEnv(platform?: NodeJS.Platform, parent?: NodeJS.ProcessEnv): Record<string, string>;
+export declare function isolateEnv(platform?: NodeJS.Platform, parent?: NodeJS.ProcessEnv, electron?: boolean): Record<string, string>;
 export interface IsolateCommand {
     execPath: string;
     args: string[];

package/dist/forge/javascript/hosts/process-host.js

@@ -23,8 +23,11 @@ const EXIT_CONFIRM_MS = 2_000;
  * The isolate's whole environment: the marker, and on Windows `SystemRoot` and nothing else (the
  * runtime cannot start without it). No other variable of the parent ever reaches the guest process.
  */
-export function isolateEnv(platform = process.platform, parent = process.env) {
+export function isolateEnv(platform = process.platform, parent = process.env, electron = !!process.versions.electron) {
     const env = { ALISIO_FORGE_ISOLATE: "1" };
+    // The Electron binary only behaves as Node with this flag; it carries no parent data.
+    if (electron)
+        env.ELECTRON_RUN_AS_NODE = "1";
     if (platform === "win32" && parent.SystemRoot)
         env.SystemRoot = parent.SystemRoot;
     return env;

package/dist/forge/python/wasm-node.d.ts

@@ -38,7 +38,7 @@ export declare function permissionArgs(paths: {
     write: readonly string[];
 }): string[];
 /** Environment of the child: nothing but the job's `ALISIO_*` variables. */
-export declare function childEnv(vars: Record<string, string>, platform?: NodeJS.Platform): Record<string, string>;
+export declare function childEnv(vars: Record<string, string>, platform?: NodeJS.Platform, electron?: boolean): Record<string, string>;
 export interface NetworkProbeResult {
     /**
      * The Permission Model refused the connection (`ERR_ACCESS_DENIED`). `false` also when the probe

package/dist/forge/python/wasm-node.js

@@ -126,11 +126,14 @@ export function permissionArgs(paths) {
     ];
 }
 /** Environment of the child: nothing but the job's `ALISIO_*` variables. */
-export function childEnv(vars, platform = process.platform) {
+export function childEnv(vars, platform = process.platform, electron = !!process.versions.electron) {
     const env = {};
     for (const [key, value] of Object.entries(vars))
         if (key.startsWith("ALISIO_"))
             env[key] = value;
+    // The Electron binary only behaves as Node with this flag; it carries no parent data.
+    if (electron)
+        env.ELECTRON_RUN_AS_NODE = "1";
     // Windows cannot start a process without these.
     if (platform === "win32" && process.env.SystemRoot)
         env.SystemRoot = process.env.SystemRoot;