dsh-plugin-coding-delegate 0.0.0-stage → 0.2.2

package/dist/routing.js

@@ -0,0 +1,88 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyDestination = classifyDestination;
+/**
+ * Where an outbound request will actually land, and whether that is allowed.
+ *
+ * Both halves of this decision used to be made by comparing provider IDs, and both fail in the
+ * documented cloud-only setup where `localProvider` and `cloudProvider` are the same id:
+ *
+ *   1. An entropy-only DLP hit forced a local reroute even when `dlpAction` was 'block', so the
+ *      payload was pinned to the cloud it was meant to be kept away from -- and the log said it was
+ *      pinned to the LOCAL worker.
+ *   2. `destination` was then inferred from `provider === localProvider`, which is true in that
+ *      setup, so source egress classified the route as local and ALLOWED source to the cloud.
+ *
+ * The plugin cannot see the architect's endpoint, so where it cannot tell it refuses rather than
+ * guessing. `dlpAction` is an explicit input for the same reason: a caller that pre-computes
+ * "should I reroute" cannot express that 'block' was overridden, which is how half 1 stayed hidden.
+ *
+ * `dlpAction` undefined preserves the previous behaviour deliberately: entropy-only hits reroute,
+ * high-confidence hits do not. Only an explicit 'block' changes that, and only 'local' authorises a
+ * reroute for a high-confidence hit.
+ */
+function classifyDestination(input) {
+    const norm = (s) => String(s || '').trim().toLowerCase();
+    const local = norm(input.localProvider);
+    const cloud = norm(input.cloudProvider);
+    const dest = norm(input.provider);
+    // No local provider, or one that IS the cloud provider, means there is nowhere local to go.
+    const isCloudOnly = !local || (Boolean(cloud) && local === cloud);
+    // 1. Is a reroute to local required, and was it authorised?
+    const wantsReroute = input.dlpTripped &&
+        (input.dlpAction === 'local' || (input.entropyOnly && input.dlpAction !== 'block'));
+    if (wantsReroute) {
+        if (isCloudOnly) {
+            return {
+                destination: 'cloud',
+                decision: 'block',
+                rerouteLocal: false,
+                reason: `Refusing local reroute: localProvider ('${input.localProvider || ''}') is ` +
+                    `identical to cloudProvider or undefined. Cannot guarantee payload isolation.`,
+            };
+        }
+        return {
+            destination: 'local',
+            decision: 'proceed',
+            rerouteLocal: true,
+            reason: 'Rerouted to local provider due to DLP policy.',
+        };
+    }
+    // 2. A tripped DLP with an explicit block policy is refused outright.
+    if (input.dlpTripped && input.dlpAction === 'block') {
+        return {
+            destination: 'cloud',
+            decision: 'block',
+            rerouteLocal: false,
+            reason: 'DLP violation: dlpAction is configured to block.',
+        };
+    }
+    // 2b. A HIGH-CONFIDENCE hit that was not rerouted is refused, at every action setting.
+    //
+    // This clause is not optional and its absence shipped a credential leak in the first wiring attempt:
+    // without it, a high-confidence secret with a DISTINCT local provider and no policy fell through to
+    // step 3, matched `dest === local`, and returned proceed/local -- so the payload passed the gate and,
+    // because it was labelled local, source egress did not stop it either. `dlp-gate.test.cjs` caught it
+    // as "Missing expected rejection"; the reasoning that it was covered by egress did not hold.
+    //
+    // The rule is the one the original expression encoded: only an entropy-only hit, or an explicit
+    // 'local' action, may be rerouted. Everything else a tripped gate found is refused, because a
+    // medium-confidence heuristic is the only thing entitled to a soft landing.
+    if (input.dlpTripped && !input.entropyOnly) {
+        return {
+            destination: 'cloud',
+            decision: 'block',
+            rerouteLocal: false,
+            reason: 'DLP violation: a high-confidence match may only be rerouted when dlpAction is ' +
+                "'local'. It was not, so nothing was transmitted.",
+        };
+    }
+    // 3. No reroute: classify where the payload actually lands. In a cloud-only setup it is cloud
+    //    regardless of whether the provider string happens to equal localProvider.
+    const effectiveDestination = !isCloudOnly && dest === local ? 'local' : 'cloud';
+    return {
+        destination: effectiveDestination,
+        decision: 'proceed',
+        rerouteLocal: false,
+    };
+}

package/dist/savings-tracker.d.ts

@@ -0,0 +1,128 @@
+export interface PricingRates {
+    inputPerMillion: number;
+    inputCachedPerMillion: number;
+    outputPerMillion: number;
+}
+export type RouteType = 'ARCHITECT_CLOUD' | 'WORKER_LOCAL' | 'local' | 'cloud' | 'cloud-failover';
+export interface StepUsage {
+    turn?: number;
+    route: RouteType;
+    model?: string;
+    reason?: string;
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    cacheHitTokens?: number;
+    elapsedMs?: number;
+    /**
+     * What a unit decided, when this record is a delegation rather than a bare model call.
+     *
+     * Absent for anything that is not a unit verdict. Its presence is what makes a record a delegation,
+     * so the ledger counts delegations without parsing the routing reason.
+     */
+    outcome?: string;
+    /** Whether that verdict was a success. The signal that makes absorbed retries countable. */
+    succeeded?: boolean;
+    /** File bytes this unit produced -- content the architect never carried. */
+    bytesWritten?: number;
+}
+export interface TurnRecord {
+    turn: number;
+    timestamp: string;
+    route: RouteType;
+    provider: string;
+    model: string;
+    routingReason: string;
+    promptTokensEst: number;
+    completionTokensEst: number;
+    totalTokensEst: number;
+    cacheHitRateEst: number;
+    costUSD: number;
+    /**
+     * What these tokens would have cost at the metered tier. NOT a saving: the local GPU is a fixed cost
+     * this plugin neither pays for nor reduces. See the audit line in `recordUsage`.
+     */
+    cloudEquivUSD: number;
+    outcome?: string;
+    succeeded?: boolean;
+    bytesWritten?: number;
+    elapsedMs?: number;
+    tokensPerSecond?: number;
+}
+export interface LedgerSummary {
+    totalTurns: number;
+    totalTokens?: number;
+    localTurns: number;
+    cloudTurns: number;
+    architectTurns: number;
+    workerTurns: number;
+    failoverTurns: number;
+    totalLocalTokens: number;
+    totalCloudTokens: number;
+    totalSpendUSD?: number;
+    totalCostUSD: number;
+    /** Cumulative metered-tier equivalent of the delegated work. Not money saved. */
+    totalCloudEquivUSD: number;
+    /** Delegations recorded, and how many of them came back as failures. */
+    delegations?: number;
+    failedDelegations?: number;
+    /**
+     * File bytes produced by delegated work -- content that never entered the architect's context. This,
+     * not any dollar figure, is what the plugin claims: code and churn stay in the worker so the
+     * architect's window holds decisions. See `docs/experiment.md`.
+     */
+    bytesKeptOut?: number;
+    /**
+     * What this file covers. Stated in the file because four of its fields were once read as session-wide
+     * when the ledger only ever records delegated work.
+     */
+    scope?: string;
+    recentEvents?: TurnRecord[];
+    history: TurnRecord[];
+}
+export declare const PRICING: {
+    readonly INPUT_CACHE_HIT: number;
+    readonly INPUT_CACHE_MISS: number;
+    readonly OUTPUT_GENERATION: number;
+    readonly WORKER_LOCAL: 0;
+};
+export declare class SavingsTracker {
+    private ledgerPath;
+    private rates;
+    private activeTurns;
+    constructor(baseDir?: string, rates?: Partial<PricingRates>);
+    private estimateTokens;
+    recordUsage(usage: StepUsage): TurnRecord;
+    startTurn(turn: number, route: RouteType, provider: string, model: string, promptText: string, routingReason?: string): void;
+    updateTurnRoute(turn: number, route: RouteType, provider: string, model: string, routingReason: string): void;
+    accumulateChunk(turn: number, textChunk: string): void;
+    recordCompletionTokens(turn: number, count: number): void;
+    endTurn(turn: number): TurnRecord | null;
+    /**
+     * What this plugin kept out of the architect's context, and what that compounds to.
+     *
+     * The currency is context, not money. Content the worker produced never entered the architect's window,
+     * so it is absent from the call that produced it AND from every later call that carries that window
+     * forward. The second part is the whole claim: keeping it out stops it accumulating, so the figure is
+     * `tokensKeptOut x modelCalls` rather than `tokensKeptOut`.
+     *
+     * It is an UPPER BOUND, and it says so, because it assumes every byte produced so far rode every call
+     * counted. A byte produced late rode fewer. The plugin cannot do better without recording, per
+     * delegation, how many calls had already happened -- and an unlabelled bound is exactly the kind of
+     * number this project keeps having to retract.
+     */
+    contextHygiene(modelCalls: number): {
+        delegations: number;
+        failedDelegations: number;
+        bytesKeptOut: number;
+        tokensKeptOut: number;
+        modelCalls: number;
+        carriedTokens: number;
+        line: string;
+    };
+    /** The last ledger written or read in this process, so the summary does not re-read the file. */
+    private lastLedger;
+    /** Read the ledger from disk once, for a process that has not written one yet. */
+    private readLedger;
+    private persist;
+}

package/dist/savings-tracker.js

@@ -0,0 +1,340 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SavingsTracker = exports.PRICING = void 0;
+const fs = __importStar(require("fs"));
+const os = __importStar(require("os"));
+const path = __importStar(require("path"));
+/** Ledger location fallback: derive it, never hard-code a machine-specific path. */
+function defaultLedgerDir() {
+    const dshHome = process.env.DSH_HOME;
+    if (dshHome && dshHome.trim())
+        return path.join(dshHome.trim(), 'local-router');
+    return path.join(os.homedir(), '.dsh', 'local-router');
+}
+exports.PRICING = {
+    INPUT_CACHE_HIT: 0.014 / 1_000_000,
+    INPUT_CACHE_MISS: 0.14 / 1_000_000,
+    OUTPUT_GENERATION: 0.28 / 1_000_000,
+    WORKER_LOCAL: 0,
+};
+class SavingsTracker {
+    ledgerPath;
+    rates;
+    activeTurns = new Map();
+    constructor(baseDir = defaultLedgerDir(), rates) {
+        this.ledgerPath = path.join(baseDir, 'savings-ledger.json');
+        this.rates = {
+            inputPerMillion: rates?.inputPerMillion ?? 0.14,
+            inputCachedPerMillion: rates?.inputCachedPerMillion ?? 0.014,
+            outputPerMillion: rates?.outputPerMillion ?? 0.28,
+        };
+    }
+    estimateTokens(text) {
+        if (!text)
+            return 0;
+        return Math.ceil(text.length / 3.8);
+    }
+    recordUsage(usage) {
+        const turn = usage.turn ?? 1;
+        const route = usage.route || 'ARCHITECT_CLOUD';
+        const model = usage.model || (route === 'WORKER_LOCAL' || route === 'local' ? 'qwen/qwen3.8-27b' : 'deepseek-chat');
+        const reason = usage.reason || 'STEP_COMPLETION';
+        const promptTokens = usage.promptTokens ?? 0;
+        const completionTokens = usage.completionTokens ?? 0;
+        const totalTokens = usage.totalTokens ?? (promptTokens + completionTokens);
+        const cacheHitTokens = Math.min(promptTokens, usage.cacheHitTokens ?? 0);
+        const cacheMissTokens = Math.max(0, promptTokens - cacheHitTokens);
+        let costUSD = 0;
+        let cloudEquivUSD = 0;
+        const isLocal = route === 'WORKER_LOCAL' || route === 'local';
+        if (isLocal) {
+            costUSD = 0;
+            cloudEquivUSD = parseFloat((promptTokens * exports.PRICING.INPUT_CACHE_MISS + completionTokens * exports.PRICING.OUTPUT_GENERATION).toFixed(6));
+        }
+        else {
+            cloudEquivUSD = 0;
+            costUSD = parseFloat((cacheHitTokens * exports.PRICING.INPUT_CACHE_HIT +
+                cacheMissTokens * exports.PRICING.INPUT_CACHE_MISS +
+                completionTokens * exports.PRICING.OUTPUT_GENERATION).toFixed(6));
+        }
+        const cacheHitRateEst = promptTokens > 0 ? parseFloat((cacheHitTokens / promptTokens).toFixed(2)) : 0;
+        const elapsedMs = usage.elapsedMs && usage.elapsedMs > 0 ? usage.elapsedMs : undefined;
+        const tokensPerSecond = elapsedMs !== undefined && completionTokens > 0
+            ? parseFloat((completionTokens / (elapsedMs / 1000)).toFixed(1))
+            : undefined;
+        const record = {
+            turn,
+            timestamp: new Date().toISOString(),
+            route,
+            provider: isLocal ? 'lm-studio' : 'deepseek-official',
+            model,
+            routingReason: reason,
+            promptTokensEst: promptTokens,
+            completionTokensEst: completionTokens,
+            totalTokensEst: totalTokens,
+            cacheHitRateEst,
+            costUSD,
+            cloudEquivUSD,
+            // The verdict, when there is one. Its presence is what marks this record a delegation rather than
+            // a bare model call, which is how the ledger counts delegations and absorbed failures without
+            // having to parse the routing reason.
+            ...(usage.outcome !== undefined ? { outcome: usage.outcome } : {}),
+            ...(usage.succeeded !== undefined ? { succeeded: usage.succeeded } : {}),
+            ...(usage.bytesWritten !== undefined ? { bytesWritten: usage.bytesWritten } : {}),
+            ...(elapsedMs !== undefined ? { elapsedMs } : {}),
+            ...(tokensPerSecond !== undefined ? { tokensPerSecond } : {}),
+        };
+        const ledger = this.persist(record);
+        this.lastLedger = ledger;
+        const rateText = tokensPerSecond !== undefined && elapsedMs !== undefined
+            ? ` | Rate: ${tokensPerSecond} tok/s e2e (${completionTokens} tok in ${(elapsedMs / 1000).toFixed(2)}s)`
+            : '';
+        // 'CloudEquiv', not 'Saved'. The local GPU is a fixed cost this plugin neither pays for nor
+        // reduces, so nothing here is money saved: a local card does not pay for itself against a
+        // metered plan. This figure is what those tokens would have cost at the metered tier, which
+        // measures the plan's exposure rather than a saving.
+        const auditMsg = `[LEDGER_AUDIT] Step ${turn} [${route.toUpperCase()}] -> Model: ${model} | Reason: ${reason} | Tokens: ${totalTokens} (Prompt: ${promptTokens}, Completion: ${completionTokens}, CacheHit: ${cacheHitTokens})${rateText} | Cost: $${costUSD.toFixed(6)} | CloudEquiv: $${cloudEquivUSD.toFixed(6)} | Metered: ${ledger.totalCloudTokens} tok | Local: ${ledger.totalLocalTokens} tok | Delegations: ${ledger.delegations ?? 0} (failed ${ledger.failedDelegations ?? 0}) | Kept out: ${ledger.bytesKeptOut ?? 0} B`;
+        console.log(auditMsg);
+        return record;
+    }
+    startTurn(turn, route, provider, model, promptText, routingReason = 'STANDARD_ROUTING') {
+        this.activeTurns.set(turn, {
+            route,
+            provider,
+            model,
+            routingReason,
+            promptText,
+            completionText: '',
+        });
+    }
+    updateTurnRoute(turn, route, provider, model, routingReason) {
+        const active = this.activeTurns.get(turn);
+        if (active) {
+            active.route = route;
+            active.provider = provider;
+            active.model = model;
+            active.routingReason = routingReason;
+            active.completionText = '';
+            delete active.exactCompletionTokens;
+        }
+    }
+    accumulateChunk(turn, textChunk) {
+        const active = this.activeTurns.get(turn);
+        if (active && textChunk) {
+            active.completionText += textChunk;
+        }
+    }
+    recordCompletionTokens(turn, count) {
+        const active = this.activeTurns.get(turn);
+        if (active && count > 0) {
+            active.exactCompletionTokens = count;
+        }
+    }
+    endTurn(turn) {
+        const active = this.activeTurns.get(turn);
+        if (!active)
+            return null;
+        this.activeTurns.delete(turn);
+        const promptTokens = this.estimateTokens(active.promptText);
+        const completionTokens = active.exactCompletionTokens ?? this.estimateTokens(active.completionText);
+        const totalTokens = promptTokens + completionTokens;
+        return this.recordUsage({
+            turn,
+            route: active.route,
+            model: active.model,
+            reason: active.routingReason || 'TURN_COMPLETION',
+            promptTokens,
+            completionTokens,
+            totalTokens,
+        });
+    }
+    /**
+     * What this plugin kept out of the architect's context, and what that compounds to.
+     *
+     * The currency is context, not money. Content the worker produced never entered the architect's window,
+     * so it is absent from the call that produced it AND from every later call that carries that window
+     * forward. The second part is the whole claim: keeping it out stops it accumulating, so the figure is
+     * `tokensKeptOut x modelCalls` rather than `tokensKeptOut`.
+     *
+     * It is an UPPER BOUND, and it says so, because it assumes every byte produced so far rode every call
+     * counted. A byte produced late rode fewer. The plugin cannot do better without recording, per
+     * delegation, how many calls had already happened -- and an unlabelled bound is exactly the kind of
+     * number this project keeps having to retract.
+     */
+    contextHygiene(modelCalls) {
+        // Read once if this process has not written a ledger yet, so the first turn of a session does not
+        // report zeros while the file already holds real totals. A figure that reads zero looks like a
+        // measurement and is not one.
+        if (!this.lastLedger)
+            this.lastLedger = this.readLedger();
+        const ledger = this.lastLedger;
+        const delegations = ledger?.delegations ?? 0;
+        const failedDelegations = ledger?.failedDelegations ?? 0;
+        const bytesKeptOut = ledger?.bytesKeptOut ?? 0;
+        // The same estimator this file already applies to text.
+        const tokensKeptOut = Math.ceil(bytesKeptOut / 3.8);
+        const calls = Number.isFinite(modelCalls) && modelCalls > 0 ? Math.floor(modelCalls) : 0;
+        const carriedTokens = tokensKeptOut * calls;
+        return {
+            delegations,
+            failedDelegations,
+            bytesKeptOut,
+            tokensKeptOut,
+            modelCalls: calls,
+            carriedTokens,
+            line: delegations +
+                ' delegation(s) [cumulative], ' +
+                failedDelegations +
+                ' failed attempt(s) absorbed, ' +
+                bytesKeptOut +
+                ' B kept out (~' +
+                tokensKeptOut +
+                ' tok); over ' +
+                calls +
+                ' model call(s) an upper bound of ' +
+                carriedTokens +
+                ' token(s) never carried',
+        };
+    }
+    /** The last ledger written or read in this process, so the summary does not re-read the file. */
+    lastLedger = null;
+    /** Read the ledger from disk once, for a process that has not written one yet. */
+    readLedger() {
+        try {
+            if (!fs.existsSync(this.ledgerPath))
+                return null;
+            return JSON.parse(fs.readFileSync(this.ledgerPath, 'utf8'));
+        }
+        catch {
+            return null;
+        }
+    }
+    persist(record) {
+        let ledger = {
+            totalTurns: 0,
+            totalTokens: 0,
+            localTurns: 0,
+            cloudTurns: 0,
+            architectTurns: 0,
+            workerTurns: 0,
+            failoverTurns: 0,
+            totalLocalTokens: 0,
+            totalCloudTokens: 0,
+            totalSpendUSD: 0,
+            totalCostUSD: 0,
+            totalCloudEquivUSD: 0,
+            delegations: 0,
+            failedDelegations: 0,
+            bytesKeptOut: 0,
+            scope: '',
+            recentEvents: [],
+            history: [],
+        };
+        try {
+            if (fs.existsSync(this.ledgerPath)) {
+                const raw = fs.readFileSync(this.ledgerPath, 'utf8');
+                ledger = JSON.parse(raw);
+            }
+        }
+        catch { }
+        // Carried forward from the name this used to have. The name was wrong, not the number: the local GPU
+        // is a fixed cost, so nothing here is money saved. Losing the history to a rename would be its own
+        // small dishonesty.
+        if (ledger.totalCloudEquivUSD === undefined && ledger.totalSavedUSD !== undefined) {
+            ledger.totalCloudEquivUSD = ledger.totalSavedUSD;
+        }
+        delete ledger.totalSavedUSD;
+        ledger.totalTurns += 1;
+        ledger.totalTokens = (ledger.totalTokens || 0) + record.totalTokensEst;
+        if (record.route === 'WORKER_LOCAL' || record.route === 'local') {
+            ledger.localTurns += 1;
+            if (record.route === 'WORKER_LOCAL')
+                ledger.workerTurns = (ledger.workerTurns || 0) + 1;
+            ledger.totalLocalTokens += record.totalTokensEst;
+            ledger.totalCloudEquivUSD = parseFloat(((ledger.totalCloudEquivUSD || 0) + record.cloudEquivUSD).toFixed(6));
+        }
+        else if (record.route === 'cloud-failover') {
+            ledger.failoverTurns = (ledger.failoverTurns || 0) + 1;
+            ledger.totalCloudTokens += record.totalTokensEst;
+            ledger.totalCostUSD = parseFloat(((ledger.totalCostUSD || 0) + record.costUSD).toFixed(6));
+            ledger.totalSpendUSD = ledger.totalCostUSD;
+        }
+        else {
+            ledger.cloudTurns += 1;
+            if (record.route === 'ARCHITECT_CLOUD')
+                ledger.architectTurns = (ledger.architectTurns || 0) + 1;
+            ledger.totalCloudTokens += record.totalTokensEst;
+            ledger.totalCostUSD = parseFloat(((ledger.totalCostUSD || 0) + record.costUSD).toFixed(6));
+            ledger.totalSpendUSD = ledger.totalCostUSD;
+        }
+        // Context hygiene, not money. These count what the architect never had to carry: content the worker
+        // produced, and attempts that came back as failures. The compounding is the point -- what is kept out
+        // of the window is kept out of every later call, not only the one that produced it.
+        if (record.outcome !== undefined) {
+            ledger.delegations = (ledger.delegations || 0) + 1;
+            // Only a genuine failure. `succeeded === false` also covers an UNVERIFIED unit, which this plugin
+            // distinguishes everywhere else -- and counting those would make the "churn the architect never saw"
+            // figure meaningless, because an unverified edit is the common case rather than the exception.
+            if (record.outcome === 'UNIT_FAILED') {
+                ledger.failedDelegations = (ledger.failedDelegations || 0) + 1;
+            }
+        }
+        if (record.bytesWritten) {
+            ledger.bytesKeptOut = (ledger.bytesKeptOut || 0) + record.bytesWritten;
+        }
+        // Stated in the file, because four of these fields were once read as session-wide when the ledger has
+        // only ever recorded delegated work. A measurement whose scope is implicit will be misread.
+        ledger.scope =
+            'cumulative across sessions; records delegated worker calls only. Architect usage is NOT recorded here ' +
+                '-- cloudTurns, architectTurns, totalCloudTokens and totalSpendUSD are always zero because the host ' +
+                'events that would feed them do not exist or carry no usage. The architect side is measured as ' +
+                'context by context-quality.ts off session/event, not as money.';
+        ledger.history.push(record);
+        if (ledger.history.length > 500) {
+            ledger.history = ledger.history.slice(-500);
+        }
+        ledger.recentEvents = ledger.history.slice(-50);
+        try {
+            fs.mkdirSync(path.dirname(this.ledgerPath), { recursive: true });
+            fs.writeFileSync(this.ledgerPath, JSON.stringify(ledger, null, 2), 'utf8');
+        }
+        catch (err) {
+            console.error('[SAVINGS_TRACKER] Failed to write ledger:', err);
+        }
+        return ledger;
+    }
+}
+exports.SavingsTracker = SavingsTracker;

package/dist/session-events.d.ts

@@ -0,0 +1,17 @@
+import type { SessionEventMap } from '@deepseek-ai/dsh-session';
+/**
+ * Events `foldContextQuality` reads. Every one of these has a `case` in that switch.
+ */
+declare const OBSERVED_EVENT_TYPES: readonly ["turn/start", "step/start", "compaction/summary", "compaction/prune", "compaction/end", "assistant/message", "request/context"];
+/** One of the observed events, carrying the HOST's payload type for it rather than `any`. */
+export type ObservedSessionEvent = {
+    [K in (typeof OBSERVED_EVENT_TYPES)[number]]: {
+        type: K;
+        data: SessionEventMap[K];
+    };
+}[(typeof OBSERVED_EVENT_TYPES)[number]];
+/** Runtime membership for the fold's vocabulary. `ReadonlySet<string>` so a plain `string` may be tested. */
+export declare const OBSERVED_EVENTS: ReadonlySet<string>;
+/** Runtime membership for the traced subset, tested against the same plain `string` a firehose delivers. */
+export declare const TRACED_EVENTS: ReadonlySet<string>;
+export {};

package/dist/session-events.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TRACED_EVENTS = exports.OBSERVED_EVENTS = void 0;
+/**
+ * Events `foldContextQuality` reads. Every one of these has a `case` in that switch.
+ */
+const OBSERVED_EVENT_TYPES = [
+    'turn/start',
+    'step/start',
+    'compaction/summary',
+    'compaction/prune',
+    'compaction/end',
+    'assistant/message',
+    'request/context',
+];
+/**
+ * The subset worth a trace line. `step/start` is folded but deliberately not traced: it fires once per
+ * model call, and this plugin reads its own live evidence out of that log.
+ */
+const TRACED_EVENT_TYPES = [
+    'turn/start',
+    'assistant/message',
+    'request/context',
+    'compaction/summary',
+    'compaction/prune',
+    'compaction/end',
+];
+/** Runtime membership for the fold's vocabulary. `ReadonlySet<string>` so a plain `string` may be tested. */
+exports.OBSERVED_EVENTS = new Set(OBSERVED_EVENT_TYPES);
+/** Runtime membership for the traced subset, tested against the same plain `string` a firehose delivers. */
+exports.TRACED_EVENTS = new Set(TRACED_EVENT_TYPES);